feat(ui): keep writes durable through temporary disconnects (#17960)

<!-- entire-trail-link-start -->
https://entire.com/gh/paperclipai/-/trails/123/changes/paperclip/123
<!-- entire-trail-link-end -->

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - People save tasks, write documents, make decisions and send board
messages.
> - A disconnect can hide a response after the server accepts a write.
> - Recovery must keep the original account, task and request key.
> - The merged connection foundation in #15754 handles reads and shared
outage state.
> - This change adds bounded write recovery and explicit actions when
recovery stops.

## Linked Issues or Issue Description

**What happened?**

Temporary failures could lose edits, report accepted writes as failures,
or require people to copy and send input again. A retry could target a
newly selected task or account. Restoring attachments could create a
second task.

**Expected behavior**

Keep the draft, its owner and its target. Retry only operations with a
server contract that prevents duplicate writes. Verify uncertain
results. Show conflicts and permanent failures, with an explicit resend
or cancel action.

**Steps to reproduce**

1. Save a task title during an outage, then open another task before
recovery.
2. Restore a task creation that needs files, selecting those files in
another order.
3. Lose a document or decision response, then interrupt the verification
read.
4. Switch accounts while a create, upload or connected-channel
publication is pending.
5. Type and erase a new-task draft before the first account lookup
completes, then reopen it.

This PR carries the write layer from #15769 and its review fixes. It
targets master after #15754 merged. Related test cleanup #16952 already
covers the unchanged copy-link toast test; this PR does not duplicate
that work.

## What Changed

- Add bounded autosave and submit jobs for supported writes, with
pending, conflict and manual retry states. Retain admitted autosaves
after navigation and preserve newer task revisions.
- Keep each job with its original account, task and operation. First
account resolution adopts admitted startup work; a later account change
cancels old work. Remount inline and document editors when their owner
or document subject changes.
- Preserve task-creation keys and immutable request snapshots through
file reattachment. Restore generated document keys before comparing
reselected files. Reject changed requests instead of creating a second
task.
- Check the original account scope before creates and each upload. Save
successful upload receipts before stopping on an account change.
Identify attachments by content digest and metadata.
- Verify uncertain document and decision results. Replay only plain,
keyed comments automatically; combined reassignment, reopen and
run-setting changes require receipt reconciliation or cancel. Settle
each request once when a receipt races its retry.
- Scope drafts and connected-channel publication reads to their owner.
Keep unowned older records unread and unreplayed, with an explicit
confirmed discard action after Activity inspection. Preserve typing
through the first session lookup, keep erased text erased, and report
browser persistence only when storage succeeds.
- Wait for the first account lookup before sending startup status
changes or decisions. Retry failed required lookups with a fixed limit
and surface exhaustion to the original action. Preserve uncertain
comment keys on account cancellation. Check the account generation
before a comment retry calls its sender and again immediately before
POST after asynchronous preparation. Retire only that request’s
optimistic echo on completion.
- Return an ordinary comment’s accepted same-company, same-task,
same-user receipt before workspace reopening, task status changes or
wakeups. Reused keys with changed text still conflict. Complete
reference and activity records through the same finalizer for initial
sends and accepted retries. It locks the task before its comment,
matching task and company deletion, comment removal and tombstoning,
rejects removed or tombstoned comments, repairs references and inserts a
missing activity record in one transaction, and publishes after commit.
- Remove reader-only record and comment-body size caps so accepted
browser writes remain readable, including JSON-escaped comment requests
in local and session storage. Update four existing Storybook fixtures to
use owned draft keys.
- Document the write contracts and add regression and real browser
recovery coverage.

- Add the exact reviewed-save recovery regression for both composer
implementations and reloads. Align receipt completion, both comment
deletion methods and company deletion with task deletion by locking
tasks first. Cover real task and company deletion races.

## Verification

- The exact reviewed-unknown-save regression fails in all four cases on
original commit `1ed0af4186`. It passes with this PR for both composers,
before and after reload. Cancel keeps the text and uploaded receipt. The
retained draft sends, and the next message also sends. Run `pnpm exec
vitest run --project @paperclipai/ui
ui/src/components/composer-recovery.test.tsx`.
- The new real PostgreSQL task-deletion race fails with SQLSTATE `40P01`
on parent commit `f3253a00c4`. The company-deletion race also fails with
`40P01` on `e8cf0e02dd`. All six receipt tests pass after the final
lock-order fixes. They cover company deletion, task deletion, comment
removal, tombstoning, concurrent cross-task references and interrupted
reference repair. Run `pnpm exec vitest run --project
@paperclipai/server
server/src/__tests__/issue-comment-receipt-postgres.test.ts`.
- The full UI run passed 9,656 of 9,659 tests across 816 files. Three
cases failed under that run: two large-tree timeouts and one
plugin-panel assertion. All 67 tests in those two files passed in an
isolated rerun. These failures remain recorded; this does not claim a
clean full UI run.
- `pnpm -r typecheck`, `pnpm build`, token gates and map checks pass on
the final change. The local full repository test command was started,
then stopped when the delivery moved to this existing PR. Fresh PR CI
must provide the full-suite gate.
- A local Storybook walkthrough used the real rich editor. Cancel kept
the restored text, Send cleared it after the simulated save, and a new
draft enabled Send again. Storybook simulates submission; it is not
staging acceptance.
- Earlier verification on `f3253a00c4` recorded five browser journeys
for title saves, cached-task offline recovery, startup recovery,
accepted comment replay and session lookup failure. Those results remain
prior-head evidence. No new staging deployment is claimed.

- On `e8cf0e02dd`, all CI checks passed after one browser-shard rerun.
Its first failure copied page text instead of YAML in an unrelated
agent-configuration test. On final commit `35131d4380`, Greptile is 5/5
with no unresolved review threads. The first CI attempt has two failures
outside this diff: runner close-attachment suspension and
scheduled-retry teardown. The scheduled-retry file passes all 14 tests
in isolation; the isolated runner test still fails locally. The single
standard CI rerun passed both jobs, and the aggregate verification gate
passed. All CI checks are green on `35131d4380`; Apex is 5/5 on that
same commit with no unresolved findings.

## Risks

- Automatic replay requires server duplicate prevention or result
verification. Uncertain combined mutations require receipt observation
or cancel and a fresh intentional send.
- Old unowned form drafts remain stored but are not assigned to an
account. Unowned channel records can be retired after Activity
inspection; this never cancels an accepted remote update.
- Browser storage and hashing can be unavailable. Storage failure is
reported honestly. Without a digest, replay can duplicate an upload
rather than silently drop a selected file.
- Detached autosaves remain bounded and check account ownership on each
attempt. Conflicts or exhaustion retain the draft for explicit recovery.
- No schema, credential or agent permission change is included. This PR
does not claim staging deployment or original-task acceptance.

## Model Used

Anthropic Claude Opus 5.5 (`claude-opus-5-5`) produced the original
implementation with tool use. OpenAI Codex, GPT-6 family, assisted with
restoration, integration, verification and review fixes. This Codex
session does not expose its exact serving model ID or context window
size.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: devinfoley <139239+devinfoley@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Amy (Opus) <claude@users.noreply.github.com>
Co-authored-by: Dotta <bippadotta@protonmail.com>

ui/src/hooks/useUpdateIssueMutation.ts

@@ -0,0 +1,264 @@
+import { useCallback, useMemo, useRef } from "react";
+import {
+  useQueryClient,
+  type MutateOptions,
+  type QueryClient,
+  type QueryKey,
+} from "@tanstack/react-query";
+import { useAccountBoundMutation } from "./useAccountBoundMutation";
+import type { Issue } from "@paperclipai/shared";
+import { describeError, isTransientError } from "@/api/errors";
+import { issuesApi, type IssueUpdateResponse } from "@/api/issues";
+import { useToastActions } from "@/context/ToastContext";
+import { useConnectivityStore } from "@/lib/connectivity";
+import { applyOptimisticIssueFieldUpdate, matchesIssueRef } from "@/lib/optimistic-issue-comments";
+import { queryKeys } from "@/lib/queryKeys";
+
+export interface UpdateIssueVariables {
+  /** Issue id or identifier. */
+  id: string;
+  data: Record<string, unknown>;
+}
+
+/** One cached copy of the issue, as it was before and right after the optimistic update. */
+type IssueRollback = Array<{ queryKey: QueryKey; before: Issue; after: Issue }>;
+
+export interface UpdateIssueContext {
+  refs: ReadonlySet<string>;
+  rollback: IssueRollback;
+}
+
+/**
+ * Fields that carry more than an absolute value: replaying them could post a
+ * second comment or interrupt twice. Updates with any of these never resend
+ * on their own.
+ */
+const NON_REPLAYABLE_FIELDS = ["comment", "interrupt", "attachmentIds", "reopen"] as const;
+
+/** True when sending this update twice has the same effect as once. */
+export function isReplayableIssueUpdate(data: Record<string, unknown>): boolean {
+  return NON_REPLAYABLE_FIELDS.every((field) => !Object.prototype.hasOwnProperty.call(data, field));
+}
+
+function isIssueLike(value: unknown): value is Issue {
+  return !!value && typeof value === "object" && typeof (value as Issue).id === "string";
+}
+
+/**
+ * Apply `update` to every issue inside cached query data of the shapes the
+ * app uses: one issue, an issue list, and infinite pages of lists.
+ */
+export function mapIssuesInQueryData(data: unknown, refs: ReadonlySet<string>, update: (issue: Issue) => Issue): unknown {
+  if (Array.isArray(data)) {
+    let changed = false;
+    const next = data.map((item) => {
+      if (Array.isArray(item)) {
+        const mapped = mapIssuesInQueryData(item, refs, update);
+        if (mapped !== item) changed = true;
+        return mapped;
+      }
+      if (!isIssueLike(item) || !matchesIssueRef(item, refs)) return item;
+      changed = true;
+      return update(item);
+    });
+    return changed ? next : data;
+  }
+  if (data && typeof data === "object" && Array.isArray((data as { pages?: unknown }).pages)) {
+    const infinite = data as { pages: unknown[] };
+    const pages = mapIssuesInQueryData(infinite.pages, refs, update);
+    return pages === infinite.pages ? data : { ...infinite, pages };
+  }
+  if (isIssueLike(data) && matchesIssueRef(data, refs)) return update(data);
+  return data;
+}
+
+/** Optimistically apply `data` to the issue everywhere it is cached; returns what rollback needs. */
+export function applyOptimisticIssueUpdate(
+  queryClient: QueryClient,
+  companyId: string | null | undefined,
+  refs: ReadonlySet<string>,
+  data: Record<string, unknown>,
+): IssueRollback {
+  const rollback: IssueRollback = [];
+  const filters = [
+    { queryKey: ["issues", "detail"] as QueryKey },
+    ...(companyId ? [{ queryKey: ["issues", companyId] as QueryKey }] : []),
+  ];
+  for (const filter of filters) {
+    for (const [queryKey, cached] of queryClient.getQueriesData({ queryKey: filter.queryKey })) {
+      let copy: { before: Issue; after: Issue } | null = null;
+      const next = mapIssuesInQueryData(cached, refs, (issue) => {
+        const after = applyOptimisticIssueFieldUpdate(issue, data) ?? issue;
+        copy ??= { before: issue, after };
+        return after;
+      });
+      if (next === cached || !copy) continue;
+      rollback.push({ queryKey, ...(copy as { before: Issue; after: Issue }) });
+      queryClient.setQueryData(queryKey, next);
+    }
+  }
+  return rollback;
+}
+
+/**
+ * Undo one failed update: only the fields it changed, only on this issue, and
+ * only where its value still shows. Other tasks' rows and newer edits to the
+ * same field (made since, and possibly still sending) stay as they are.
+ */
+export function rollbackOptimisticIssueUpdate(queryClient: QueryClient, refs: ReadonlySet<string>, rollback: IssueRollback) {
+  for (const rows of rollback) {
+    const before = rows.before as unknown as Record<string, unknown>;
+    const after = rows.after as unknown as Record<string, unknown>;
+    const changed = Object.keys(after).filter((field) => !Object.is(after[field], before[field]));
+    if (changed.length === 0) continue;
+    queryClient.setQueryData(rows.queryKey, (current: unknown) =>
+      mapIssuesInQueryData(current, refs, (issue) => {
+        const shown = issue as unknown as Record<string, unknown>;
+        let reverted: Record<string, unknown> | null = null;
+        for (const field of changed) {
+          if (!Object.is(shown[field], after[field])) continue;
+          reverted ??= { ...shown };
+          reverted[field] = before[field];
+        }
+        return (reverted as unknown as Issue | null) ?? issue;
+      }),
+    );
+  }
+}
+
+interface IssueWriteTurn {
+  /** Settles once the previous update to the same issue has settled. */
+  ready: Promise<void>;
+  release: () => void;
+}
+
+/**
+ * Updates to one issue are sent in the order they were made, so a change
+ * still retrying through an outage cannot land after, and overwrite, a newer
+ * one. Updates to different issues never wait for each other.
+ */
+const issueWriteTails = new Map<string, Promise<void>>();
+const issueWriteTurns = new WeakMap<UpdateIssueVariables, IssueWriteTurn>();
+
+function takeIssueWriteTurn(key: string): IssueWriteTurn {
+  const ready = issueWriteTails.get(key) ?? Promise.resolve();
+  let release!: () => void;
+  const settled = new Promise<void>((resolve) => { release = resolve; });
+  const tail = ready.then(() => settled);
+  issueWriteTails.set(key, tail);
+  void tail.then(() => {
+    if (issueWriteTails.get(key) === tail) issueWriteTails.delete(key);
+  });
+  return { ready, release };
+}
+
+export interface UseUpdateIssueMutationOptions {
+  companyId: string | null | undefined;
+  /** Query keys this surface lists issues under; refreshed after every update. */
+  invalidateKeys?: QueryKey[];
+  onSuccess?: (result: IssueUpdateResponse, variables: UpdateIssueVariables) => void;
+  onSettled?: () => void;
+  /** What the user was doing, for error copy. */
+  action?: string;
+}
+
+export interface UpdateIssueMutation {
+  mutate: (
+    variables: UpdateIssueVariables,
+    options?: MutateOptions<IssueUpdateResponse, Error, UpdateIssueVariables, UpdateIssueContext>,
+  ) => void;
+  mutateAsync: (
+    variables: UpdateIssueVariables,
+    options?: MutateOptions<IssueUpdateResponse, Error, UpdateIssueVariables, UpdateIssueContext>,
+  ) => Promise<IssueUpdateResponse>;
+  isPending: boolean;
+  variables: UpdateIssueVariables | undefined;
+}
+
+/**
+ * The one issue-update mutation: optimistic update of every cached copy,
+ * rollback and readable toast on failure, and `meta.replay = "idempotent"`
+ * for absolute-field updates so they pause through an outage and resend on
+ * reconnect instead of failing.
+ */
+export function useUpdateIssueMutation(options: UseUpdateIssueMutationOptions): UpdateIssueMutation {
+  const queryClient = useQueryClient();
+  const { pushToast } = useToastActions();
+  const connectivity = useConnectivityStore();
+  const { companyId, invalidateKeys, onSuccess, onSettled, action = "update the task" } = options;
+
+  const mutationOptions = {
+    waitForTurn: (variables: UpdateIssueVariables) => issueWriteTurns.get(variables)?.ready,
+    mutationFn: (variables: UpdateIssueVariables) => issuesApi.update(variables.id, variables.data),
+    onMutate: async ({ id, data }: UpdateIssueVariables): Promise<UpdateIssueContext> => {
+      const refs = new Set([id]);
+      const cached = queryClient.getQueryData<Issue>(queryKeys.issues.detail(id));
+      if (cached?.id) refs.add(cached.id);
+      if (cached?.identifier) refs.add(cached.identifier);
+      // Stop in-flight reads of this issue and its lists from overwriting the
+      // optimistic value; other issues' reads keep going.
+      await Promise.all([
+        ...[...refs].map((ref) => queryClient.cancelQueries({ queryKey: queryKeys.issues.detail(ref) })),
+        ...(companyId ? [queryClient.cancelQueries({ queryKey: queryKeys.issues.list(companyId) })] : []),
+      ]);
+      return { refs, rollback: applyOptimisticIssueUpdate(queryClient, companyId, refs, data) };
+    },
+    onSuccess: (result: IssueUpdateResponse, variables: UpdateIssueVariables) => {
+      onSuccess?.(result, variables);
+    },
+    onError: (error: Error, _variables: UpdateIssueVariables, context: UpdateIssueContext | undefined) => {
+      if (context) rollbackOptimisticIssueUpdate(queryClient, context.refs, context.rollback);
+      // While the connection banner is up it already explains an outage.
+      if (isTransientError(error) && connectivity.getSnapshot().status !== "online") return;
+      const { title, body } = describeError(error, { action });
+      pushToast({ title, body, tone: "error" });
+    },
+    onFinished: (variables: UpdateIssueVariables) => { issueWriteTurns.get(variables)?.release(); },
+    onSettled: (_result: unknown, _error: unknown, variables: UpdateIssueVariables) => {
+      void queryClient.invalidateQueries({ queryKey: queryKeys.issues.detail(variables.id) });
+      for (const queryKey of invalidateKeys ?? (companyId ? [queryKeys.issues.list(companyId)] : [])) {
+        void queryClient.invalidateQueries({ queryKey });
+      }
+      onSettled?.();
+    },
+  };
+  // Two observers, because `meta` is fixed per mutation: absolute updates may
+  // replay across an outage, anything else fails fast.
+  const replayable = useAccountBoundMutation({ ...mutationOptions, meta: { replay: "idempotent" } });
+  const direct = useAccountBoundMutation(mutationOptions);
+
+  // Stable callbacks: callers list `mutate` in effect and callback deps.
+  const replayableRef = useRef(replayable);
+  replayableRef.current = replayable;
+  const directRef = useRef(direct);
+  directRef.current = direct;
+  const companyIdRef = useRef(companyId);
+  companyIdRef.current = companyId;
+  const queue = (variables: UpdateIssueVariables) => {
+    // A copy, so each call gets its own turn even if a caller reuses variables.
+    const queued = { ...variables };
+    const cached = queryClient.getQueryData<Issue>(queryKeys.issues.detail(variables.id));
+    issueWriteTurns.set(queued, takeIssueWriteTurn(`${companyIdRef.current ?? "none"}:${cached?.id ?? variables.id}`));
+    const mutation = isReplayableIssueUpdate(queued.data) ? replayableRef.current : directRef.current;
+    return { mutation, queued };
+  };
+  const mutate = useCallback<UpdateIssueMutation["mutate"]>((variables, mutateOptions) => {
+    const { mutation, queued } = queue(variables);
+    mutation.mutate(queued, mutateOptions);
+  }, []);
+  const mutateAsync = useCallback<UpdateIssueMutation["mutateAsync"]>((variables, mutateOptions) => {
+    const { mutation, queued } = queue(variables);
+    return mutation.mutateAsync(queued, mutateOptions);
+  }, []);
+  const latest = (replayable.submittedAt ?? 0) >= (direct.submittedAt ?? 0) ? replayable : direct;
+
+  return useMemo(
+    () => ({
+      mutate,
+      mutateAsync,
+      isPending: replayable.isPending || direct.isPending,
+      variables: latest.variables,
+    }),
+    [direct.isPending, latest.variables, mutate, mutateAsync, replayable.isPending],
+  );
+}