diff --git a/docs/superpowers/research/2026-09-08-post-merge-regression-audit.md b/docs/superpowers/research/2026-09-08-post-merge-regression-audit.md
new file mode 100644
index 00000000..2500cded
--- /dev/null
+++ b/docs/superpowers/research/2026-09-08-post-merge-regression-audit.md
@@ -0,0 +1,686 @@
+# Post-merge regression audit — 2026-09-08
+
+Scope: `git diff 3256e06a~1..HEAD` on `main`, covering PR #834
+(quota-independent provider switch), #836 (agent names), #838 (agent terminal
+follow) and #840 (API key vault), plus whatever the four reported symptoms
+turned out to actually be.
+
+Written after four parallel read-only investigations. Everything below is
+either CONFIRMED (a concrete input traced to a wrong output) or explicitly
+labelled as suspicion. Fixed items say which commit. Unfixed items say why.
+
+---
+
+## The four reported symptoms
+
+### 1. "The key vault has no padding" — FIXED
+
+Two independent causes in `KeyVaultModal.tsx`.
+
+`DialogContent` carries **no padding by design**. The primitive owns layout
+only; `DialogHeader` and `DialogFooter` each supply `px-4 py-3`, and every
+other feature modal pads its own body — `ViewPromptsModal` and
+`RewindToPromptModal` both use `min-h-0 flex-1 overflow-y-auto px-4 py-3`.
+The vault modal used `DialogHeader` and then hung the provider list, key rows,
+warning banners and the footnote directly off `DialogContent`, so only the
+header was ever padded.
+
+Separately, the header passed `flex-row items-center justify-between gap-4`
+**without `flex`**. `DialogHeader`'s base class list is a plain block, so all
+four of those classes were inert and "Lock now" stacked under the description
+instead of sitting opposite the title.
+
+Three further things were wrong inside the same blast radius and were fixed
+with it: banners, key rows and the key form used `bg-surface`, which is the
+dialog's own background, so they rendered as invisible fills; the two-column
+row had `overflow-y-auto` on itself *and* both children, scrolling the
+provider list away with the key list; and the banners used bare `rounded`
+instead of the `rounded-slab` token.
+
+### 2. "All my Claude sessions came up as Error" — EXPLAINED, diagnosis FIXED
+
+**Not a regression from any of the four merges.** The spawn/recover/rehydrate
+path is not in the diff range at all — `src/main/sessionManager.ts` and
+`hook/persistence/rehydrate.ts` do not appear in `git diff --name-only
+3256e06a~1..HEAD`.
+
+The incident journal for that launch
+(`~/.config/agent-code/incidents/runs/2026-09-08T13-52-08-243Z-…`) shows
+`rehydrate.complete ok:true` for both windows, then 20 × `wake.result
+{ok:false, code:"start-failed", durationMs:~80}` starting two minutes later as
+agents were opened from Dispatch. Per session: `provider.start.end ok:true` in
+15ms, then `gate.eval {gate:"terminal", reason:"exited", elapsedMs:0}`.
+`feed-debug` shows `session exited code=1` on every retry.
+
+All six failing sessions resolved to three directories —
+`~/Desktop/Development/bringdown-engine-{settlement,cli-first,fixtures}` —
+none of which exist. `git worktree list` reports every `bringdown-engine-*`
+worktree as prunable, and `~/Desktop/Development` has an mtime 33 minutes
+before the app launched.
+
+**Mechanism:** node-pty performs the chdir *inside the forked child*
+(`node_modules/node-pty/src/unix/pty.cc`: `if (chdir(cwd_) == -1) _exit(1)`).
+A deleted directory therefore produces a successful PTY creation followed by
+an immediate exit(1), and every layer above reports good news on the way up.
+The failure only surfaced later as the readiness wait giving up with "agent
+exited before it became ready for input (start-failed)", which named neither
+the cause nor the folder.
+
+There was no cwd existence check anywhere on the spawn path. There is now, in
+`spawnWithId` — the one funnel both `spawn()` and `recover()` pass through —
+and `recover()` surfaces it as `Workspace folder is missing: <path>`, marked
+non-retryable so Dispatch stops re-spawning it.
+
+This will keep happening, because worktree-per-branch is the standing
+workflow: **34 of the 73 persisted rows in the current `workspace.json` are
+detached records.** The fix makes it legible, not impossible.
+
+### 3. "Jump to latest does not work for OpenCode" — DIAGNOSED, NOT FIXED
+
+Needs a decision. See "Open decisions" below.
+
+The command palette entry **does** work for OpenCode; the `End` key does not.
+`jump-latest-message` is the app's only `context: 'feed'` binding
+(`features/command-keybindings/defaults.ts:182`), and both halves of the
+`feedFocused` predicate at `tile-tree/useKeybinds.ts:697-708` are false on an
+OpenCode terminal pane:
+
+- `renderedAgentSurfaceIsVisible` delegates to `getEffectiveAgentSurface`,
+  which returns `'terminal'` unconditionally for `providerRuntime ===
+  'terminal'` (`agentDisplayMode.ts:70`). OpenCode Terminal can never be on
+  the rendered surface, so this is false 100% of the time for that provider.
+- `isTextEditingTarget` returns true for any `HTMLTextAreaElement`, and
+  xterm's focused element is `.xterm-helper-textarea`.
+
+It hits any raw agent terminal, but Claude and Codex default to the rendered
+feed, so OpenCode Terminal is the only session type that is *always* on the
+excluded surface.
+
+PR #838 fixed the palette-admission half (dropped `renderedViewPolicy` from
+`paneCommands.ts`) and the scroll half (`agentTerminalFollow.ts` consumes
+`scrollToLatestRequest`). It never touched the keybinding router — the plan
+doc lists five files and neither `useKeybinds.ts` nor `defaults.ts` is among
+them, and the PR's own test file says "This task does not touch `when`."
+Issue #837 promised the opposite: "Scope is Claude/Codex raw views and
+OpenCode Terminal."
+
+`toggle-tail` already reaches raw terminals because it is `Alt+F` in
+`context: 'global'`, which is the shape of one of the two options.
+
+**Unverified caveat:** if the OpenCode TUI runs on xterm's alternate screen,
+`term.scrollToBottom()` is a no-op regardless of keybindings, and neither
+route will ever work. `packages/opencode-headless/research/07-tui-and-screen-
+surface.md:55` describes OpenTUI as rendering into the alternate screen, but
+`vendor/in_progress/opencode/.../tui/app.tsx:73` sets `externalOutputMode:
+"passthrough"`, which points the other way. **Disambiguate by scrolling that
+pane with the mouse wheel:** if scrollback works, it is the normal buffer and
+the keybinding gate is the whole story.
+
+### 4. Terminal-view rendering corruption — ONE OF THREE CAUSES FIXED
+
+Three independent contributors. Only one is from a recent merge.
+
+**(a) The agent-name row resized every pane after mount — FIXED, and this one
+is ours.** A name arrives over IPC well after the pane mounts.
+`AgentTitleHeader` keyed the row's *existence* on the name, so with Agent
+names on, every named pane mounted with no row, fitted tall, told the PTY
+`rows: N`, then grew a ~23px row when the reply landed, refitted, and sent
+`rows: N-1` as a SIGWINCH into a live, mid-output TUI. Ink and the Claude Code
+TUI erase a line count computed for the pre-resize frame, so the redraw lands
+on the wrong region and leaves garbled fragments in the scrollback
+permanently. New behaviour from `2b529300`: before it, the row existed only
+for explicitly-titled agents, so an untitled agent never changed height. The
+row now reserves its box from first paint whenever names are enabled for an
+agent-kind session.
+
+**(b) The WebGL texture atlas — the likeliest dominant cause. NOT FIXED,
+needs a decision.** See "Open decisions".
+
+`@xterm/addon-webgl` is pinned at `0.19.0` and was switched on for
+`AgentTerminalLeaf` in `3b885068` on 2026-09-04. Issue #789 was filed the next
+day describing near-identical symptoms, and its fix `082d845f` is an admitted
+workaround whose own comment cites upstream xterm.js #5883/#6038 and ends
+"The exact reported screenshot still needs user confirmation after
+deployment." #789 was closed without that confirmation.
+
+Upstream #5883 (merged 2026-05-21) fixes two bugs, and its description is the
+reported symptom verbatim: "garbled or garbage characters", "characters
+sampling from incorrect texture pages", "ghost glyphs and misplaced text
+during heavy streaming workloads".
+
+1. Stale texture binding after an atlas page merge: a fresh page replaces the
+   old one **at the same index**, and per-page version counters made
+   same-index swaps undetectable.
+2. Stale vertex buffer after a mid-update merge: `_requestClearModel` was set
+   but never reset.
+
+The local workaround subscribes to `onAddTextureAtlasCanvas` /
+`onRemoveTextureAtlasCanvas` and calls `invalidateTextureBindings()` +
+`refresh()`. That can address bug 1's symptom but cannot replicate bug 2's fix
+or the bounded retry loop upstream added inside `renderRows()`, because both
+live below the addon's public surface. This is consistent with the corruption
+still being reported.
+
+The fix ships in `@xterm/addon-webgl@0.20.0-beta.219` and later. **There is
+still no stable 0.20.0** — latest published is `0.20.0-beta.300`.
+
+Character-level evidence favours this over any dimension mismatch: the
+screenshot has junk substituted at single space positions
+("Nowvgatheringcthe#recent-changeecontext0") and single characters replaced
+mid-word ("the .uck? theretis like noopadding"). A PTY geometry mismatch
+cannot punch one character out of the middle of a word — a TUI writes whole
+strings. Stale texture coordinates render whatever glyph now occupies that
+atlas slot, which is exactly why fragments of nearby text reappear scattered.
+
+**(c) Attach replay is parsed at 80×24 before the first fit — NOT FIXED,
+pre-existing, tracked as #766.** `AgentTerminalOwnership.tsx:107-108` starts
+`handoffComplete` false, so the first commit renders the leaf inside a
+`hidden` div. `dimensionActive` is therefore false when the mount effect runs
+and `scheduleFitAndResizeBackend()` is skipped, so `term.open(container)`
+measures a hidden box and xterm stays at its default 80×24. `attachAgentPty`
+resolves a few ms later and `forwarder.replay(...)` writes up to 512 KiB
+immediately, while the first real `fit.fit()` only runs from a later
+`requestAnimationFrame`. The raw PTY history is therefore normally parsed at
+80 columns and then reflowed mid-parse. Absolute cursor-positioning sequences
+in the replay land on the wrong cells.
+
+Minimal fix: gate `forwarder.replay(...)` on a "has been fitted at least once"
+latch, queueing the buffer the way `backlogQueue` already does. Issue #766
+proposes removing the raw replay entirely, which subsumes it.
+
+---
+
+## Also fixed in this branch
+
+These were found while auditing and are not among the reported symptoms.
+
+- **Seven agent-name reconciler tests had never passed.**
+  `createSettingsStorage`'s "storage unavailable" guard only caught a *thrown*
+  access. Under `happy-dom`, `localStorage` is defined-but-undefined, so the
+  assignment succeeded, a live adapter was returned, and every store write
+  died inside Zustand's persist middleware with "storage.setItem is not a
+  function". The agent-name reconciliation those tests were written to protect
+  has therefore never actually been verified. The guard now checks the object
+  is a usable `Storage`.
+
+- **The first insertion into any pane that needed waking always failed.**
+  `deliverTextToSession` and both prompt-template paths use the session-meta
+  object's identity as their "is my target still the same pane?" token across
+  the await. `ensureSessionLive` replaced that object on *every* wake, even a
+  no-op one, so the guard read "the pane changed" and cancelled. The retry
+  worked because no wake was needed by then. Now identity-preserving on a
+  genuine no-op.
+
+- **Plain terminal panes rendered no pane toast at all.** `TerminalLeaf`
+  called `showPaneToast` but never rendered `PaneToast`. #840 made terminal
+  panes valid insertion targets and routed all of that feature's feedback
+  through pane toasts, so on a shell pane a failed insertion produced nothing
+  observable — and the palette does not close on failure.
+
+- **A bulk provider-switch return destroyed the batch even when nothing
+  returned.** The modal is the only return affordance in the app. Arrival
+  compaction is on by default for large conversations and blocks returns for
+  minutes per pane, so a return attempted in that window returned zero agents
+  and binned the record. Now trimmed to the unreturned agents and cleared only
+  when empty. This module had no test file at all; it has one now.
+
+---
+
+## Decisions taken
+
+### D1. Jump to Latest on OpenCode — RESOLVED, and it was not a keybinding
+
+The keybinding analysis was correct but beside the point. A follow-up
+investigation established that an OpenCode Terminal pane runs OpenTUI with
+`screenMode` defaulting to `alternate-screen`, and renders its transcript into
+an internal scrollbox with its own paging keybinds. Nothing is ever evicted
+upward, so `viewportY === baseY` always holds and `term.scrollToBottom()` — the
+entire jump implementation — is a guaranteed no-op there. No chord could have
+fixed it.
+
+`externalOutputMode: "passthrough"` in OpenCode's TUI setup looks like an
+opt-out from alt-screen but is an orthogonal axis: it is the only value legal
+with alternate-screen and is its default.
+
+Claude Code and Codex are different, which is why jump works for them in the
+same pane type: both render inline on the normal buffer and push history into
+real xterm scrollback (Codex's `insert_history_lines`; Claude's AlternateScreen
+component is documented as being for transient ctrl-o style overlays only).
+
+**A fix was written and reverted on review.** Sending the TUI its own
+scroll-to-bottom chord works — ESC + 0x07 is Ctrl+Alt+G, which OpenCode binds
+to `messages_last`, and two independent passes confirmed both the binding and
+the encoding. What cannot be guaranteed is what that chord MEANS on a given
+machine. OpenCode keybinds are user-configurable, and a supported
+configuration can move `messages_last` elsewhere and put `messages_undo` —
+which aborts the session and reverts history — on Ctrl+Alt+G. A command
+labelled "Jump to Latest Message" must not be able to do that, and documenting
+the exposure is not mitigating it.
+
+Reading the effective binding would mean reimplementing OpenCode's config
+loader: JSONC, global plus per-project plus every `.opencode` directory up to
+home, variable substitution, a legacy migration, a win32 special case and
+plugin-registered binds. That reimplementation would drift.
+
+The rebinding-immune route exists — OpenCode's server exposes
+`POST /tui/execute-command`, whose alias table dispatches `session.last` below
+the keybind layer — but it needs a known server URL, which means running
+`opencode serve` and attaching the TUI to it rather than spawning the TUI
+directly. That is a transport change for this runtime and the right place for
+this to land.
+
+What DID ship: the command's description no longer claims a behaviour it
+cannot deliver, and the limitation is recorded where the jump is implemented.
+
+The command's description, which claimed "in a raw terminal view this scrolls
+the TUI viewport to the bottom", was false for OpenCode and is corrected. The
+system test's alternate-screen case was vacuous — on the alt screen viewportY
+and baseY are both 0, so its bottom assertion was `0 === 0` — and now proves
+both mechanisms.
+
+**Not done, deliberately:** no new chord was added. `End` stays feed-only. The
+palette command now works on every provider, which is what was actually broken,
+and the keybinding router's exclusion of raw terminal surfaces is a separate
+pre-existing design choice that `reservations.ts` documents on purpose. Note
+for anyone revisiting it: `Alt+End` is NOT free — it is reserved for
+directional split resize, because macOS turns Fn+Option+Arrow into it. `Alt+G`
+was verified free across defaults, reservations, the blocked-chord sets, the
+three provider TUIs, and macOS.
+
+### D2. WebGL — RESOLVED by turning it off
+
+Upgrading is not available: the fix ships only in
+`@xterm/addon-webgl@0.20.0-beta.219+`, there is still no stable 0.20.0, and
+that beta's peer dependency is `@xterm/xterm: ^6.1.0-beta.304`. Taking it would
+drag the CORE terminal — the heart of every pane — onto a beta to fix one
+renderer bug. That trade is clearly wrong, so the renderer is disabled behind a
+single constant with the exact upgrade condition written next to it.
+
+The DOM renderer is xterm's default, is correct, and was already the tested
+fallback every failure path in that file lands on. The two structural halves of
+the perf work that introduced WebGL — routing raw PTY channels once per
+renderer, and coalescing inline grid resizes — are untouched. VS Code ships the
+same escape hatch for the same symptom class.
+
+The gate is a parameter defaulting to the constant rather than a hard-coded
+read, so the fifteen existing cases keep proving the attach, fallback,
+context-loss and atlas-repair machinery still works for the day it flips back.
+
+## Confirmed findings — fixed, except where noted
+
+Kept as the record of what each defect actually was, since the fixes are only
+legible against it. Two carry a partial remainder, called out inline:
+
+- **Finding 1** (return forcing arrival compaction) is fixed for the CONSENT
+  half — the batch now records what the user agreed to and the return reuses
+  it. The other half of the recommendation, capping the arrival wait far below
+  300s, is NOT done: `COMPACTION_TIMEOUT_MS` is still 300_000 and the progress
+  toasts still 305_000. Shortening it changes when a legitimately slow
+  compaction is abandoned, which is a product decision about a destructive
+  operation, not a cleanup.
+- **Finding 4** (identity length bound) mirrors main's per-item limit through a
+  shared constant, so one over-long identity can no longer reject the batch.
+  Chunking the request is NOT done, and is not needed for the bug: the batch
+  cap is 10,000 identities and nothing else can now fail validation.
+
+1. **Return forces arrival compaction on without consent, locking N composers
+   for up to 5.5 minutes.** `bulkProviderSwitch.ts:61-67` hard-codes
+   `compactOnArrival: targetKind === 'claude'` on the return path.
+   `ComposerInput.tsx:241` disables the composer for the whole
+   `providerSwitchMessage` lifetime — a 30s readiness wait plus a 300s
+   compaction wait, with no cancel. The forward flow has an explicit checkbox
+   and a quota disclosure ("spends Claude quota, not Codex's"); one `Return
+   20` click has neither. *Fix:* carry the forward batch's choice on
+   `ProviderSwitchBatch`, and cap the arrival wait far below 300s.
+
+2. **`switchingModel` is invisible to every close guard, so `/model` can
+   fan out twice over the same panes.** `BulkProviderSwitchModal.tsx` guards
+   on `busy` only (`:504-507`, `:518-520`, `:521-527`) while `runModelSwitch`
+   sets only `switchingModel` (`:451-483`), and the open-reset effect clears
+   both. Escape mid-loop, reopen, click again, and a second sequential loop
+   interleaves PTY writes on panes that already got `/model sonnet` — the race
+   the comment at `:463-466` says the loop exists to prevent. *Fix:* `const
+   locked = busy || switchingModel` in all three guards.
+
+3. **Every replaceSession / reload / resume / rewind permanently burns a name
+   from the 100-entry pool.** `replaceSession` registers the successor with no
+   `agentNameId` (deliberately), then awaits `killSessionBackendIfOwned` — a
+   full IPC round trip, so React flushes in between. The reconciler sees the
+   identity-less successor, claims one, and main allocates and **commits to
+   disk**, advancing `nextIndex`. Only then does `session.ts:1153` overwrite
+   with the carried identity. The allocated name is referenced by nothing and
+   is never recycled. The pool drains at the rate of *replacements*, so ~100
+   reloads and every new agent is "Apollo 2". Multi-pane Undo Close burns up
+   to N−1 per restored tab. *Fix:* `pendingReplacementSuccessorsRef` already
+   exists; expose it through `refs` and have `claimMissingIdentities` skip
+   those ids.
+
+4. **One over-long `agentNameId` kills naming for the entire window.**
+   `reconcile.ts:30-31` validates identities as non-empty strings with no
+   upper bound; `main/agentNames/ipc.ts:19` is `z.string().min(1).max(200)`.
+   One identity over 200 chars in a user-editable `workspace.json` passes the
+   renderer check, enters the array, and `requestSchema.parse` rejects the
+   whole batch. `useAgentNameReconciler.ts:140` swallows it silently. This is
+   verbatim the failure `reconcile.ts:12-28` claims to have fixed — only the
+   type half of the contract was mirrored, not the length half. *Fix:* mirror
+   the length bound, and chunk the request.
+
+5. **The `{{key:…}}` "collect all failures" path is dead code.**
+   `keyReferences.ts:60-70` branches on `value === null`, but the production
+   resolver is `window.api.keyVaultResolveReference`, typed
+   `Promise<string>`, and `VaultService.resolveReference` *throws* on every
+   failure mode. The first bad reference escapes the loop, the aggregation
+   never runs, and the documented "one error message tells the user everything
+   that needs fixing" is false. Behaviour is still safe — it aborts rather
+   than inserting a literal. *Fix:* `await resolve(ref).catch(() => null)`, or
+   delete the aggregation and its comment.
+
+6. **Bulk switch discards every failure message and shrink summary that
+   `cc0e908d` went out of its way to produce.** `bulkProviderSwitch.ts:132-143`
+   drops `result.message` and `result.shrinkSummary`. The poisoned-carrier
+   abort names the exact remedy and is replaced by `Switched 0 agents to
+   Claude (12 failed)`; the shrink disclosure, added so "no lossy step is
+   silent", prints as `12 raw`. The single-pane path surfaces both, and the
+   sibling function in the same file already argues the case ("A count alone
+   is unactionable").
+
+7. **Mid-turn agents are reported as `failed`, contradicting the modal's own
+   footer**, which promises they "will be skipped until idle". The forward
+   summary has no `skipped` counter; the return path does.
+
+8. **"Ask once" confirmation is armed against a set that can grow.**
+   `runSwitch` arms on the first click and reads `matchingRows` live on the
+   second. Disarm handlers cover every manual change but not `agentRows`
+   changing on its own — confirm for 3 agents, a fourth goes idle, and 4 get
+   their history rewritten under a confirmation that named 3. *Fix:* snapshot
+   the confirmed `sessionId[]` when arming.
+
+9. **The agent-name registry grows without bound and rewrites the whole file
+   per allocation.** No prune path exists. At 10k assignments it rebuilds a
+   `Set` over every value per allocation and re-serialises the entire file on
+   the promise tail every window queues behind. Amplified directly by
+   finding 3. "Never recycle" only requires `nextIndex` to be monotonic, not
+   full retention.
+
+10. **The default quota-independent switch wakes the source provider it
+    provably never uses.** `providerSwitchCore.ts:310` calls
+    `ensureSessionLive` unconditionally, but `planWithoutSourceTurns` — the
+    default — never touches the live source; that is the entire point. For a
+    hibernated pane this is a real spawn plus a 30s readiness wait that
+    `replaceSession` then kills, serialised N times across a bulk switch.
+
+11. **`deliverTextToSession`'s refusal is an exception, not a result.**
+    `encodeTerminalPaste` throws from inside `paste()`, and
+    `DeliverTextResult` has no refusal variant. Combined with finding "plain
+    terminal panes render no toast" (now fixed), a multiline template into a
+    non-bracketed-paste program was a total silent no-op. *Fix:* add a
+    `refused` variant.
+
+12. **Unmatchable key references are pasted literally and silently.**
+    `KEY_REF_PATTERN` excludes `/` from both capture groups, so
+    `{{key:A/B/C}}` and `{{key:Provider}}` never match and survive
+    `body.replace` untouched — contradicting the header's "resolution aborts
+    loudly".
+
+13. **Secret sinks beyond the ones the disclosure comment names.** The comment
+    names drafts, scrollback and the provider transcript. It omits:
+    `useAutoSave.ts:97-99` writing `draftInput` to `workspace.json` in
+    plaintext; `draft.ts:109` keeping a cleared draft recoverable via undo;
+    `KeyVaultModal.tsx` putting revealed plaintext in a DOM `title=`
+    attribute; and — most significantly — the proxy dumps.
+    `packages/claude-code-headless/src/proxy/mitmAddon.py:490` base64-encodes
+    outbound request bodies into the proxy events JSONL. That directory is
+    already 3.9 GB on this machine and never rotates, so submitting a prompt
+    containing a vault key writes that key to disk in trivially recoverable
+    form somewhere nothing prunes.
+
+14. **`providerSwitchesInFlight.add` sits outside its try block.** A throw
+    from the intervening `setRuntimes` leaks the entry permanently in a
+    module-scoped Set, and that pane answers "Provider switch already in
+    progress" until the window reloads. Separately, if
+    `window.api.switchProvider` throws *synchronously*,
+    `.finally(unsubscribeProgress)` is never attached and the progress
+    listener survives for the life of the renderer.
+    `startArrivalCompaction` guards exactly this; the transaction path does
+    not.
+
+15. **Unhandled rejections at three `BulkProviderSwitchModal` call sites**,
+    and `runModelSwitch` has `try/finally` with no `catch` — an IPC rejection
+    aborts the batch mid-way and the `finally` still toasts success with
+    `failed === 0` for agents never touched.
+
+16. **`largestSourceEstimate` re-walks every matching pane's entry window on
+    every runtime tick.** The memo's own comment names `workspace.runtimes` as
+    "one of the highest-churn references in the app" and then depends on it —
+    O(rows × up to 2000 entries) per streaming tick while the modal is open.
+
+17. **The vault fails on Windows/Linux with a raw TypeError.** `main/index.ts`
+    wires `promptAuth` to `systemPreferences.promptTouchID` while
+    `canPromptAuth` correctly gates on darwin, but `ensureUnlocked` does not
+    consult the flag. Off-macOS the user gets "promptTouchID is not a
+    function" instead of the honest platform message. Fails closed, so
+    security is fine; the UX is not.
+
+18. **`tailEngagedRef` is not reset when the terminal detaches.**
+    `agentTerminalFollow.ts:109-114` disposes the marker but leaves the flag
+    true, so a remount under the same sessionId silently loses the saved
+    reading position on the next disengage.
+
+19. **The reconciler's stated invariant is false.** It claims "on failure no
+    dep changed at all — so a broken registry cannot become a hot loop", but
+    `identities` is a `useMemo` over `state` and `agentNameIdentities` returns
+    a fresh array every call. With an unreadable `agent-names.json`
+    (deliberately never cached), every focus change, title edit, pin, split
+    and close fires another failing IPC round trip forever, with no
+    user-visible signal.
+
+---
+
+## Suspicions (stated as such, with what would confirm)
+
+- **`isLimitIdle`'s `turnStartedAt === null` branch may green-light a switch
+  over a live turn.** `turnStartedAt` is null in a fresh `emptyRuntime()`, and
+  with `processActive` true from an adopted backend the guard reads "parked"
+  and `replaceSession` kills a live turn. *Confirm by:* reloading the renderer
+  while a Claude pane whose recent transcript holds a `rate_limit` carrier is
+  mid-turn. Cheap hardening: refuse when `turnStartedAt === null &&
+  processActive === true`.
+- **`answerResumePrompt` presses UP a guessed number of times** (`selectedIndex
+  ?? 1`) and then Enter. If the cursor was elsewhere, Enter lands on a
+  different option; if that option discards history the imported transcript is
+  silently lost, the wait burns its full 300s, and the switch is still
+  reported successful.
+- **The resume-prompt branch may be unable to satisfy its own wait** — it
+  waits for a compaction whose fingerprint differs from baseline, having just
+  answered "Resume from summary", which resumes *from* the existing carrier.
+- **Nothing enforces one-identity-per-live-session.** `agentNameId` has no
+  runtime validation at any persistence boundary. The registry guarantees
+  identity→name uniqueness; nothing guarantees session→identity uniqueness.
+  Every in-app path was traced and none produces a duplicate, so the invariant
+  is simply unguarded against a copied or edited `workspace.json`.
+- **The `__proto__` structured-clone round trip is untested.**
+  `registry.ts:218` creates a real own `__proto__` data property and the
+  renderer reads it back through Electron's structured clone, which is only
+  ever exercised with a mocked `window.api`.
+
+---
+
+## Explicitly clean
+
+The most dangerous question asked — **can a multi-line template auto-submit?**
+— gets a clean answer. `encodeTerminalPaste` normalises `\r\n?` to `\n` first,
+then rejects `[\x00-\x08\x0b-\x1f\x7f-\x9f]`, which catches embedded `ESC`
+(so `\x1b[201~` cannot be forged to close the bracket early) and every bare
+`\r` that survived normalisation. Multiline is wrapped only when
+`term.modes.bracketedPasteMode` is genuinely true, read live, and is refused
+with a message otherwise. Nothing appends `\r`.
+
+Also verified clean: the `textPasteTarget` registry (no leaked registrations,
+no cross-window collision, correct re-check after pane replacement);
+`templateBusy` cannot deadlock (the palette unmounts and discards the ref);
+the command-palette dep arrays; `keyReferences` regex and injection handling
+(function replacer, so `$&`/`$1` in a secret are not interpreted; the two
+placeholder grammars cannot collide); `main/ipc/keyVault.ts` (key ids
+validated before any path join, unlock gate correctly fenced against a
+concurrent lock, handlers registered once); the paste-target `isActive`
+gating; and the agent-name hard parts — vocabulary exhaustion, cross-window
+allocation serialisation with temp-file-plus-rename, Undo Close identity carry
+on every path, the default-off toggle, and the prototype-pollution hardening,
+which is genuinely thorough.
+
+---
+
+## Where the coverage holes are
+
+Three of the highest-severity findings live in code with no adequate test, and
+that is not a coincidence.
+
+- `deliverTextToSession.renderer.test.ts` stubs `ensureSessionLive` as a no-op
+  over frozen session objects, so the no-op-wake bug was structurally
+  untestable there. Its one cancel test flips the validity flag by hand — it
+  encodes the bug's shape as intended behaviour.
+- `bulkProviderSwitch.ts` had **no test file at all**, and three findings live
+  in it, one of them two-click data loss. It has one now, covering the return
+  path's batch bookkeeping.
+- `agentNameContinuity.renderer.test.tsx` mounts `useSessionActions` without
+  the reconciler, so the interim render that burns a name cannot occur. The
+  test asserts the final identity, which is correct; the leak is invisible
+  to it.
+- Seven `reconciler.renderer.test.tsx` tests never ran green at all, so
+  nothing in agent-name reconciliation was actually verified before merge.
+
+## Pre-existing test failures on `main` (not caused by this branch)
+
+Verified by running the same files at `origin/main`:
+
+- `providers/shared/renderer/protocols/media/imageAttachment.test.ts` — cites
+  a missing local session file. This is open issue #839.
+- `workspace/hook/persistence/codexLiveContinuity.renderer.test.tsx` — a
+  `waitFor` timeout.
+- `main/workflows/control.system.test.ts` — a 5s test timeout.
+
+---
+
+## Deliberately deferred
+
+**Attach replay is parsed at 80x24 before the first fit.** Pre-existing,
+structural, and tracked as issue #766. `AgentTerminalOwnership` renders the
+leaf inside a `hidden` div on its first commit, so `dimensionActive` is false
+when the mount effect runs and the initial fit is skipped; `term.open` then
+measures a hidden box and xterm stays at its default 80x24. `attachAgentPty`
+resolves a few milliseconds later and up to 512 KiB of raw PTY history is
+replayed immediately, while the first real `fit()` only runs from a later
+animation frame — reflowing the buffer mid-parse, so absolute cursor-positioning
+sequences in the replay land on the wrong cells.
+
+NOT fixed here, on purpose. Every available shape of the fix has a real cost:
+
+- Deferring the whole attach until the first fit means a pane that is never
+  dimension-active never attaches, so a long-hidden pane can fall off the far
+  end of main's bounded 512 KiB buffer and lose output it would have kept.
+- Deferring only the replay leaves live PTY chunks writing to the terminal
+  ahead of the buffered history, which produces the very interleaving the
+  change is meant to remove, unless the forwarder's replay latch is also
+  restructured.
+
+This is the most delicate path in the application, it cannot be exercised
+without running the app, and it is not one of the four reported symptoms nor
+caused by any of the four merges. Issue #766 proposes replacing the raw replay
+with a serialized screen, which removes the ordering problem entirely rather
+than sequencing around it. That is the right place for it.
+
+The two corruption causes that COULD be resolved safely — the WebGL atlas bug
+and the agent-name row resizing every pane after mount — both were.
+
+---
+
+## Later additions (same branch)
+
+Two more symptoms were reported while this branch was open, plus a two-agent
+merge review. Recorded here because both turned out to share a root cause with
+what was already being fixed.
+
+### The mouse wheel does nothing in an OpenCode terminal pane — DIAGNOSED, NOT FIXED
+
+Same family as the Jump to Latest bug and a different mechanism. **Nothing
+swallows the wheel** — that was checked exhaustively: exactly one `wheel`
+handler exists in the renderer and it belongs to the feed, there is no
+capture-phase listener, no `attachCustomWheelEventHandler`, and the terminal
+container's parent is `overflow-hidden` so nothing above can consume it.
+
+The modes that make the wheel work are thrown away. `attachAgentPty` replays
+the trailing bytes of a CAPPED buffer that evicts the OLDEST data, and a TUI
+writes its mode preamble exactly once at startup: `1049` (alternate screen),
+`1000`/`1002`/`1003` (mouse button, drag, any-event including wheel) and `1006`
+(SGR encoding). A TUI repainting at 60fps blows through the 512 KiB cap
+quickly, so on any session with real activity that preamble is long gone before
+a renderer attaches, and nothing reconstructs it.
+
+A freshly-constructed xterm therefore sits on the NORMAL buffer with no mouse
+tracking while the application believes the opposite. xterm attaches its
+wheel-to-mouse-report listener only when the application has asked for wheel
+events, and its fallback path returns early on a normal buffer, so the wheel
+reaches nobody. Meanwhile the TUI paints absolutely-addressed full frames that
+never push a line into scrollback, so native viewport scrolling has nothing to
+scroll either. The pane still LOOKS correct, because a full-screen repaint
+renders identically on either buffer — which is why this was hard to see.
+
+OpenCode enables mouse capture by default and Agent Code never disables it; the
+installed binary's renderer setup block contains exactly those DECSETs. Claude
+Code and Codex are unaffected because they render inline and push real
+scrollback.
+
+**A fix was written, reviewed, and reverted.** Tracking the five modes as
+chunks pass and prepending the active ones ahead of the replay fails in two
+ways that were reproduced against real xterm:
+
+1. **Current modes cannot precede historical output.** If the retained replay
+   contains bytes written on the normal buffer and only later switches to the
+   alternate screen, prefixing the current `1049h` moves that earlier content
+   onto the alternate buffer, where the following `1049l` discards it. The
+   correct input is the mode state at the replay's STARTING boundary, which
+   means feeding a tracker the bytes the cap EVICTS, not the bytes it keeps.
+2. **A set of independent flags is not xterm's model.** Mouse protocols are
+   mutually exclusive — `1000h`, `1003h`, `1003l` leaves reporting disabled,
+   and `1003h` then `1000h` leaves VT200, not ANY. `ESC c` and the
+   `1047`/`1048`/`1049` aliases matter too.
+
+Doing it properly is a real terminal state machine and cannot be validated
+without running the app. It belongs next to issue #766, which proposes
+replacing the raw replay with a serialized screen and would remove the ordering
+problem entirely rather than sequencing around it.
+
+### Pane paths were truncated from the wrong end
+
+Every pane in a workspace shares the leading path segments, so
+`text-overflow: ellipsis` — which always clips the END — removed the only part
+that identifies the agent. A narrow pane showed `…/Desktop/Developme…` for all
+of them. `shortenCwd` was already producing the right string; only the clipping
+end was wrong.
+
+### Merge review
+
+One Claude and one Codex reviewer, both read-only, both returned BLOCK, and
+between them they found seven things worth fixing. The most valuable was one
+both the author and the Claude reviewer reached independently: the wake's
+no-op detection compared `builtInMcpDomains` by reference, and that array is
+rebuilt on every wake, so the fix was inert for exactly the agent panes it
+existed to protect and worked only for plain terminals.
+
+The rest: the identity-carry reservation leaked when spawn itself threw and its
+gate was narrower than the carry predicate; the bulk modal's double-run lock
+covered the close paths but not the run paths; the widened `{{key:…}}` pattern
+captured ordinary JSX and broke templates that had always worked; catching
+every resolver throw re-prompted for authentication once per reference; the
+vault's provider column could not be scrolled to in a narrow window; and three
+comments described the code beside them inaccurately.
+
+Both reviewers confirmed the OpenCode jump chord's default binding and byte
+encoding are correct, and Codex reproduced the JSX and re-prompt regressions
+against the real modules rather than reasoning about them.
+
+Three changes were WITHDRAWN rather than defended once the reviewer's
+reproductions showed they were wrong: the terminal mode tracker, the OpenCode
+jump chord, and a widened `{{key:…}}` pattern that captured ordinary JSX. Each
+is written up above with the evidence that killed it, so the next attempt
+starts from the failure instead of repeating it.
diff --git a/src/main/agentNames/ipc.ts b/src/main/agentNames/ipc.ts
index 78d83989..8b508128 100644
--- a/src/main/agentNames/ipc.ts
+++ b/src/main/agentNames/ipc.ts
@@ -2,6 +2,10 @@ import { ipcMain } from 'electron'
 import { join } from 'node:path'
 import { z } from 'zod'
 
+import {
+  AGENT_NAME_IDENTITY_MAX_LENGTH,
+  AGENT_NAME_IDENTITY_REQUEST_MAX,
+} from '@shared/types/agentNames.js'
 import { AgentNameRegistry } from '@main/agentNames/registry.js'
 import { STATE_DIR } from '@main/storage/paths.js'
 import { getBrowserWindow, windowIdFor } from '@main/window/windowRegistry.js'
@@ -14,9 +18,12 @@ import { getBrowserWindow, windowIdFor } from '@main/window/windowRegistry.js'
 // address — so the two must not be able to take each other down.
 export const AGENT_NAMES_FILE = join(STATE_DIR, 'agent-names.json')
 
-// Bounded so a malformed or hostile renderer cannot make the allocator walk a
-// huge list under the serialization tail. 10k is far past any real workspace.
-const requestSchema = z.array(z.string().min(1).max(200)).max(10_000)
+// Both bounds come from the shared contract, because the renderer's
+// `identityOf` has to refuse exactly what this refuses — see
+// shared/types/agentNames.ts for the batch-wide failure that drift caused.
+const requestSchema = z
+  .array(z.string().min(1).max(AGENT_NAME_IDENTITY_MAX_LENGTH))
+  .max(AGENT_NAME_IDENTITY_REQUEST_MAX)
 
 /**
  * The ONLY consumer of AgentNameRegistry.
diff --git a/src/main/agentNames/registry.ts b/src/main/agentNames/registry.ts
index 47d030cd..f186198c 100644
--- a/src/main/agentNames/registry.ts
+++ b/src/main/agentNames/registry.ts
@@ -98,6 +98,30 @@ function adoptAssignments(source: Record<string, string>): Record<string, string
 export class AgentNameRegistry {
   private state: RegistryState | undefined
 
+  /**
+   * Normalized spoken names currently assigned, kept alongside `state`.
+   *
+   * WHY it is cached instead of rebuilt: `allocate` used to walk every value
+   * and normalize it on EVERY call, purely to answer "has a hand-edited file
+   * already used this name". That is O(assignments) work per allocation for a
+   * question whose answer only changes when this process assigns something,
+   * and this process is the single writer after the first load. `load` already
+   * builds exactly this set for its duplicate check, so caching it there costs
+   * nothing and makes the common path proportional to the NEW names.
+   *
+   * WHY there is still no prune path, which would bound the file properly:
+   * assignments can only be dropped by knowing which identities are still
+   * live, and no single window knows that. A window holds its own workspace,
+   * not the others', so pruning against one window's identity set would delete
+   * names belonging to agents open in another window and hand those names out
+   * again. That is a correctness bug traded for a size nicety. The growth rate
+   * was the real problem and it is fixed at the source: successors mid-replace
+   * no longer burn an allocation each (see the renderer's
+   * pendingIdentityCarry), so the file now grows once per genuinely new agent
+   * rather than once per reload, resume, rewind and provider switch.
+   */
+  private usedNames: Set<string> | undefined
+
   // WHY one promise tail rather than a mutex or a per-identity lock: every
   // allocation reads the whole counter and writes the whole file, so the
   // critical section is the entire operation. Two windows starting agents in
@@ -129,6 +153,7 @@ export class AgentNameRegistry {
         throw new Error(`Agent name registry at ${this.path} is unreadable; refusing to overwrite it`, { cause: error })
       }
       this.state = { version: 1, nextIndex: 0, assignments: emptyAssignments() }
+      this.usedNames = new Set()
       return this.state
     }
 
@@ -167,7 +192,13 @@ export class AgentNameRegistry {
       // name makes every later lookup ambiguous with no evidence for choosing
       // between them.
       const spoken = Object.values(assignments).map(normalizeAgentName)
-      if (new Set(spoken).size !== spoken.length) throw new Error('Two identities share one spoken name')
+      const distinct = new Set(spoken)
+      if (distinct.size !== spoken.length) throw new Error('Two identities share one spoken name')
+      // Assigned here rather than after the try, so a file that fails
+      // validation leaves BOTH `state` and this cache unset — the refusal has
+      // to be all-or-nothing or a later allocation would consult a set that
+      // describes a registry we refused to load.
+      this.usedNames = distinct
     } catch (error) {
       // WHY this is not cached and not repaired: leaving `this.state` unset
       // means every later call re-reads and re-fails, so the user gets a
@@ -188,7 +219,14 @@ export class AgentNameRegistry {
     // we mutated in place, a write error would leave this process believing it
     // had published names that are not on disk.
     const draft: RegistryState = { ...loaded, assignments: adoptAssignments(loaded.assignments) }
-    const used = new Set(Object.values(draft.assignments).map(normalizeAgentName))
+    // `load` guarantees this alongside `state`; the fallback keeps the type
+    // honest without pretending an unloaded registry is an empty one.
+    const used = this.usedNames ?? new Set<string>()
+    // Every name this call adds, so a failed commit can undo its effect on the
+    // shared cache. The draft's assignments are already a copy and roll back
+    // for free; this set is not, because copying it per allocation is the cost
+    // being removed.
+    const added: string[] = []
     let changed = false
 
     for (const identity of identities) {
@@ -210,11 +248,24 @@ export class AgentNameRegistry {
       // would have to reconcile two divergent counters with no evidence.
       while (used.has(normalizeAgentName(name))) name = agentNameAt(draft.nextIndex++)
       draft.assignments[identity] = name
-      used.add(normalizeAgentName(name))
+      const normalized = normalizeAgentName(name)
+      used.add(normalized)
+      added.push(normalized)
       changed = true
     }
 
-    if (changed) await this.commit(draft)
+    if (changed) {
+      try {
+        await this.commit(draft)
+      } catch (error) {
+        // Same contract as the draft copy above: a write that did not land
+        // must leave this process believing nothing was published. Leaving the
+        // names in the cache would make the retry skip past them and burn the
+        // vocabulary for allocations that never happened.
+        for (const name of added) used.delete(name)
+        throw error
+      }
+    }
     return Object.fromEntries(identities.map(identity => [identity, draft.assignments[identity]]))
   }
 
diff --git a/src/main/index.ts b/src/main/index.ts
index b2e97955..4d5d51cf 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -205,7 +205,22 @@ const caffeinateController = new CaffeinateController()
 // no async boot step — only the per-run unlock boolean.
 const vaultService = new VaultService({
   store: createFileVaultStore(join(STATE_DIR, 'key-vault'), createSafeStorageCodec()),
-  promptAuth: reason => systemPreferences.promptTouchID(reason),
+  promptAuth: async reason => {
+    // WHY the platform check lives HERE and not in ensureUnlocked: the service
+    // deliberately attempts the prompt rather than pre-gating on
+    // canPromptAuth, because that flag once reported biometric capability only
+    // and pre-gating locked out every password-only Mac from the login-password
+    // path this feature promises. That reasoning is right for capability. It is
+    // NOT right for a platform that has no promptTouchID at all: there,
+    // "attempt it" meant calling undefined, and the user got a raw
+    // "systemPreferences.promptTouchID is not a function" TypeError instead of
+    // the honest platform message. Fails closed either way; only the wording
+    // was broken.
+    if (process.platform !== 'darwin' || typeof systemPreferences.promptTouchID !== 'function') {
+      throw new Error('The API key vault needs macOS Touch ID or login-password authentication, which this platform does not provide.')
+    }
+    await systemPreferences.promptTouchID(reason)
+  },
   // canPromptTouchID checks biometrics, not user-presence/password auth.
   // Electron 43's promptTouchID uses SecAccessControlUserPresence; attempt
   // that supported macOS API and let rejection keep the vault locked.
diff --git a/src/main/sessionManager.codexReplacement.test.ts b/src/main/sessionManager.codexReplacement.test.ts
index 2eb9bdf9..633b2571 100644
--- a/src/main/sessionManager.codexReplacement.test.ts
+++ b/src/main/sessionManager.codexReplacement.test.ts
@@ -21,6 +21,21 @@ const { createSession, resolveTranscriptPath } = vi.hoisted(() => ({
   resolveTranscriptPath: vi.fn(),
 }))
 
+vi.mock('@main/workspaceDirectory.js', () => ({
+  // These suites spawn into synthetic paths ('/tmp/project', '/recorded/worktree')
+  // that intentionally do not exist on disk. The real spawn-path guard stats the
+  // cwd, so it is stubbed here; workspaceDirectory.test.ts covers the guard
+  // itself, and sessionManager.recover.test.ts overrides this mock to prove the
+  // manager surfaces a missing folder.
+  MissingWorkspaceDirectoryError: class MissingWorkspaceDirectoryError extends Error {
+    constructor(readonly cwd: string) {
+      super(`Workspace folder is missing: ${cwd}`)
+      this.name = 'MissingWorkspaceDirectoryError'
+    }
+  },
+  assertWorkspaceDirectoryExists: vi.fn(async () => {}),
+}))
+
 vi.mock('@providers/registry.main.js', () => ({
   getMainProvider: () => ({ createSession, resolveTranscriptPath }),
 }))
diff --git a/src/main/sessionManager.lifecycle.test.ts b/src/main/sessionManager.lifecycle.test.ts
index 77e1b8b7..07a4e221 100644
--- a/src/main/sessionManager.lifecycle.test.ts
+++ b/src/main/sessionManager.lifecycle.test.ts
@@ -13,6 +13,21 @@ const { createSession, deliverPrompt } = vi.hoisted(() => ({
   deliverPrompt: vi.fn(),
 }))
 
+vi.mock('@main/workspaceDirectory.js', () => ({
+  // These suites spawn into synthetic paths ('/tmp/project', '/recorded/worktree')
+  // that intentionally do not exist on disk. The real spawn-path guard stats the
+  // cwd, so it is stubbed here; workspaceDirectory.test.ts covers the guard
+  // itself, and sessionManager.recover.test.ts overrides this mock to prove the
+  // manager surfaces a missing folder.
+  MissingWorkspaceDirectoryError: class MissingWorkspaceDirectoryError extends Error {
+    constructor(readonly cwd: string) {
+      super(`Workspace folder is missing: ${cwd}`)
+      this.name = 'MissingWorkspaceDirectoryError'
+    }
+  },
+  assertWorkspaceDirectoryExists: vi.fn(async () => {}),
+}))
+
 vi.mock('@providers/registry.main.js', () => ({
   getMainProvider: () => ({ createSession, deliverPrompt }),
 }))
diff --git a/src/main/sessionManager.recover.test.ts b/src/main/sessionManager.recover.test.ts
index 6676008f..d415763b 100644
--- a/src/main/sessionManager.recover.test.ts
+++ b/src/main/sessionManager.recover.test.ts
@@ -12,6 +12,21 @@ const terminalControl = vi.hoisted(() => ({
   stop: vi.fn(async (): Promise<void> => {}),
 }))
 
+vi.mock('@main/workspaceDirectory.js', () => ({
+  // These suites spawn into synthetic paths ('/tmp/project', '/recorded/worktree')
+  // that intentionally do not exist on disk. The real spawn-path guard stats the
+  // cwd, so it is stubbed here; workspaceDirectory.test.ts covers the guard
+  // itself, and the missing-folder case below overrides this mock to prove the
+  // manager surfaces it.
+  MissingWorkspaceDirectoryError: class MissingWorkspaceDirectoryError extends Error {
+    constructor(readonly cwd: string) {
+      super(`Workspace folder is missing: ${cwd}`)
+      this.name = 'MissingWorkspaceDirectoryError'
+    }
+  },
+  assertWorkspaceDirectoryExists: vi.fn(async () => {}),
+}))
+
 vi.mock('@providers/registry.main.js', () => ({
   getMainProvider: () => ({ createSession, deliverPrompt }),
 }))
@@ -92,6 +107,42 @@ describe('SessionManager recover', () => {
     terminalControl.stop.mockClear()
   })
 
+  it('reports the missing folder instead of a generic start failure', async () => {
+    // The 2026-09-08 regression report: six panes came up as ERROR after their
+    // git worktrees were deleted, and the only text the user ever saw was
+    // "agent exited before it became ready for input (start-failed)". node-pty
+    // chdirs inside the forked child, so without the spawn-path guard the PTY
+    // is created successfully and the process is dead microseconds later —
+    // recover() returns ok:true and the failure masquerades as a readiness
+    // timeout. This asserts the guard converts that into a message naming the
+    // folder, and marks it non-retryable so Dispatch stops re-spawning it.
+    const { assertWorkspaceDirectoryExists } = await import('@main/workspaceDirectory.js')
+    const { MissingWorkspaceDirectoryError } = await import('@main/workspaceDirectory.js')
+    vi.mocked(assertWorkspaceDirectoryExists).mockRejectedValueOnce(
+      new MissingWorkspaceDirectoryError('/tmp/deleted-worktree'),
+    )
+    const { SessionManager } = await import('./sessionManager')
+    const manager = new SessionManager()
+
+    const result = await manager.recover({
+      sessionId: 'gone-folder-session',
+      kind: 'claude',
+      cwd: '/tmp/deleted-worktree',
+    })
+
+    expect(result).toMatchObject({
+      ok: false,
+      code: 'start-failed',
+      retryable: false,
+      message: 'Workspace folder is missing: /tmp/deleted-worktree',
+    })
+    // No backend was constructed, and nothing was left half-claimed: the guard
+    // runs before the spawn reservation precisely so a retry is not fenced out
+    // by a session that never existed.
+    expect(createSession).not.toHaveBeenCalled()
+    expect(manager.getBackendSnapshot('gone-folder-session')).toBeNull()
+  })
+
   it('adopts a matching live backend without constructing another provider', async () => {
     const { SessionManager } = await import('./sessionManager')
     const manager = new SessionManager()
diff --git a/src/main/sessionManager.screenGate.test.ts b/src/main/sessionManager.screenGate.test.ts
index 1d5c936a..c08b8635 100644
--- a/src/main/sessionManager.screenGate.test.ts
+++ b/src/main/sessionManager.screenGate.test.ts
@@ -6,6 +6,21 @@ const { createSession, createTerminalSession } = vi.hoisted(() => ({
   createTerminalSession: vi.fn(),
 }))
 
+vi.mock('@main/workspaceDirectory.js', () => ({
+  // These suites spawn into synthetic paths ('/tmp/project', '/recorded/worktree')
+  // that intentionally do not exist on disk. The real spawn-path guard stats the
+  // cwd, so it is stubbed here; workspaceDirectory.test.ts covers the guard
+  // itself, and the missing-folder case below overrides this mock to prove the
+  // manager surfaces it.
+  MissingWorkspaceDirectoryError: class MissingWorkspaceDirectoryError extends Error {
+    constructor(readonly cwd: string) {
+      super(`Workspace folder is missing: ${cwd}`)
+      this.name = 'MissingWorkspaceDirectoryError'
+    }
+  },
+  assertWorkspaceDirectoryExists: vi.fn(async () => {}),
+}))
+
 vi.mock('@providers/registry.main.js', () => ({
   getMainProvider: () => ({
     name: 'Claude',
diff --git a/src/main/sessionManager.ts b/src/main/sessionManager.ts
index 90abc879..f400fec8 100644
--- a/src/main/sessionManager.ts
+++ b/src/main/sessionManager.ts
@@ -34,6 +34,10 @@ import type {
   SessionRecoverResult,
 } from '@shared/types/session.js'
 import { TmuxRegistry } from '@main/tmux/TmuxRegistry.js'
+import {
+  MissingWorkspaceDirectoryError,
+  assertWorkspaceDirectoryExists,
+} from '@main/workspaceDirectory.js'
 import { performanceService } from '@main/performance/PerformanceService.js'
 import { getToolPath, refreshToolchainFromState } from '@main/setup/toolchain.js'
 import { resolveToolPath } from '@main/setup/binaryResolver.js'
@@ -1836,12 +1840,20 @@ export class SessionManager extends EventEmitter {
       return {
         ok: false,
         code: 'start-failed',
-        retryable: true,
+        // A deleted folder is not retryable: every retry re-runs the same
+        // stat and fails identically. The incident journal for 2026-09-08
+        // shows the old path retrying these spawns on each Dispatch select,
+        // which is pure noise once the cause is known.
+        retryable: !(error instanceof MissingWorkspaceDirectoryError),
         // WHY the raw provider exception stays out of IPC: binary launch
         // errors can contain environment values, proxy URLs, or scoped MCP
         // tokens. Main records the typed code and internal performance error;
         // renderer receives one stable, actionable message with no payload.
-        message: 'Session failed to start. Check provider setup and retry.',
+        // The missing-directory case is the deliberate exception — its
+        // message is curated and its payload is a path the UI already shows.
+        message: error instanceof MissingWorkspaceDirectoryError
+          ? error.message
+          : 'Session failed to start. Check provider setup and retry.',
       }
     } finally {
       if (this.recoveriesInFlight.get(options.sessionId) === claim) {
@@ -2422,6 +2434,13 @@ export class SessionManager extends EventEmitter {
     }
     const kind: SessionKind = options.kind ?? DEFAULT_PROVIDER
     const providerRuntime = resolveProviderRuntime(kind, options.providerRuntime)
+    // Fail here rather than in the forked child. See
+    // MissingWorkspaceDirectoryError for why a deleted cwd is otherwise
+    // invisible until the readiness wait times out. This runs before the
+    // spawn reservation so a missing folder leaves no half-claimed session
+    // behind, and it is in spawnWithId rather than in spawn()/recover()
+    // separately because this is the one funnel both of them pass through.
+    await assertWorkspaceDirectoryExists(options.cwd)
     if (
       this.sessions.has(sessionId) ||
       this.spawningSessionGenerations.has(sessionId) ||
diff --git a/src/main/sessionManager.wake.test.ts b/src/main/sessionManager.wake.test.ts
index adbe3a7e..5188b515 100644
--- a/src/main/sessionManager.wake.test.ts
+++ b/src/main/sessionManager.wake.test.ts
@@ -6,6 +6,21 @@ const { createSession, createTerminalSession } = vi.hoisted(() => ({
   createTerminalSession: vi.fn(),
 }))
 
+vi.mock('@main/workspaceDirectory.js', () => ({
+  // These suites spawn into synthetic paths ('/tmp/project', '/recorded/worktree')
+  // that intentionally do not exist on disk. The real spawn-path guard stats the
+  // cwd, so it is stubbed here; workspaceDirectory.test.ts covers the guard
+  // itself, and sessionManager.recover.test.ts overrides this mock to prove the
+  // manager surfaces a missing folder.
+  MissingWorkspaceDirectoryError: class MissingWorkspaceDirectoryError extends Error {
+    constructor(readonly cwd: string) {
+      super(`Workspace folder is missing: ${cwd}`)
+      this.name = 'MissingWorkspaceDirectoryError'
+    }
+  },
+  assertWorkspaceDirectoryExists: vi.fn(async () => {}),
+}))
+
 vi.mock('@providers/registry.main.js', () => ({
   getMainProvider: () => ({
     name: 'OpenCode',
diff --git a/src/main/workspaceDirectory.test.ts b/src/main/workspaceDirectory.test.ts
new file mode 100644
index 00000000..195b1ea6
--- /dev/null
+++ b/src/main/workspaceDirectory.test.ts
@@ -0,0 +1,77 @@
+import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import {
+  MissingWorkspaceDirectoryError,
+  assertWorkspaceDirectoryExists,
+} from './workspaceDirectory.js'
+
+// WHY this suite touches the real filesystem instead of mocking node:fs: the
+// entire point of the guard is to predict whether a forked child's chdir will
+// succeed. A mocked stat would only assert that we call stat, which is the one
+// thing that cannot regress silently. Real temp directories test the property
+// we actually care about, including the symlink case that a naive lstat
+// implementation would get wrong.
+const made: string[] = []
+
+async function tempDir(): Promise<string> {
+  const dir = await mkdtemp(path.join(tmpdir(), 'agent-code-wsdir-'))
+  made.push(dir)
+  return dir
+}
+
+afterEach(async () => {
+  await Promise.all(made.splice(0).map(dir => rm(dir, { recursive: true, force: true })))
+})
+
+describe('assertWorkspaceDirectoryExists', () => {
+  it('accepts a directory that exists', async () => {
+    const dir = await tempDir()
+    await expect(assertWorkspaceDirectoryExists(dir)).resolves.toBeUndefined()
+  })
+
+  it('names the resolved path when the directory is gone', async () => {
+    const dir = await tempDir()
+    const missing = path.join(dir, 'deleted-worktree')
+    await expect(assertWorkspaceDirectoryExists(missing))
+      .rejects.toThrow(MissingWorkspaceDirectoryError)
+    // The path is the whole value of this error — a message that says only
+    // "folder is missing" reproduces the failure it was written to replace.
+    await expect(assertWorkspaceDirectoryExists(missing))
+      .rejects.toThrow(missing)
+  })
+
+  it('rejects a path that exists but is a file', async () => {
+    const dir = await tempDir()
+    const file = path.join(dir, 'not-a-directory')
+    await writeFile(file, '')
+    await expect(assertWorkspaceDirectoryExists(file))
+      .rejects.toThrow(MissingWorkspaceDirectoryError)
+  })
+
+  it('follows symlinks, accepting a link to a live directory', async () => {
+    const dir = await tempDir()
+    const target = path.join(dir, 'target')
+    const link = path.join(dir, 'link')
+    await mkdir(target)
+    await symlink(target, link)
+    await expect(assertWorkspaceDirectoryExists(link)).resolves.toBeUndefined()
+  })
+
+  it('rejects a dangling symlink, which is what a deleted worktree leaves behind', async () => {
+    const dir = await tempDir()
+    const link = path.join(dir, 'link')
+    await symlink(path.join(dir, 'never-existed'), link)
+    // stat (not lstat) is the deliberate choice: chdir follows the link too,
+    // so the child would fail here exactly as this guard does.
+    await expect(assertWorkspaceDirectoryExists(link))
+      .rejects.toThrow(MissingWorkspaceDirectoryError)
+  })
+
+  it('resolves a relative path before reporting it', async () => {
+    await expect(assertWorkspaceDirectoryExists('definitely-not-here'))
+      .rejects.toThrow(path.resolve('definitely-not-here'))
+  })
+})
diff --git a/src/main/workspaceDirectory.ts b/src/main/workspaceDirectory.ts
new file mode 100644
index 00000000..2678406e
--- /dev/null
+++ b/src/main/workspaceDirectory.ts
@@ -0,0 +1,62 @@
+import { stat } from 'node:fs/promises'
+import path from 'node:path'
+
+/**
+ * The session's workspace directory is gone from disk.
+ *
+ * WHY this is a typed error carrying a quotable message, when every other
+ * spawn failure is deliberately flattened to "Session failed to start. Check
+ * provider setup and retry.": that flattening exists to keep provider launch
+ * exceptions — which can contain environment values, proxy URLs and scoped
+ * MCP tokens — off IPC. A missing cwd carries none of that. The path is
+ * already rendered in the pane header, and this is the one start failure the
+ * user can actually act on.
+ */
+export class MissingWorkspaceDirectoryError extends Error {
+  constructor(readonly cwd: string) {
+    super(`Workspace folder is missing: ${cwd}`)
+    this.name = 'MissingWorkspaceDirectoryError'
+  }
+}
+
+/**
+ * Resolve-and-stat a spawn cwd before any backend is started.
+ *
+ * WHY this check exists at all: node-pty performs the chdir INSIDE the forked
+ * child (`node_modules/node-pty/src/unix/pty.cc`: `if (chdir(cwd_) == -1)
+ * _exit(1)`). A deleted directory therefore produces a *successful* PTY
+ * creation followed by an immediate exit(1), and every layer above reports
+ * good news on the way up: the provider start resolves ok, `recover()`
+ * returns `ok: true` with disposition 'spawned', and the failure only
+ * surfaces much later as the readiness wait giving up with "Agent exited
+ * before it became ready for input (start-failed)".
+ *
+ * That is exactly what the 2026-09-08 incident journal shows for six sessions
+ * whose git worktrees had been deleted 33 minutes before the app launched.
+ * The message named neither the directory nor the cause, so the failure read
+ * as a mysterious provider fault.
+ *
+ * Trading one stat() per spawn for an error that says what is actually wrong
+ * is worth it here in particular, because worktree-per-branch is the standing
+ * workflow in this repo: panes routinely outlive the directory they were
+ * opened in.
+ *
+ * WHY stat and not lstat: symlinked worktrees are common, and the question is
+ * only whether the child's chdir will succeed. chdir follows symlinks, so a
+ * dangling symlink must fail here for the same reason a deleted directory
+ * does, and reporting one message for both is the correct answer.
+ */
+export async function assertWorkspaceDirectoryExists(cwd: string): Promise<void> {
+  const resolved = path.resolve(cwd)
+  let isDirectory: boolean
+  try {
+    isDirectory = (await stat(resolved)).isDirectory()
+  } catch {
+    // Anything that makes the directory unusable from here (ENOENT, ENOTDIR,
+    // a dangling symlink, EACCES on a parent) would fail the child's chdir
+    // for the same practical reason. One message keeps the user pointed at
+    // the folder rather than at an errno.
+    throw new MissingWorkspaceDirectoryError(resolved)
+  }
+  if (!isDirectory) throw new MissingWorkspaceDirectoryError(resolved)
+}
diff --git a/src/renderer/src/app-state/settings/storage.renderer.test.ts b/src/renderer/src/app-state/settings/storage.renderer.test.ts
new file mode 100644
index 00000000..68b6ea65
--- /dev/null
+++ b/src/renderer/src/app-state/settings/storage.renderer.test.ts
@@ -0,0 +1,77 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { createSettingsStorage } from './storage'
+
+// WHY this suite exists at all:
+//
+// createSettingsStorage's "storage is unavailable" guard only caught a THROWN
+// access, which is the browser storage-denied case. It did not catch storage
+// being merely absent — which is exactly what the renderer test environment
+// provides. The adapter was therefore handed out live, and every store write
+// died inside Zustand's persist middleware with "storage.setItem is not a
+// function". Seven agent-name reconciler tests failed that way from the day
+// they landed, and any future renderer test that writes a setting would have
+// joined them. These cases pin the guard so that cannot silently return.
+
+const original = Object.getOwnPropertyDescriptor(window, 'localStorage')
+
+function stubStorage(value: unknown): void {
+  Object.defineProperty(window, 'localStorage', { configurable: true, value })
+}
+
+afterEach(() => {
+  if (original) Object.defineProperty(window, 'localStorage', original)
+  else Reflect.deleteProperty(window as unknown as Record<string, unknown>, 'localStorage')
+})
+
+describe('createSettingsStorage', () => {
+  it('returns undefined when storage is absent, rather than a broken adapter', () => {
+    stubStorage(undefined)
+    expect(createSettingsStorage()).toBeUndefined()
+  })
+
+  it('returns undefined when storage exists but is not a usable Storage', () => {
+    // The shape that actually shipped: present enough to pass a truthiness
+    // check, useless the moment persist calls it.
+    stubStorage({})
+    expect(createSettingsStorage()).toBeUndefined()
+  })
+
+  it('returns undefined when only some Storage methods are present', () => {
+    stubStorage({ getItem: () => null, setItem: () => {} })
+    expect(createSettingsStorage()).toBeUndefined()
+  })
+
+  it('returns undefined when the access itself throws', () => {
+    Object.defineProperty(window, 'localStorage', {
+      configurable: true,
+      get() { throw new Error('denied by policy') },
+    })
+    expect(createSettingsStorage()).toBeUndefined()
+  })
+
+  it('writes through to a usable Storage', () => {
+    const setItem = vi.fn()
+    stubStorage({ getItem: vi.fn(() => null), setItem, removeItem: vi.fn() })
+    const adapter = createSettingsStorage()
+    expect(adapter).toBeDefined()
+
+    adapter?.setItem('agent-code', { version: 1, state: { settings: { a: 1 } } } as never)
+    expect(setItem).toHaveBeenCalledTimes(1)
+    expect(setItem.mock.calls[0][0]).toBe('agent-code')
+  })
+
+  it('skips a repeat write of the same settings object', () => {
+    // The whole reason this adapter exists instead of createJSONStorage:
+    // persist runs after EVERY action, including stream ticks that never
+    // touch settings.
+    const setItem = vi.fn()
+    stubStorage({ getItem: vi.fn(() => null), setItem, removeItem: vi.fn() })
+    const adapter = createSettingsStorage()
+    const settings = { a: 1 }
+
+    adapter?.setItem('agent-code', { version: 1, state: { settings } } as never)
+    adapter?.setItem('agent-code', { version: 1, state: { settings } } as never)
+    expect(setItem).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/src/renderer/src/app-state/settings/storage.ts b/src/renderer/src/app-state/settings/storage.ts
index 7ade9f19..28eb2b38 100644
--- a/src/renderer/src/app-state/settings/storage.ts
+++ b/src/renderer/src/app-state/settings/storage.ts
@@ -21,7 +21,36 @@ type PersistedSettings = { settings: Settings }
 export function createSettingsStorage(): PersistStorage<PersistedSettings> | undefined {
   let storage: Storage
   try {
-    storage = localStorage
+    // WHY this checks the METHODS and not just that the access succeeded:
+    //
+    // The original guard only caught a THROWN access, which is the browser
+    // "storage denied" case. It did not catch storage being merely absent.
+    // Under the renderer test environment (`happy-dom`) `localStorage` is
+    // defined-but-undefined, so the assignment succeeded, this function
+    // returned a live adapter, and every store write then died inside
+    // Zustand's persist middleware with "storage.setItem is not a function".
+    // That silently broke all seven agent-name reconciler tests the moment
+    // they touched `useAppStore.setState`, and it would do the same to any
+    // future renderer test that writes a setting.
+    //
+    // Returning undefined here is the documented contract for "storage is
+    // unavailable" — Zustand then skips persistence entirely, which is the
+    // correct behavior in a test or on a surface with no storage, rather than
+    // throwing on an unrelated store action.
+    //
+    // Deliberately the BARE global rather than `window.localStorage`: the
+    // migration suites drive this through `vi.stubGlobal('localStorage', …)`,
+    // which replaces the global binding and not a `window` property. In every
+    // real surface (Electron renderer, phone bundle) the two are the same
+    // object anyway.
+    const candidate: Storage | undefined = localStorage
+    if (
+      !candidate ||
+      typeof candidate.getItem !== 'function' ||
+      typeof candidate.setItem !== 'function' ||
+      typeof candidate.removeItem !== 'function'
+    ) return undefined
+    storage = candidate
   } catch {
     // Match Zustand's createJSONStorage behavior when storage is unavailable
     // during SSR/test bootstrap or denied by the browser environment.
diff --git a/src/renderer/src/features/command-palette/ui/CommandPalette.tsx b/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
index 1d30e52d..66ad4341 100644
--- a/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
+++ b/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
@@ -1343,6 +1343,10 @@ function OpenCommandPalette({
         if (result.delivered) {
           workspace.showPaneToast(sessionId, `Inserted template: ${template.title}`)
           onClose()
+        } else if (result.reason === 'refused') {
+          // The terminal's own words: which rule the text broke. A multiline
+          // template into a program without bracketed paste is the common one.
+          workspace.showPaneToast(sessionId, result.message)
         } else if (result.reason === 'write-rejected') {
           workspace.showPaneToast(sessionId, 'Terminal write was rejected — pane is not ready')
         } else {
@@ -1515,6 +1519,8 @@ function OpenCommandPalette({
       if (result.delivered) {
         workspace.showPaneToast(sessionId, `Inserted template: ${fill.template.title}`)
         onClose()
+      } else if (result.reason === 'refused') {
+        workspace.showPaneToast(sessionId, result.message)
       } else if (result.reason === 'write-rejected') {
         workspace.showPaneToast(sessionId, 'Terminal write was rejected — pane is not ready')
       } else {
diff --git a/src/renderer/src/features/key-vault/ui/KeyVaultModal.tsx b/src/renderer/src/features/key-vault/ui/KeyVaultModal.tsx
index 953b29cf..f7e3645d 100644
--- a/src/renderer/src/features/key-vault/ui/KeyVaultModal.tsx
+++ b/src/renderer/src/features/key-vault/ui/KeyVaultModal.tsx
@@ -5,6 +5,7 @@ import {
   Dialog,
   DialogContent,
   DialogDescription,
+  DialogFooter,
   DialogHeader,
   DialogTitle,
 } from '@renderer/components/ui/dialog'
@@ -22,11 +23,24 @@ import type { KeyVaultKey, KeyVaultStatus } from '@shared/types/keyVault'
 // is what triggers Touch ID / the login-password prompt.
 //
 // DISCLOSURE (review finding): once a key is INSERTED, it leaves the
-// vault's protection by design — a composer draft autosaves to
-// workspace.json in plaintext until sent or cleared, and a PTY paste
-// lands in scrollback/tmux history. Submitting the prompt puts the key
-// in the provider transcript, plaintext, exactly like a manual paste.
-// The vault encrypts STORAGE, not the prompt pipeline.
+// vault's protection by design. The vault encrypts STORAGE, not the
+// prompt pipeline. The full list of places an inserted key comes to
+// rest, which is longer than this comment used to admit:
+//
+//   1. The composer draft, autosaved to workspace.json in PLAINTEXT
+//      (useAutoSave writes runtime.draftInput for every session with
+//      one), until the prompt is sent or the draft is cleared.
+//   2. "Clear draft" does not end that — the cleared text is retained
+//      for undo (draft.ts's clearedDrafts), so it stays recoverable.
+//   3. A PTY paste lands in xterm scrollback and in tmux history.
+//   4. Submitting puts it in the provider transcript, plaintext,
+//      exactly like a manual paste.
+//   5. If proxy streaming is on, the mitm addon base64-encodes outbound
+//      request bodies into the proxy events journal under
+//      ~/.config/agent-code/proxy, which nothing prunes or rotates.
+//
+// Anything meant to stay secret should be given to the agent by a path
+// that does not go through a prompt at all.
 
 type KeyForm = { id?: string; name: string; value: string; note: string } | null
 
@@ -189,6 +203,10 @@ export function KeyVaultModal() {
       if (result.delivered) {
         workspace.showPaneToast(sessionId, `Inserted key: ${key.name}`)
         closeKeyVault()
+      } else if (result.reason === 'refused') {
+        // The terminal's own words: which rule the text broke, not a generic
+        // failure. A key with a stray control byte is worth naming exactly.
+        setError(result.message)
       } else if (result.reason === 'write-rejected') {
         setError('Terminal write was rejected — pane is not ready; try again')
       } else {
@@ -206,8 +224,12 @@ export function KeyVaultModal() {
 
   return (
     <Dialog open onOpenChange={nextOpen => { if (!nextOpen) closeKeyVault() }}>
-      <DialogContent className="flex max-h-[85vh] w-[min(760px,calc(100vw-2rem))] flex-col">
-        <DialogHeader className="flex-row items-center justify-between gap-4">
+      <DialogContent className="flex max-h-[85vh] w-[min(760px,calc(100vw-2rem))] flex-col overflow-hidden">
+        {/* `flex` has to accompany `flex-row` here. DialogHeader's base class
+            list is a plain block, so flex-row/items-center/justify-between
+            were all inert and "Lock now" stacked underneath the description
+            instead of sitting opposite the title. */}
+        <DialogHeader className="flex flex-row items-center justify-between gap-4">
           <div className="min-w-0">
             <DialogTitle className="font-semibold">API Key Vault</DialogTitle>
             <DialogDescription className="mt-0.5 text-[10px]">
@@ -222,6 +244,7 @@ export function KeyVaultModal() {
             <Button
               variant="outline"
               size="sm"
+              className="shrink-0"
               onClick={() => {
                 // Clear visible plaintext BEFORE locking: a "locked"
                 // status line over revealed secrets was a review finding.
@@ -234,208 +257,243 @@ export function KeyVaultModal() {
           )}
         </DialogHeader>
 
-        {status && !status.encryptionAvailable && (
-          <div className="text-[11px] text-ink bg-surface border border-border rounded px-2 py-1">
-            OS keyring (safeStorage) is unavailable on this machine — keys cannot be stored.
-          </div>
-        )}
-        {error && (
-          <div className="text-[11px] text-ink bg-surface border border-border rounded px-2 py-1">{error}</div>
-        )}
+        {/* DialogContent carries NO padding by design — DialogHeader and
+            DialogFooter own their own px-4 py-3 and every feature modal pads
+            its own body (see ViewPromptsModal / RewindToPromptModal). This
+            wrapper is that body. Without it the provider list, key rows and
+            footnote rendered flush against the dialog border on all four
+            sides, which is exactly how this shipped. */}
+        <div className="flex min-h-0 flex-1 flex-col gap-2 px-4 py-3">
+          {status && !status.encryptionAvailable && (
+            <div className="rounded-slab border border-border bg-canvas px-2 py-1 text-[11px] text-ink">
+              OS keyring (safeStorage) is unavailable on this machine — keys cannot be stored.
+            </div>
+          )}
+          {error && (
+            <div className="rounded-slab border border-border bg-canvas px-2 py-1 text-[11px] text-ink">
+              {error}
+            </div>
+          )}
 
-        {!status?.unlocked && <Button onClick={() => void refresh()}>Unlock Vault</Button>}
-        {status?.unlocked && <div className="flex flex-col sm:flex-row flex-1 min-h-0 gap-3 overflow-y-auto">
-          <div className="sm:w-48 shrink-0 flex flex-col gap-1 overflow-y-auto pr-1">
-            {providers.map(provider => (
-              <button
-                key={provider.id}
-                className={`text-left px-2 py-1 rounded-chip truncate text-xs ${
-                  provider.id === selectedProviderId
-                    ? 'bg-surface text-ink'
-                    : 'text-muted hover:text-ink'
-                }`}
-                onClick={() => { setSelectedProviderId(provider.id); setKeyForm(null); setProviderRename(null) }}
-                title={provider.name}
-              >
-                {provider.name}
-              </button>
-            ))}
-            <input
-              className="bg-surface border border-border rounded-chip px-2 py-1 text-xs mt-2"
-              placeholder="New provider…"
-              value={newProviderName}
-              onChange={e => setNewProviderName(e.target.value)}
-              onKeyDown={e => { if (e.key === 'Enter') addProvider() }}
-            />
-          </div>
+          {!status?.unlocked && (
+            <Button className="self-start" onClick={() => void refresh()}>
+              Unlock Vault
+            </Button>
+          )}
 
-          <div className="flex-1 min-w-0 overflow-y-auto flex flex-col gap-2">
-            {!selectedProvider && (
-              <div className="text-muted text-xs">Create a provider to get started.</div>
-            )}
-            {selectedProvider && (
-              <>
-                <div className="flex items-center justify-between gap-2">
-                  <span className="text-ink font-semibold text-sm">{selectedProvider.name}</span>
-                  <div className="flex items-center gap-2">
-                    <button
-                      className="text-[11px] text-muted hover:text-ink"
-                      onClick={() =>
-                        setProviderRename({ id: selectedProvider.id, name: selectedProvider.name })
-                      }
-                    >
-                      Rename
-                    </button>
-                    <button
-                      className="text-[11px] text-muted hover:text-ink"
-                      onClick={() => {
-                        if (window.confirm(`Delete provider "${selectedProvider.name}" and all its keys?`)) {
-                          void runVaultAction(() =>
-                            window.api.keyVaultDeleteProvider(selectedProvider.id),
-                          )
-                        }
-                      }}
-                    >
-                      Delete
-                    </button>
-                    <Button
-                      variant="outline"
-                      size="sm"
-                      onClick={() => setKeyForm({ name: '', value: '', note: '' })}
-                    >
-                      + New Key
-                    </Button>
-                  </div>
-                </div>
+          {/* Only the two columns scroll. Scrolling the ROW as well (as it did)
+              meant the provider list slid out of view with the key list and
+              produced a second nested scrollbar on the same axis. */}
+          {status?.unlocked && (
+            <div className="flex min-h-0 flex-1 flex-col gap-3 sm:flex-row">
+              {/* `sm:shrink-0`, NOT `shrink-0`, and `min-h-0` on both axes'
+                  worth of layout: below the sm breakpoint this row stacks as a
+                  COLUMN, and a non-shrinking child there takes its full content
+                  height. With the outer scroller removed, a long provider list
+                  then grew past the dialog and the new overflow-hidden clipped
+                  the bottom of it — including "New provider…" — with no
+                  scrollbar able to reach it, because the column's own
+                  overflow-y-auto cannot help an element that was never
+                  constrained. Shrinking only in the row direction keeps the
+                  fixed 12rem sidebar the wide layout wants. */}
+              <div className="flex min-h-0 flex-col gap-1 overflow-y-auto pr-1 sm:w-48 sm:shrink-0">
+                {providers.map(provider => (
+                  <button
+                    key={provider.id}
+                    className={`truncate rounded-chip px-2 py-1 text-left text-xs ${
+                      provider.id === selectedProviderId
+                        ? 'bg-canvas text-ink'
+                        : 'text-muted hover:text-ink'
+                    }`}
+                    onClick={() => { setSelectedProviderId(provider.id); setKeyForm(null); setProviderRename(null) }}
+                    title={provider.name}
+                  >
+                    {provider.name}
+                  </button>
+                ))}
+                <input
+                  className="mt-2 rounded-chip border border-border bg-canvas px-2 py-1 text-xs"
+                  placeholder="New provider…"
+                  value={newProviderName}
+                  onChange={e => setNewProviderName(e.target.value)}
+                  onKeyDown={e => { if (e.key === 'Enter') addProvider() }}
+                />
+              </div>
 
-                {providerRename && providerRename.id === selectedProvider.id && (
-                  <div className="flex gap-2 items-center">
-                    <input
-                      className="flex-1 bg-canvas border border-border rounded-chip px-2 py-1 text-xs"
-                      value={providerRename.name}
-                      placeholder="Provider name"
-                      onChange={e => setProviderRename({ ...providerRename, name: e.target.value })}
-                      onKeyDown={e => {
-                        if (e.key !== 'Enter') return
-                        const name = providerRename.name.trim()
-                        if (!name) return
-                        const id = providerRename.id
-                        setProviderRename(null)
-                        void runVaultAction(() => window.api.keyVaultRenameProvider(id, name))
-                      }}
-                    />
-                    <Button variant="ghost" size="sm" onClick={() => setProviderRename(null)}>Cancel</Button>
-                    <Button
-                      size="sm"
-                      onClick={() => {
-                        const name = providerRename.name.trim()
-                        if (!name) return
-                        const id = providerRename.id
-                        setProviderRename(null)
-                        void runVaultAction(() => window.api.keyVaultRenameProvider(id, name))
-                      }}
-                    >
-                      Save
-                    </Button>
-                  </div>
+              <div className="flex min-h-0 min-w-0 flex-1 flex-col gap-2 overflow-y-auto">
+                {!selectedProvider && (
+                  <div className="text-xs text-muted">Create a provider to get started.</div>
                 )}
-
-                {selectedKeys.map(key => (
-                  <div key={key.id} className="border border-border rounded-chip p-2 flex flex-col gap-1 bg-surface">
-                    <div className="flex flex-wrap items-center gap-2 min-w-0 text-xs">
-                      <span className="text-ink truncate">{key.name}</span>
-                      <span className="text-[10px] text-muted shrink-0">••••{key.hint}</span>
-                      {revealed.has(key.id) && (
-                        <span
-                          className="text-[10px] text-ink truncate max-w-[220px]"
-                          title={revealed.get(key.id)}
-                        >
-                          {revealed.get(key.id)}
-                        </span>
-                      )}
-                      <span className="flex-1" />
-                      <button
-                        className="text-[11px] text-muted hover:text-ink shrink-0"
-                        onClick={() => void toggleReveal(key)}
-                      >
-                        {revealed.has(key.id) ? 'Hide' : 'Reveal'}
-                      </button>
-                      <button
-                        className="text-[11px] text-muted hover:text-ink shrink-0"
-                        onClick={() =>
-                          void runVaultAction(() => window.api.keyVaultCopyKey(key.providerId, key.id))
-                        }
-                      >
-                        Copy
-                      </button>
-                      <button
-                        className="text-[11px] text-ink shrink-0"
-                        onClick={() => void insertKey(key)}
-                      >
-                        Insert
-                      </button>
-                      <button
-                        className="text-[11px] text-muted hover:text-ink shrink-0"
-                        onClick={() => setKeyForm({ id: key.id, name: key.name, value: '', note: key.note })}
-                      >
-                        Edit
-                      </button>
-                      <button
-                        className="text-[11px] text-muted hover:text-ink shrink-0"
-                        onClick={() => {
-                          if (window.confirm(`Delete key "${key.name}"?`)) {
-                            void runVaultAction(() =>
-                              window.api.keyVaultDeleteKey(key.providerId, key.id),
-                            )
+                {selectedProvider && (
+                  <>
+                    <div className="flex items-center justify-between gap-2">
+                      <span className="truncate text-sm font-semibold text-ink">{selectedProvider.name}</span>
+                      <div className="flex shrink-0 items-center gap-2">
+                        <button
+                          className="text-[11px] text-muted hover:text-ink"
+                          onClick={() =>
+                            setProviderRename({ id: selectedProvider.id, name: selectedProvider.name })
                           }
-                        }}
-                      >
-                        Delete
-                      </button>
+                        >
+                          Rename
+                        </button>
+                        <button
+                          className="text-[11px] text-muted hover:text-ink"
+                          onClick={() => {
+                            if (window.confirm(`Delete provider "${selectedProvider.name}" and all its keys?`)) {
+                              void runVaultAction(() =>
+                                window.api.keyVaultDeleteProvider(selectedProvider.id),
+                              )
+                            }
+                          }}
+                        >
+                          Delete
+                        </button>
+                        <Button
+                          variant="outline"
+                          size="sm"
+                          onClick={() => setKeyForm({ name: '', value: '', note: '' })}
+                        >
+                          + New Key
+                        </Button>
+                      </div>
                     </div>
-                    {key.note && <div className="text-[10px] text-muted truncate">{key.note}</div>}
-                  </div>
-                ))}
 
-                {keyForm && (
-                  <div className="border border-border rounded-chip p-3 flex flex-col gap-2 bg-surface">
-                    <div className="text-xs text-ink">{keyForm.id ? 'Edit key' : 'New key'}</div>
-                    <input
-                      className="bg-canvas border border-border rounded-chip px-2 py-1 text-xs"
-                      placeholder="Key name (e.g. main)"
-                      value={keyForm.name}
-                      onChange={e => setKeyForm({ ...keyForm, name: e.target.value })}
-                    />
-                    <input
-                      className="bg-canvas border border-border rounded-chip px-2 py-1 text-xs"
-                      type="password"
-                      placeholder={keyForm.id ? 'Value (leave blank to keep current)' : 'Value'}
-                      value={keyForm.value}
-                      onChange={e => setKeyForm({ ...keyForm, value: e.target.value })}
-                    />
-                    <input
-                      className="bg-canvas border border-border rounded-chip px-2 py-1 text-xs"
-                      placeholder="Note (optional)"
-                      value={keyForm.note}
-                      onChange={e => setKeyForm({ ...keyForm, note: e.target.value })}
-                    />
-                    <div className="flex gap-2 justify-end">
-                      <Button variant="ghost" size="sm" onClick={() => setKeyForm(null)}>Cancel</Button>
-                      <Button size="sm" onClick={saveKeyForm}>Save</Button>
-                    </div>
-                  </div>
+                    {providerRename && providerRename.id === selectedProvider.id && (
+                      <div className="flex items-center gap-2">
+                        <input
+                          className="flex-1 rounded-chip border border-border bg-canvas px-2 py-1 text-xs"
+                          value={providerRename.name}
+                          placeholder="Provider name"
+                          onChange={e => setProviderRename({ ...providerRename, name: e.target.value })}
+                          onKeyDown={e => {
+                            if (e.key !== 'Enter') return
+                            const name = providerRename.name.trim()
+                            if (!name) return
+                            const id = providerRename.id
+                            setProviderRename(null)
+                            void runVaultAction(() => window.api.keyVaultRenameProvider(id, name))
+                          }}
+                        />
+                        <Button variant="ghost" size="sm" onClick={() => setProviderRename(null)}>Cancel</Button>
+                        <Button
+                          size="sm"
+                          onClick={() => {
+                            const name = providerRename.name.trim()
+                            if (!name) return
+                            const id = providerRename.id
+                            setProviderRename(null)
+                            void runVaultAction(() => window.api.keyVaultRenameProvider(id, name))
+                          }}
+                        >
+                          Save
+                        </Button>
+                      </div>
+                    )}
+
+                    {selectedKeys.map(key => (
+                      <div key={key.id} className="flex flex-col gap-1 rounded-slab border border-border bg-canvas p-2">
+                        <div className="flex min-w-0 flex-wrap items-center gap-2 text-xs">
+                          <span className="truncate text-ink">{key.name}</span>
+                          <span className="shrink-0 text-[10px] text-muted">••••{key.hint}</span>
+                          {revealed.has(key.id) && (
+                            // WHY no `title` attribute here, and why it wraps
+                            // instead of truncating: a `title` puts the
+                            // plaintext secret into an OS tooltip and into the
+                            // accessibility tree, where it is readable by
+                            // anything that can query the DOM and is rendered
+                            // by the window server outside this surface's
+                            // control. Truncating created the need for that
+                            // tooltip, so the fix is to let the value wrap and
+                            // be fully visible in the row instead.
+                            <span className="min-w-0 text-[10px] text-ink [overflow-wrap:anywhere]">
+                              {revealed.get(key.id)}
+                            </span>
+                          )}
+                          <span className="flex-1" />
+                          <button
+                            className="shrink-0 text-[11px] text-muted hover:text-ink"
+                            onClick={() => void toggleReveal(key)}
+                          >
+                            {revealed.has(key.id) ? 'Hide' : 'Reveal'}
+                          </button>
+                          <button
+                            className="shrink-0 text-[11px] text-muted hover:text-ink"
+                            onClick={() =>
+                              void runVaultAction(() => window.api.keyVaultCopyKey(key.providerId, key.id))
+                            }
+                          >
+                            Copy
+                          </button>
+                          <button
+                            className="shrink-0 text-[11px] text-ink"
+                            onClick={() => void insertKey(key)}
+                          >
+                            Insert
+                          </button>
+                          <button
+                            className="shrink-0 text-[11px] text-muted hover:text-ink"
+                            onClick={() => setKeyForm({ id: key.id, name: key.name, value: '', note: key.note })}
+                          >
+                            Edit
+                          </button>
+                          <button
+                            className="shrink-0 text-[11px] text-muted hover:text-ink"
+                            onClick={() => {
+                              if (window.confirm(`Delete key "${key.name}"?`)) {
+                                void runVaultAction(() =>
+                                  window.api.keyVaultDeleteKey(key.providerId, key.id),
+                                )
+                              }
+                            }}
+                          >
+                            Delete
+                          </button>
+                        </div>
+                        {key.note && <div className="truncate text-[10px] text-muted">{key.note}</div>}
+                      </div>
+                    ))}
+
+                    {keyForm && (
+                      <div className="flex flex-col gap-2 rounded-slab border border-border bg-canvas p-3">
+                        <div className="text-xs text-ink">{keyForm.id ? 'Edit key' : 'New key'}</div>
+                        <input
+                          className="rounded-chip border border-border bg-surface px-2 py-1 text-xs"
+                          placeholder="Key name (e.g. main)"
+                          value={keyForm.name}
+                          onChange={e => setKeyForm({ ...keyForm, name: e.target.value })}
+                        />
+                        <input
+                          className="rounded-chip border border-border bg-surface px-2 py-1 text-xs"
+                          type="password"
+                          placeholder={keyForm.id ? 'Value (leave blank to keep current)' : 'Value'}
+                          value={keyForm.value}
+                          onChange={e => setKeyForm({ ...keyForm, value: e.target.value })}
+                        />
+                        <input
+                          className="rounded-chip border border-border bg-surface px-2 py-1 text-xs"
+                          placeholder="Note (optional)"
+                          value={keyForm.note}
+                          onChange={e => setKeyForm({ ...keyForm, note: e.target.value })}
+                        />
+                        <div className="flex justify-end gap-2">
+                          <Button variant="ghost" size="sm" onClick={() => setKeyForm(null)}>Cancel</Button>
+                          <Button size="sm" onClick={saveKeyForm}>Save</Button>
+                        </div>
+                      </div>
+                    )}
+                  </>
                 )}
-              </>
-            )}
-          </div>
+              </div>
+            </div>
+          )}
         </div>
 
-        }
-        <div className="text-[10px] text-muted border-t border-border pt-2">
+        <DialogFooter className="justify-start text-[10px] leading-relaxed text-muted">
           Reference keys from prompt templates with {'{{key:Provider/Key}}'} · Encrypted with the OS
           keyring · One unlock per app launch · An inserted key sits in the saved draft (or terminal
           scrollback) until sent or cleared
-        </div>
+        </DialogFooter>
       </DialogContent>
     </Dialog>
   )
diff --git a/src/renderer/src/features/prompt-templates/keyReferences.test.ts b/src/renderer/src/features/prompt-templates/keyReferences.test.ts
index e071d721..34460db3 100644
--- a/src/renderer/src/features/prompt-templates/keyReferences.test.ts
+++ b/src/renderer/src/features/prompt-templates/keyReferences.test.ts
@@ -52,3 +52,78 @@ describe('resolveKeyReferences', () => {
     ).rejects.toThrow(/Brave\/a.*OpenAI\/b/)
   })
 })
+
+describe('what the grammar deliberately does NOT capture', () => {
+  it('leaves ordinary JSX alone, including a slash inside the value', () => {
+    // A widened pattern that tried to diagnose typos captured all of these and
+    // aborted insertion on templates that had always worked, with no way to
+    // escape the syntax — not even inside a code fence. Breaking text nobody
+    // intended as syntax is worse than failing to diagnose a typo.
+    const bodies = [
+      '<Widget options={{key: value}} />',
+      '<Widget options={{key: "/api/v1"}} />',
+      '<Widget options={{key: /abc/}} />',
+      'log line: {{key:A/B/C}} from the pasted output',
+      'use {{key:Brave}} now',
+    ]
+    for (const body of bodies) {
+      expect(collectKeyReferences(body)).toEqual([])
+    }
+  })
+
+  it('still resolves a real reference sitting next to such text', async () => {
+    await expect(resolveKeyReferences(
+      '<Widget options={{key: "/api/v1"}} /> {{key:P/K}}',
+      async () => 'secret',
+    )).resolves.toBe('<Widget options={{key: "/api/v1"}} /> secret')
+  })
+
+  it('leaves an ordinary variable placeholder alone', async () => {
+    // The two grammars cannot collide: the placeholder pattern is
+    // [A-Za-z0-9_]+ and cannot contain a colon.
+    await expect(resolveKeyReferences('{{goal}} {{key:P/K}}', async () => 'secret'))
+      .resolves.toBe('{{goal}} secret')
+  })
+})
+
+describe('failing references', () => {
+  it('reports a thrown resolution failure with the service message', async () => {
+    // The production adapter is typed Promise<string> and VaultService throws
+    // on every failure mode, so the `value === null` branch this module was
+    // built around is unreachable. Without a catch the first bad reference
+    // escaped and the failure list was never built.
+    await expect(resolveKeyReferences('{{key:P/bad}}', async () => {
+      throw new Error('No such key')
+    })).rejects.toThrow('No such key')
+  })
+
+  it('asks the vault ONCE when the first reference fails', async () => {
+    // The reason the loop stops rather than continuing: one failure mode is a
+    // cancelled unlock, and ensureUnlocked clears its pending promise on
+    // cancellation — so carrying on to the next reference opens another OS
+    // authentication prompt. Three references would ask three times. A user
+    // who just cancelled must not be re-asked.
+    const asked: string[] = []
+    const resolve = async (ref: { providerName: string; keyName: string }) => {
+      asked.push(`${ref.providerName}/${ref.keyName}`)
+      throw new Error('Vault unlock was cancelled')
+    }
+
+    await expect(resolveKeyReferences('{{key:P/a}} {{key:P/b}} {{key:P/c}}', resolve))
+      .rejects.toThrow('Vault unlock was cancelled')
+    expect(asked).toEqual(['P/a'])
+  })
+
+  it('keeps the service message, which distinguishes locked from missing', async () => {
+    await expect(resolveKeyReferences('{{key:P/K}}', async () => {
+      throw new Error('Vault is locked')
+    })).rejects.toThrow('Vault is locked')
+  })
+
+  it('does not interpret a substitution pattern inside a secret', async () => {
+    // A function replacer, never a string: `$&` in a secret would otherwise be
+    // expanded into the matched text.
+    await expect(resolveKeyReferences('{{key:P/K}}', async () => 'sk-$&-$1'))
+      .resolves.toBe('sk-$&-$1')
+  })
+})
diff --git a/src/renderer/src/features/prompt-templates/keyReferences.ts b/src/renderer/src/features/prompt-templates/keyReferences.ts
index 1d46da22..99937226 100644
--- a/src/renderer/src/features/prompt-templates/keyReferences.ts
+++ b/src/renderer/src/features/prompt-templates/keyReferences.ts
@@ -31,14 +31,50 @@ export function prepareTemplateText(
 
 export type KeyReference = { providerName: string; keyName: string }
 
+/**
+ * A well-formed vault reference: exactly one separator, neither half
+ * containing another.
+ *
+ * WHY this pattern is NARROW, after an attempt to widen it was reverted:
+ *
+ * The narrowness has a real cost — a typo like `{{key:Brave}}` or
+ * `{{key:A/B/C}}` matches nothing and is pasted into the prompt verbatim,
+ * which is the silent failure the header paragraph above says this grammar
+ * exists to avoid. Widening it to catch those looked obviously right and was
+ * wrong: `{{key:…}}` with arbitrary contents is ordinary text.
+ * `<Widget options={{key: value}} />` is everyday JSX. So is
+ * `<Widget options={{key: "/api/v1"}} />` and `{{key: /abc/}}`, which a
+ * separator requirement does not exclude either — a slash does not establish
+ * that the author meant a vault reference. Templates that had always worked
+ * began aborting insertion outright, with no way to escape the syntax, not
+ * even inside a code fence.
+ *
+ * Breaking text nobody intended as syntax is worse than failing to diagnose a
+ * typo. Catching typos properly needs an escape mechanism this grammar does
+ * not have, so it is not attempted here.
+ */
 const KEY_REF_PATTERN = /\{\{\s*key:([^/{}]+?)\/([^/{}]+?)\s*\}\}/g
 
+function referenceKey(ref: KeyReference): string {
+  // NUL separator so two different (provider, key) pairs cannot produce the
+  // same map key. Unreachable through this pattern, which forbids a slash in
+  // either half, but the map is also written from the replace callback.
+  return `${ref.providerName}\u0000${ref.keyName}`
+}
+
+function parseAll(body: string): KeyReference[] {
+  return [...body.matchAll(KEY_REF_PATTERN)].map(match => ({
+    providerName: match[1].trim(),
+    keyName: match[2].trim(),
+  }))
+}
+
+/** Well-formed references, in first-appearance order, deduped. */
 export function collectKeyReferences(body: string): KeyReference[] {
   const seen = new Set<string>()
   const ordered: KeyReference[] = []
-  for (const match of body.matchAll(KEY_REF_PATTERN)) {
-    const ref = { providerName: match[1].trim(), keyName: match[2].trim() }
-    const dedupeKey = `${ref.providerName}\u0000${ref.keyName}`
+  for (const ref of parseAll(body)) {
+    const dedupeKey = referenceKey(ref)
     if (seen.has(dedupeKey)) continue
     seen.add(dedupeKey)
     ordered.push(ref)
@@ -54,21 +90,53 @@ export async function resolveKeyReferences(
   // String.replace callback cannot await, and each ref may cross the
   // vault gate), collecting ALL failures so one error message tells the
   // user everything that needs fixing.
-  const refs = collectKeyReferences(body)
   const values = new Map<string, string>()
   const failures: string[] = []
-  for (const ref of refs) {
-    const value = await resolve(ref)
+  const seen = new Set<string>()
+
+  for (const ref of parseAll(body)) {
+    const dedupeKey = referenceKey(ref)
+    if (seen.has(dedupeKey)) continue
+    seen.add(dedupeKey)
+
+    // WHY the call is wrapped AND why the loop stops on the first throw:
+    //
+    // Wrapped, because the aggregation this function is built around was dead
+    // code in production. The real adapter is
+    // `window.api.keyVaultResolveReference`, typed `Promise<string>`, and
+    // VaultService throws on every failure mode, so `value === null` was
+    // unreachable and the first bad reference escaped the loop entirely.
+    //
+    // Stopping, because continuing is worse than the bug it fixed. One of
+    // those failure modes is a CANCELLED unlock, and `ensureUnlocked` clears
+    // its pending promise on cancellation — so carrying on to the next
+    // reference opens another OS authentication prompt. A template with three
+    // references asked once before, and would ask three times if this
+    // continued. A user who just cancelled must not be re-asked.
+    //
+    // Whatever was collected before the failure is still reported alongside
+    // it, and the service's own message is kept because it is written for
+    // direct display and distinguishes "no such key" from "vault is locked".
+    let value: string | null
+    try {
+      value = await resolve(ref)
+    } catch (error) {
+      const detail = error instanceof Error && error.message.length > 0 ? error.message : null
+      failures.push(`{{key:${ref.providerName}/${ref.keyName}}}${detail ? ` (${detail})` : ''}`)
+      break
+    }
     if (value === null || value.length === 0) {
       failures.push(`{{key:${ref.providerName}/${ref.keyName}}}`)
       continue
     }
-    values.set(`${ref.providerName}\u0000${ref.keyName}`, value)
+    values.set(dedupeKey, value)
   }
+
   if (failures.length > 0) {
     throw new Error(`Unresolved key reference: ${failures.join(', ')}`)
   }
-  return body.replace(KEY_REF_PATTERN, (_match, rawProvider: string, rawKey: string) => {
-    return values.get(`${rawProvider.trim()}\u0000${rawKey.trim()}`) ?? ''
-  })
+  // A function replacer, never a string: `$&` or `$1` inside a SECRET would
+  // otherwise be interpreted as a substitution pattern.
+  return body.replace(KEY_REF_PATTERN, (_match, rawProvider: string, rawKey: string) =>
+    values.get(referenceKey({ providerName: rawProvider.trim(), keyName: rawKey.trim() })) ?? '')
 }
diff --git a/src/renderer/src/features/session-text-delivery/deliverTextToSession.ts b/src/renderer/src/features/session-text-delivery/deliverTextToSession.ts
index d1e1d0e6..e1bf54b6 100644
--- a/src/renderer/src/features/session-text-delivery/deliverTextToSession.ts
+++ b/src/renderer/src/features/session-text-delivery/deliverTextToSession.ts
@@ -25,17 +25,42 @@ import type { Workspace } from '@renderer/workspace/workspaceStore'
 // not enabled bracketed paste receives single-line text only. Multiline
 // input is refused rather than risking accidental command execution.
 //
-// SECRET DISCLOSURE (review finding): text inserted into a composer
-// draft follows the SAME persistence rules as any draft — it autosaves
-// to workspace.json in plaintext until sent or cleared. Inserted into a
-// PTY it lands in scrollback (and tmux history). That is inherent to
-// insertion itself, not this helper: once the user submits, the secret
-// reaches the provider transcript in plaintext anyway. The VAULT's
-// encryption contract covers storage, not the prompt pipeline.
+// SECRET DISCLOSURE (review finding): inserted text follows the SAME
+// persistence rules as anything else the user could have typed, which is
+// inherent to insertion rather than to this helper. The complete list of
+// resting places, because an earlier version of this comment named only
+// the first and third and that understated it:
+//
+//   1. A composer draft autosaves to workspace.json in PLAINTEXT
+//      (useAutoSave persists runtime.draftInput for every session that
+//      has one), until the prompt is sent or the draft is cleared.
+//   2. Clearing the draft does not end that: the cleared text is kept
+//      for undo (draft.ts's clearedDrafts), so it stays recoverable.
+//   3. A PTY paste lands in xterm scrollback and in tmux history.
+//   4. Submitting puts it in the provider transcript, plaintext.
+//   5. With proxy streaming on, the mitm addon base64-encodes outbound
+//      request bodies into the proxy events journal under
+//      ~/.config/agent-code/proxy, which nothing prunes or rotates.
+//
+// The VAULT's encryption contract covers storage, not the prompt
+// pipeline, and this helper is the boundary where that stops applying.
 
 export type DeliverTextResult =
   | { delivered: true; surface: 'composer' | 'pty' }
   | { delivered: false; reason: 'no-session' | 'write-rejected' | 'cancelled' }
+  /**
+   * The terminal refused this exact text, with a reason worth showing.
+   *
+   * WHY a result variant and not the exception it used to be: `encodeTerminalPaste`
+   * throws for control characters and for multiline input into a program that
+   * has not enabled bracketed paste. That threw straight out of a function
+   * whose result union claimed to describe every outcome, so whether the user
+   * ever saw the reason depended on each caller happening to wrap the call in
+   * try/catch — and on a plain terminal pane, which rendered no toast at all
+   * until recently, a multiline template was a total silent no-op. A refusal
+   * is an ANSWER, so it is returned like one.
+   */
+  | { delivered: false; reason: 'refused'; message: string }
 
 export async function deliverTextToSession(
   workspace: Workspace,
@@ -95,8 +120,22 @@ async function deliverPtyText(
   if (isCurrent && !isCurrent()) return { delivered: false, reason: 'cancelled' }
   // Do not follow a changed/mirrored target after wake or retry into a
   // replacement process. A refused write keeps the picker open for the user.
-  if (getTerminalPasteTarget(sessionId) === target && await target.paste(text)) {
-    return { delivered: true, surface: 'pty' }
+  if (getTerminalPasteTarget(sessionId) !== target) return { delivered: false, reason: 'write-rejected' }
+  let accepted: boolean
+  try {
+    accepted = await target.paste(text)
+  } catch (error) {
+    // encodeTerminalPaste's refusals are written for direct display and say
+    // exactly which rule the text broke.
+    return {
+      delivered: false,
+      reason: 'refused',
+      message: error instanceof Error && error.message.length > 0
+        ? error.message
+        : 'The terminal refused this text.',
+    }
   }
-  return { delivered: false, reason: 'write-rejected' }
+  return accepted
+    ? { delivered: true, surface: 'pty' }
+    : { delivered: false, reason: 'write-rejected' }
 }
diff --git a/src/renderer/src/features/workspace/commands/paneCommands.ts b/src/renderer/src/features/workspace/commands/paneCommands.ts
index a453cd80..57667750 100644
--- a/src/renderer/src/features/workspace/commands/paneCommands.ts
+++ b/src/renderer/src/features/workspace/commands/paneCommands.ts
@@ -561,7 +561,7 @@ export const paneCommands: CommandDef[] = [
     category: 'navigate',
     surface: 'session',
     title: 'Jump to Latest Message',
-    description: '**What it does:** Scrolls to the **latest agent message**.\n\n**Use when:** You are far up in the feed and want to return to the bottom.\n\n**Notes:** Agent panes only — in a raw terminal view this scrolls the TUI viewport to the bottom.',
+    description: '**What it does:** Scrolls to the **latest agent message**.\n\n**Use when:** You are far up in the feed and want to return to the bottom.\n\n**Notes:** Agent panes only. In a raw terminal view this scrolls the xterm viewport, which works for providers that render inline (Claude, Codex). A TUI that owns its own transcript on the alternate screen (OpenCode Terminal) keeps its history outside the viewport, so there is nothing here to scroll — use that TUI\'s own scroll keys.',
     // NO `renderedViewPolicy` — the xterm viewport answers jump requests too
     // (useAgentTerminalFollow); gating on a rendered feed would hide this on
     // the surface where returning to the bottom is most often needed.
diff --git a/src/renderer/src/features/workspace/ui/BulkProviderSwitchModal.tsx b/src/renderer/src/features/workspace/ui/BulkProviderSwitchModal.tsx
index 511da178..47d68d58 100644
--- a/src/renderer/src/features/workspace/ui/BulkProviderSwitchModal.tsx
+++ b/src/renderer/src/features/workspace/ui/BulkProviderSwitchModal.tsx
@@ -159,6 +159,26 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
   const [projectFilter, setProjectFilter] = useState('')
   const [busy, setBusy] = useState(false)
   const [switchingModel, setSwitchingModel] = useState(false)
+  // Refs so the open-reset effect can see the live values without depending on
+  // them — depending on them would re-run the reset the moment a loop ended.
+  const busyRef = useRef(busy)
+  busyRef.current = busy
+  const switchingModelRef = useRef(switchingModel)
+  switchingModelRef.current = switchingModel
+  /**
+   * The exact panes the source-compaction confirmation named.
+   *
+   * WHY a snapshot instead of re-reading `matchingRows` on the confirmed
+   * click: the confirmation is armed on the first click and consumed on the
+   * second, and every MANUAL way of changing the set (direction, scope,
+   * project toggle, select-all, clear, filter) disarms it. But `matchingRows`
+   * is a memo over live workspace state and changes on its own — an agent
+   * spawning, or one that was mid-turn going idle, silently joins the set
+   * between the two clicks. The user then confirms "compact 3 agents on Codex
+   * first" and four agents get their live history rewritten. Confirming a set
+   * has to mean confirming THAT set.
+   */
+  const [confirmedSessionIds, setConfirmedSessionIds] = useState<string[] | null>(null)
   // Live status (mid-turn) can change while the modal sits open. Re-tick every
   // 10s so the ⚠ skip count stays honest, matching Close Old Agents.
   const [nowTick, setNowTick] = useState(0)
@@ -209,10 +229,19 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
 
   useEffect(() => {
     if (!open) return
+    // Never reset over a loop that is still running. `open` is store state, so
+    // `closeBulkProviderSwitch` from a command or another surface can close
+    // this modal even while the guards above refuse Escape; reopening then ran
+    // this effect and cleared the very flag that single-flights the loop,
+    // letting a second batch start against the same panes. Both flags are
+    // cleared by their own `finally`, so skipping the reset here cannot strand
+    // them.
+    if (busyRef.current || switchingModelRef.current) return
     setDirectionChoice(null)
     setCompactOnArrivalChoice(null)
     setCompactOnSourceChoice(false)
     setSourceConfirmArmed(false)
+    setConfirmedSessionIds(null)
     setScopeMode('all')
     setSelectedProjects(new Set())
     setProjectFilter('')
@@ -336,22 +365,49 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
   // Biggest conversation in the batch, not the sum: arrival compaction runs
   // per agent, so the question is whether ANY single pane will land oversized.
   //
-  // The runtimes map is swapped for a frozen empty one while closed so the memo
-  // is not merely early-returning on a dependency that changes on every runtime
-  // tick — it stops being invalidated at all. This modal is a permanently
-  // mounted surface (see the usage hook gate above), and `workspace.runtimes`
-  // is one of the highest-churn references in the app.
-  const runtimesForEstimate = open ? workspace.runtimes : NO_RUNTIMES
+  // This modal is a permanently mounted surface (see the usage hook gate
+  // above), and `workspace.runtimes` is one of the highest-churn references in
+  // the app — which is what makes the dependency choice below load-bearing
+  // rather than cosmetic.
+  // WHY this is keyed on the session ids and reads runtimes through a REF:
+  //
+  // Gating on `open` stopped the walk while the modal is closed, but while it
+  // is OPEN the number is derived from `workspace.runtimes` — which the
+  // comment directly above names "one of the highest-churn references in the
+  // app". Every streaming tick from any pane re-walked up to 2000 entries for
+  // every matching row, to produce a single threshold comparison that defaults
+  // one checkbox.
+  //
+  // Depending on `matchingRows` instead is NOT sufficient and a first attempt
+  // that did only that changed nothing: `agentRows` lists `workspace.runtimes`
+  // in its own deps, so `matchingRows` is a fresh array on every tick too. The
+  // dependency has to be the thing that actually decides the answer, which is
+  // WHICH sessions match — not the identity of the array listing them, and not
+  // the identity of the runtime map. Joining the ids is O(rows) per render
+  // against O(rows x entries) for the walk.
+  //
+  // The estimate can therefore lag a pane's growth within one open session.
+  // That is acceptable and deliberate: it only picks the default state of a
+  // checkbox the user can see and toggle, and it is re-derived every time the
+  // modal opens.
+  const runtimesRef = useRef(workspace.runtimes)
+  runtimesRef.current = workspace.runtimes
+  const matchingRowsRef = useRef(matchingRows)
+  matchingRowsRef.current = matchingRows
+  const matchingSessionKey = matchingRows.map(row => row.sessionId).join('\u0000')
   const largestSourceEstimate = useMemo(() => {
+    if (!open) return 0
+    const runtimes = runtimesRef.current
     let largest = 0
-    for (const row of matchingRows) {
-      const runtime = runtimesForEstimate[row.sessionId]
+    for (const row of matchingRowsRef.current) {
+      const runtime = runtimes[row.sessionId]
       if (!runtime) continue
       const estimate = estimateLiveEntriesBytes(runtime.entries)
       if (estimate > largest) largest = estimate
     }
     return largest
-  }, [matchingRows, runtimesForEstimate])
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [matchingSessionKey, open])
 
   // Claude is the only target with a compaction the renderer can drive
   // (compactAfterSwitch reports every other kind as a no-op), so the checkbox
@@ -383,6 +439,7 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
   // in the confirmation.
   const toggleProject = useCallback((cwd: string) => {
     setSourceConfirmArmed(false)
+    setConfirmedSessionIds(null)
     setSelectedProjects(prev => {
       const next = new Set(prev)
       if (next.has(cwd)) next.delete(cwd)
@@ -393,16 +450,19 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
 
   const selectAllProjects = useCallback(() => {
     setSourceConfirmArmed(false)
+    setConfirmedSessionIds(null)
     setSelectedProjects(new Set(projects.map(project => project.cwd)))
   }, [projects])
 
   const clearProjects = useCallback(() => {
     setSourceConfirmArmed(false)
+    setConfirmedSessionIds(null)
     setSelectedProjects(new Set())
   }, [])
 
   const changeScopeMode = useCallback((mode: ScopeMode) => {
     setSourceConfirmArmed(false)
+    setConfirmedSessionIds(null)
     setScopeMode(mode)
   }, [])
 
@@ -411,11 +471,16 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
     // scope it hides rows the user is choosing from; disarm either way rather
     // than depend on that distinction staying true.
     setSourceConfirmArmed(false)
+    setConfirmedSessionIds(null)
     setProjectFilter(value)
   }, [])
 
   const runSwitch = useCallback(async () => {
-    if (matchingRows.length === 0 || busy) return
+    // `locked`, not `busy`: runModelSwitch sets only `switchingModel`, so
+    // guarding on `busy` alone let a Switch start on top of an in-flight
+    // /model fan-out over the same panes — the very race the sequential loop
+    // exists to prevent, and the one the close guards below already cover.
+    if (matchingRows.length === 0 || lockedRef.current) return
     // One confirmation for the whole batch, in the modal, replacing main's
     // per-agent native dialog (spec §Renderer). It is required only on the
     // opt-in source path: that is the branch that rewrites live history and
@@ -423,12 +488,20 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
     // nothing and is confirmed by the button press itself.
     if (compactOnSource && !sourceConfirmArmed) {
       setSourceConfirmArmed(true)
+      setConfirmedSessionIds(matchingRows.map(row => row.sessionId))
       return
     }
+    // The confirmed set wins over the live one whenever a confirmation was
+    // required. Panes that closed in between are skipped by the action itself,
+    // which re-reads meta per iteration, so a stale id is harmless — an
+    // UNCONFIRMED id is not.
+    const sessionIds = compactOnSource && confirmedSessionIds
+      ? confirmedSessionIds
+      : matchingRows.map(row => row.sessionId)
     setBusy(true)
     try {
       await workspace.switchAgentsToProvider(
-        matchingRows.map(row => row.sessionId),
+        sessionIds,
         target,
         {
           allowSourceTurns: compactOnSource,
@@ -446,10 +519,10 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
     } finally {
       setBusy(false)
     }
-  }, [busy, compactOnArrival, compactOnSource, matchingRows, onClose, sourceConfirmArmed, target, workspace])
+  }, [busy, compactOnArrival, compactOnSource, confirmedSessionIds, matchingRows, onClose, sourceConfirmArmed, target, workspace])
 
   const runModelSwitch = useCallback(async () => {
-    if (matchingRows.length === 0 || switchingModel || busy) return
+    if (matchingRows.length === 0 || lockedRef.current) return
     setSwitchingModel(true)
     let delivered = 0
     let failed = 0
@@ -473,6 +546,25 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
           if (firstFailure === null) firstFailure = result.message
         }
       }
+    } catch (error) {
+      // WHY this catch exists: the loop had try/finally and no catch, so a
+      // REJECTED deliverPrompt (a dead IPC channel, a preload shape mismatch)
+      // aborted the batch mid-way while the `finally` still ran. The count was
+      // not wrong about what it claimed — `delivered` only ever incremented
+      // after `result.ok` — but the toast said "Sent /model … to 3 agents"
+      // with no failure note at all, so every agent the loop never reached
+      // simply vanished from the report. Silence about an agent reads as
+      // "nothing to say", not as "never attempted".
+      // Clamped so the report can never claim more agents than the batch had:
+      // the loop aborted, so everything not already counted is unattempted,
+      // and at minimum the one that rejected must show up.
+      const remaining = matchingRows.length - delivered - failed
+      failed += remaining > 0 ? remaining : 1
+      if (firstFailure === null) {
+        firstFailure = error instanceof Error && error.message.length > 0
+          ? error.message
+          : 'Prompt delivery failed'
+      }
     } finally {
       setSwitchingModel(false)
       const failureNote = failed > 0
@@ -483,7 +575,9 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
   }, [busy, matchingRows, showToast, switchingModel])
 
   const runReturn = useCallback(async () => {
-    if (busy) return
+    // Same reason as runSwitch: a Return must not start under an in-flight
+    // /model fan-out.
+    if (lockedRef.current) return
     setBusy(true)
     try {
       // Intentionally NOT closing the modal: the banner clears itself when
@@ -501,10 +595,25 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
   // mid-loop, a second bulk operation could start concurrently against the same
   // replaceSession mutation paths. Refusing to close while busy keeps `busy` the
   // authoritative single-flight guard without lifting it into workspace state.
+  // WHY `switchingModel` counts as locked too:
+  //
+  // `runModelSwitch` sets only `switchingModel`, and every close guard keyed on
+  // `busy` alone. Escape during the sequential /model loop was therefore
+  // allowed, the reset effect below cleared `switchingModel` on reopen, and a
+  // second click started a second loop that interleaved PTY writes on panes
+  // that had already received the prompt. That is precisely the race the
+  // sequential loop exists to prevent. `open` is store-owned, so
+  // `closeBulkProviderSwitch` from anywhere else bypasses this guard for
+  // `busy` as well — see the reset effect, which is the second half of the fix.
+  const locked = busy || switchingModel
+  // Read by the run guards, which must see the live value without taking
+  // `locked` as a dependency and re-creating every callback on each toggle.
+  const lockedRef = useRef(locked)
+  lockedRef.current = locked
   const requestClose = useCallback(() => {
-    if (busy) return
+    if (locked) return
     onClose()
-  }, [busy, onClose])
+  }, [locked, onClose])
 
   return (
     <Dialog
@@ -516,14 +625,14 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
       <DialogContent
         className="flex max-h-[86vh] w-[min(860px,94vw)] flex-col overflow-hidden"
         onEscapeKeyDown={event => {
-          if (busy) event.preventDefault()
+          if (locked) event.preventDefault()
         }}
         onPointerDownOutside={event => {
           // WHY an in-flight batch cannot be dismissed: the old overlay kept
           // this single-flight operation visible until it settled. Preventing
           // Radix's outside close preserves that contract while still letting
           // the primitive own all normal dismissal behavior.
-          if (busy) event.preventDefault()
+          if (locked) event.preventDefault()
         }}
       >
         <div className="flex-shrink-0 border-b border-border px-4 py-3">
@@ -538,7 +647,7 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
             <button
               type="button"
               onClick={requestClose}
-              disabled={busy}
+              disabled={locked}
               className="rounded-control px-2 py-1 text-[10px] border border-border text-ink-dim hover:text-ink hover:border-border-hi disabled:opacity-50"
             >
               Esc
@@ -555,7 +664,7 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
               <button
                 type="button"
                 onClick={() => void runReturn()}
-                disabled={busy}
+                disabled={locked}
                 className="rounded-control flex-shrink-0 px-2.5 py-1 text-[11px] border border-accent/60 bg-accent/10 text-accent hover:bg-accent/20 disabled:opacity-50"
               >
                 {busy ? 'Working…' : `Return ${batch.agents.length}`}
@@ -593,6 +702,7 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
                     // source. Changing direction changes whose quota would be
                     // spent, so the armed second click must not carry over.
                     setSourceConfirmArmed(false)
+                    setConfirmedSessionIds(null)
                   }}
                   className="rounded-control px-2 py-1.5 bg-canvas border border-border text-[12px] text-ink outline-none focus:border-accent"
                 >
@@ -666,6 +776,7 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
                 onChange={e => {
                   setCompactOnSourceChoice(e.target.checked)
                   setSourceConfirmArmed(false)
+                  setConfirmedSessionIds(null)
                 }}
                 className="mt-0.5 accent-current disabled:opacity-50"
               />
@@ -701,7 +812,7 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
                 <button
                   type="button"
                   onClick={() => void runModelSwitch()}
-                  disabled={busy || switchingModel || matchingRows.length === 0}
+                  disabled={locked || matchingRows.length === 0}
                   className="rounded-control flex-shrink-0 px-2.5 py-1 text-[11px] border border-accent/60 bg-accent/10 text-accent hover:bg-accent/20 disabled:opacity-50"
                 >
                   {switchingModel
@@ -853,7 +964,7 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
             <button
               type="button"
               onClick={requestClose}
-              disabled={busy}
+              disabled={locked}
               className="rounded-control px-3 py-1.5 text-[11px] border border-border text-ink-dim hover:text-ink hover:border-border-hi disabled:opacity-50"
             >
               Cancel
@@ -861,7 +972,10 @@ export function BulkProviderSwitchModal({ open, workspace, onClose }: Props) {
             <button
               type="button"
               onClick={() => void runSwitch()}
-              disabled={busy || matchingRows.length === 0}
+              // `locked`, matching the handler: with `busy` alone the button
+              // stayed enabled during a /model fan-out while runSwitch refused
+              // the click, so it looked available and did nothing.
+              disabled={locked || matchingRows.length === 0}
               className={`rounded-control
                 px-3 py-1.5 text-[11px] border
                 ${matchingRows.length > 0
diff --git a/src/renderer/src/styles.css b/src/renderer/src/styles.css
index d9989b35..19bf3609 100644
--- a/src/renderer/src/styles.css
+++ b/src/renderer/src/styles.css
@@ -1063,3 +1063,40 @@ body,
 *::-webkit-scrollbar-thumb:hover {
   background: var(--theme-muted);
 }
+
+/* Truncate a path from its START, so the ellipsis eats the least useful end.
+ *
+ * WHY this exists rather than Tailwind's `truncate`: `text-overflow: ellipsis`
+ * always clips the END of the line. For a project path that is exactly
+ * backwards — every pane in a workspace shares the same leading segments, so a
+ * narrow pane showed ".../Desktop/Developme…" for all of them and the one part
+ * that identifies the agent was the first thing cut. With several panes open
+ * the header stopped distinguishing them at all.
+ *
+ * WHY direction rather than measuring and slicing in JS: the ellipsis has to
+ * land wherever the box happens to end, which only the layout engine knows.
+ * Reversing the paragraph direction moves the overflow edge to the left and
+ * lets `text-overflow` do its normal job there.
+ *
+ * WHY the call sites wrap the text in an inner `dir="ltr"` span, and why this
+ * rule must NOT carry `unicode-bidi: plaintext`:
+ *
+ * Both alternatives were measured in Chrome at 180px. `direction: rtl` alone
+ * clips the right end and reorders the leading "…/" onto the far side —
+ * ".../parent-directory/my-project" renders as "…tory/my-project/…". Adding
+ * `unicode-bidi: plaintext` derives the run's direction from its first strong
+ * character, which is LTR for an ASCII path, so the clipping edge goes back to
+ * the end and the whole rule does nothing. Only the two-element form works:
+ * the OUTER direction selects which edge clips, the INNER one preserves the
+ * path's text order. Short paths and the leading ellipsis survive intact, and
+ * at a comfortable width nothing is clipped at all.
+ */
+.truncate-start {
+  display: block;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  direction: rtl;
+  text-align: left;
+}
diff --git a/src/renderer/src/workspace/agentNames/pendingIdentityCarry.test.ts b/src/renderer/src/workspace/agentNames/pendingIdentityCarry.test.ts
new file mode 100644
index 00000000..0b1e0fdd
--- /dev/null
+++ b/src/renderer/src/workspace/agentNames/pendingIdentityCarry.test.ts
@@ -0,0 +1,81 @@
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { claimMissingIdentities } from './reconcile'
+import {
+  identityCarryIsPending,
+  releaseIdentityCarry,
+  reserveIdentityCarry,
+  resetIdentityCarryForTests,
+} from './pendingIdentityCarry'
+import type { WorkspaceState } from '@renderer/workspace/types'
+
+// The leak this closes, restated because it is not obvious from the code:
+//
+// `spawn` deliberately does not mint an identity, so a replacement successor
+// is committed to state with none. `replaceSession` then awaits
+// `killSessionBackendIfOwned` — a full IPC round trip — and React flushes in
+// that gap. The reconciler sees an identity-less agent, claims one, and main
+// allocates a name and commits it to disk, advancing nextIndex. The
+// replacement commit then overwrites the identity, orphaning that name
+// forever, because the registry never recycles. The 100-name vocabulary
+// therefore drained at the rate of RELOADS, not new agents.
+
+afterEach(resetIdentityCarryForTests)
+
+function workspace(sessions: Record<string, unknown>): WorkspaceState {
+  return { sessions, buried: [] } as unknown as WorkspaceState
+}
+
+describe('identity carry reservation', () => {
+  it('claims an identity for an ordinary unnamed agent', () => {
+    const next = claimMissingIdentities(workspace({
+      'agent-one': { cwd: '/recorded', kind: 'claude' },
+    }))
+    expect(next.sessions['agent-one'].agentNameId).toBe('agent-one')
+  })
+
+  it('does not claim one for a successor whose identity is already in flight', () => {
+    reserveIdentityCarry('successor')
+    const state = workspace({ successor: { cwd: '/recorded', kind: 'claude' } })
+
+    const next = claimMissingIdentities(state)
+
+    expect(next.sessions.successor.agentNameId).toBeUndefined()
+    // Identity-preserving, so no downstream memo in the workspace tree is
+    // invalidated by a pass that decided to do nothing.
+    expect(next).toBe(state)
+  })
+
+  it('claims again as soon as the reservation is released', () => {
+    // The release must genuinely re-open the claim: a stranded reservation
+    // would leave that pane permanently unnamed, which is the mirror-image bug
+    // and just as bad as the leak.
+    reserveIdentityCarry('successor')
+    releaseIdentityCarry('successor')
+
+    const next = claimMissingIdentities(workspace({
+      successor: { cwd: '/recorded', kind: 'claude' },
+    }))
+
+    expect(next.sessions.successor.agentNameId).toBe('successor')
+  })
+
+  it('reserves only the named session, never its neighbours', () => {
+    reserveIdentityCarry('successor')
+
+    const next = claimMissingIdentities(workspace({
+      successor: { cwd: '/recorded', kind: 'claude' },
+      bystander: { cwd: '/recorded', kind: 'codex' },
+    }))
+
+    expect(next.sessions.successor.agentNameId).toBeUndefined()
+    expect(next.sessions.bystander.agentNameId).toBe('bystander')
+  })
+
+  it('treats releasing an unreserved id as a no-op', () => {
+    // replaceSession releases in a `finally` that also covers paths where no
+    // reservation was ever taken (an ordinary spawn carries no identity).
+    expect(() => releaseIdentityCarry('never-reserved')).not.toThrow()
+    expect(identityCarryIsPending('never-reserved')).toBe(false)
+  })
+})
diff --git a/src/renderer/src/workspace/agentNames/pendingIdentityCarry.ts b/src/renderer/src/workspace/agentNames/pendingIdentityCarry.ts
new file mode 100644
index 00000000..92f30afe
--- /dev/null
+++ b/src/renderer/src/workspace/agentNames/pendingIdentityCarry.ts
@@ -0,0 +1,65 @@
+import type { SessionId } from '@renderer/workspace/types'
+
+/**
+ * Successor panes that are mid-`replaceSession` and are about to inherit their
+ * predecessor's `agentNameId`.
+ *
+ * WHY this exists — the name leak it closes:
+ *
+ * `spawn` deliberately does not mint an identity (see its comment: a seed
+ * there would land on the successor and win the replacement spread, renaming a
+ * pane that only changed backends). So a freshly spawned successor is
+ * committed to `state.sessions` with NO `agentNameId`, and `replaceSession`
+ * then awaits `killSessionBackendIfOwned` — a full IPC round trip, i.e. a
+ * macrotask boundary. React flushes in that gap. The reconciler, mounted in
+ * the same component, sees an identity-less agent, claims one, and main
+ * ALLOCATES A NAME AND COMMITS IT TO DISK, advancing `nextIndex`. Only
+ * afterwards does the replacement commit overwrite `agentNameId` with the
+ * carried one.
+ *
+ * The allocated name is now referenced by nothing, and the registry guarantees
+ * names are never recycled. So the 100-entry vocabulary drained at the rate of
+ * REPLACEMENTS — every reload, resume, rewind and provider switch — rather
+ * than at the rate of new agents. Roughly a hundred reloads and every new
+ * agent is "Apollo 2". Multi-pane Undo Close burned up to N-1 per restored tab
+ * on top of that, because it spawns in a sequential await loop.
+ *
+ * WHY a module-scoped set rather than a threaded ref: the writer
+ * (`replaceSession`, in useSessionActions) and the reader
+ * (`claimMissingIdentities`, called from useAgentNameReconciler) are siblings
+ * under one component with no existing channel between them, and widening
+ * SessionActions to carry a naming detail would put a workspace concern in an
+ * unrelated public shape. Each BrowserWindow is its own JS realm and session
+ * ids are window-scoped, so one module-level set is exactly one window's
+ * worth of state. `providerSwitchesInFlight` is the same pattern for the same
+ * reason.
+ *
+ * WHY it is not merely `pendingReplacementSuccessorsRef`: that set exists for
+ * a different question and is populated ONLY when main reports a Codex
+ * same-rollout handoff transaction. It says nothing about Claude, OpenCode,
+ * fresh Codex, or different-transcript swaps, which are most replacements.
+ */
+const pendingIdentityCarry = new Set<SessionId>()
+
+/**
+ * Mark a successor as "its identity is arriving in this same tick's commit".
+ * The caller MUST pair this with `releaseIdentityCarry` on every exit path,
+ * including failures — a stranded id would leave that pane permanently
+ * unnamed, which is the opposite failure and just as bad.
+ */
+export function reserveIdentityCarry(sessionId: SessionId): void {
+  pendingIdentityCarry.add(sessionId)
+}
+
+export function releaseIdentityCarry(sessionId: SessionId): void {
+  pendingIdentityCarry.delete(sessionId)
+}
+
+export function identityCarryIsPending(sessionId: SessionId): boolean {
+  return pendingIdentityCarry.has(sessionId)
+}
+
+/** Test seam. Never call from application code. */
+export function resetIdentityCarryForTests(): void {
+  pendingIdentityCarry.clear()
+}
diff --git a/src/renderer/src/workspace/agentNames/presentation.renderer.test.tsx b/src/renderer/src/workspace/agentNames/presentation.renderer.test.tsx
index fce6ad9c..ad546e87 100644
--- a/src/renderer/src/workspace/agentNames/presentation.renderer.test.tsx
+++ b/src/renderer/src/workspace/agentNames/presentation.renderer.test.tsx
@@ -109,6 +109,45 @@ describe('agent name presentation', () => {
     expect(container.querySelector('[data-agent-title-header="true"]')).toHaveTextContent('Investigate queue race')
   })
 
+  it('holds the row open for an agent whose name has not arrived yet', () => {
+    // WHY this matters far beyond a blank badge: a name arrives over IPC well
+    // after the pane mounts. When the row's EXISTENCE depended on the name,
+    // every named agent pane grew ~23px mid-life on every window load, shrank
+    // the terminal box, refit, and sent a second PTY resize as a SIGWINCH into
+    // a live, mid-output TUI. The TUI's redraw then erased a line count
+    // computed for the pre-resize frame and left garbled fragments in the
+    // scrollback permanently. Reserving the box removes the resize.
+    seed()
+    appState.workspaceAgentNames = {}
+    const { container } = render(<AgentTitleHeader sessionId={AGENT} />)
+
+    expect(container.querySelector('[data-agent-title-header="true"]')).not.toBeNull()
+    const placeholder = container.querySelector('[data-agent-name-placeholder="true"]')
+    expect(placeholder).not.toBeNull()
+    // It must not be readable or addressable as a name: an operator resolving
+    // agents by name must never match a pane that has none yet.
+    expect(placeholder).toHaveAttribute('aria-hidden', 'true')
+    expect(container.querySelector('[data-agent-name-badge="true"]')).toBeNull()
+    expect(container.querySelector('[data-agent-title-header="true"]')).toHaveTextContent('')
+  })
+
+  it('reserves nothing for a shell, which never receives a name', () => {
+    // The reservation is keyed on provider kind, so a plain terminal pane must
+    // not gain a row it will never fill.
+    seed()
+    appState.workspaceAgentNames = {}
+    const { container } = render(<AgentTitleHeader sessionId={SHELL} />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('reserves nothing while the setting is off, so unnamed users lose no space', () => {
+    seed()
+    appState.workspaceAgentNames = {}
+    appState.settings.agentNamesEnabled = false
+    const { container } = render(<AgentTitleHeader sessionId={AGENT} />)
+    expect(container.firstChild).toBeNull()
+  })
+
   it('chips the name on the agent row of the Dispatch index and leaves shells bare', () => {
     seed()
     const { container } = renderIndex()
diff --git a/src/renderer/src/workspace/agentNames/reconcile.ts b/src/renderer/src/workspace/agentNames/reconcile.ts
index 7b061a6c..57450096 100644
--- a/src/renderer/src/workspace/agentNames/reconcile.ts
+++ b/src/renderer/src/workspace/agentNames/reconcile.ts
@@ -1,3 +1,5 @@
+import { AGENT_NAME_IDENTITY_MAX_LENGTH } from '@shared/types/agentNames'
+import { identityCarryIsPending } from '@renderer/workspace/agentNames/pendingIdentityCarry'
 import { DEFAULT_PROVIDER, isAgentProviderKind } from '@shared/types/providerKind'
 
 import type { SessionMeta, WorkspaceState } from '@renderer/workspace/types'
@@ -26,9 +28,20 @@ function isNameable(meta: Pick<SessionMeta, 'kind'>): boolean {
  *    naming for every agent in the window. Buried records never pass through
  *    the claim above (it walks `state.sessions` only), so that guard cannot
  *    cover this one.
+ *
+ * WHY the LENGTH bound is imported rather than written here: this comment
+ * already named main's schema verbatim, but only the type half was actually
+ * mirrored. An identity longer than 200 characters passed this check, entered
+ * the request array, and made the whole batch fail validation — the exact
+ * batch-wide outage the paragraph above describes, reachable from one
+ * hand-edited workspace.json. Sharing the constant makes the two halves
+ * impossible to drift apart again.
  */
 function identityOf(meta: Pick<SessionMeta, 'agentNameId'>): string | null {
-  return typeof meta.agentNameId === 'string' && meta.agentNameId.length > 0 ? meta.agentNameId : null
+  const identity = meta.agentNameId
+  if (typeof identity !== 'string') return null
+  if (identity.length === 0 || identity.length > AGENT_NAME_IDENTITY_MAX_LENGTH) return null
+  return identity
 }
 
 /**
@@ -49,6 +62,12 @@ export function claimMissingIdentities(state: WorkspaceState): WorkspaceState {
   const sessions = { ...state.sessions }
   for (const [sessionId, meta] of Object.entries(state.sessions)) {
     if (!isNameable(meta) || identityOf(meta)) continue
+    // A successor mid-replacement is about to inherit its predecessor's
+    // identity in this same operation. Claiming one for it here allocates a
+    // name that the very next commit overwrites and that nothing will ever
+    // reference again — and names are never recycled. See
+    // pendingIdentityCarry for why the gap is observable at all.
+    if (identityCarryIsPending(sessionId)) continue
     sessions[sessionId] = { ...meta, agentNameId: sessionId }
     changed = true
   }
diff --git a/src/renderer/src/workspace/agentNames/reconciler.renderer.test.tsx b/src/renderer/src/workspace/agentNames/reconciler.renderer.test.tsx
index 12668339..b02630eb 100644
--- a/src/renderer/src/workspace/agentNames/reconciler.renderer.test.tsx
+++ b/src/renderer/src/workspace/agentNames/reconciler.renderer.test.tsx
@@ -297,4 +297,85 @@ describe('agent name reconciliation', () => {
       names: stored,
     })).toBe('Apollo')
   })
+
+  it('stops re-asking a broken registry after a few failures for the same set', async () => {
+    // `identities` is a memo over workspace state and returns a fresh array on
+    // every workspace change, and the request set is cleared on SETTLE. With an
+    // unreadable agent-names.json — a state the registry deliberately never
+    // caches — every focus change, title edit, pin, split and close therefore
+    // fired another failing IPC round trip, forever, with nothing visible to
+    // the user. The effect's own comment claimed that could not happen.
+    const resolveAgentNames = vi.fn(async () => { throw new Error('registry unreadable') })
+    const mounted = mount({ enabled: true, resolveAgentNames })
+    await waitFor(() => expect(resolveAgentNames).toHaveBeenCalled())
+    await act(async () => { await Promise.resolve() })
+
+    // Nudge the workspace repeatedly without changing WHICH identities exist.
+    for (let i = 0; i < 6; i += 1) {
+      await act(async () => {
+        mounted.control.current?.(prev => ({ ...prev, activeTabId: `tab-${i}` }))
+        await Promise.resolve()
+      })
+    }
+
+    // Three attempts, not one: a rejection can be a transient collision on the
+    // shared serialization tail, so giving up immediately would leave agents
+    // unnamed for a condition that fixes itself.
+    expect(resolveAgentNames.mock.calls.length).toBeLessThanOrEqual(3)
+  })
+
+  it('asks again once the identity set actually changes', async () => {
+    // The breaker must not become a permanent mute: a new agent is a new
+    // question, and the registry may have been repaired since.
+    const resolveAgentNames = vi.fn(async () => { throw new Error('registry unreadable') })
+    const mounted = mount({ enabled: true, resolveAgentNames })
+    await waitFor(() => expect(resolveAgentNames).toHaveBeenCalled())
+    await act(async () => { await Promise.resolve() })
+    for (let i = 0; i < 5; i += 1) {
+      await act(async () => {
+        mounted.control.current?.(prev => ({ ...prev, activeTabId: `tab-${i}` }))
+        await Promise.resolve()
+      })
+    }
+    const beforeNewAgent = resolveAgentNames.mock.calls.length
+
+    await act(async () => {
+      mounted.control.current?.(prev => ({
+        ...prev,
+        sessions: { ...prev.sessions, 'agent-two': { cwd: '/recorded', kind: 'claude' } },
+      }))
+      await Promise.resolve()
+    })
+
+    await waitFor(() =>
+      expect(resolveAgentNames.mock.calls.length).toBeGreaterThan(beforeNewAgent))
+  })
+
+  it('treats an over-long identity as absent, so one bad record cannot mute the window', async () => {
+    // main validates z.string().min(1).max(200) over the WHOLE array, so a
+    // single hand-edited identity longer than that made requestSchema.parse
+    // reject every identity in the batch — and the reconciler swallows that
+    // silently, so no agent in the window ever received a name. The renderer's
+    // own comment named main's schema verbatim but mirrored only its type half.
+    const resolveAgentNames = vi.fn(async (identities: string[]) =>
+      Object.fromEntries(identities.map(identity => [identity, 'Apollo'])))
+    const base = workspace()
+    const initial = {
+      ...base,
+      sessions: {
+        ...base.sessions,
+        'agent-long': { cwd: '/recorded', kind: 'claude', agentNameId: 'x'.repeat(201) },
+      },
+    } as unknown as WorkspaceState
+    mount({ enabled: true, resolveAgentNames, initial })
+
+    await waitFor(() => expect(resolveAgentNames).toHaveBeenCalled())
+    await act(async () => { await Promise.resolve() })
+
+    const asked = resolveAgentNames.mock.calls.flatMap(call => call[0])
+    expect(asked.some(identity => identity.length > 200)).toBe(false)
+    // And the agent heals rather than staying stuck: an unusable identity is
+    // re-claimed exactly like a malformed one.
+    expect(asked).toContain('agent-long')
+  })
 })
diff --git a/src/renderer/src/workspace/agentNames/selectors.ts b/src/renderer/src/workspace/agentNames/selectors.ts
index b0f2a817..7cccb1cf 100644
--- a/src/renderer/src/workspace/agentNames/selectors.ts
+++ b/src/renderer/src/workspace/agentNames/selectors.ts
@@ -69,3 +69,37 @@ export function agentNameForSession(state: AppStore, sessionId: SessionId): stri
     names: state.workspaceAgentNames ?? {},
   })
 }
+
+/**
+ * Will this pane eventually grow an agent-name row?
+ *
+ * WHY presentation needs to know this BEFORE the name exists, when
+ * `resolveAgentName` deliberately refuses to answer early:
+ *
+ * A name arrives over IPC (`useAgentNameReconciler` -> `resolveAgentNames`)
+ * tens to hundreds of milliseconds after the pane mounts, and only once
+ * `restoreStatus` leaves 'pending'. AgentTitleHeader keyed its existence on
+ * the name, so on every window load a named agent pane rendered no row, laid
+ * its terminal out tall, told the PTY `rows: N` — and then, when the reply
+ * landed, grew a ~23px row, shrank the terminal box, refit, and sent
+ * `rows: N-1` as a SIGWINCH into a live, mid-output TUI. Ink and the Claude
+ * Code TUI erase a line count computed for the pre-resize frame, so that
+ * second resize overwrites the wrong region and leaves permanently garbled
+ * fragments in the scrollback.
+ *
+ * Reserving the row from first paint removes the layout change entirely, so
+ * there is no second resize to race. It is deliberately keyed on
+ * `agentNamesEnabled` + provider kind rather than on the identity or the
+ * name, because those are the only two facts already known at mount: the
+ * identity itself is claimed by a later effect, so keying on it would
+ * reintroduce the same flip one step earlier.
+ *
+ * Same defensive optional reads as `agentNameForSession` above, for the same
+ * phone-bundle reason: a keyless store must degrade, never throw.
+ */
+export function agentNameRowIsReserved(state: AppStore, sessionId: SessionId): boolean {
+  if (state.settings?.agentNamesEnabled !== true) return false
+  const meta = state.workspaceState?.sessions?.[sessionId]
+  if (!meta) return false
+  return isAgentProviderKind(meta.kind ?? DEFAULT_PROVIDER)
+}
diff --git a/src/renderer/src/workspace/agentNames/useAgentName.ts b/src/renderer/src/workspace/agentNames/useAgentName.ts
index 0d61769f..8d17c8e5 100644
--- a/src/renderer/src/workspace/agentNames/useAgentName.ts
+++ b/src/renderer/src/workspace/agentNames/useAgentName.ts
@@ -1,5 +1,8 @@
 import { useAppStore } from '@renderer/app-state/hooks'
-import { agentNameForSession } from '@renderer/workspace/agentNames/selectors'
+import {
+  agentNameForSession,
+  agentNameRowIsReserved,
+} from '@renderer/workspace/agentNames/selectors'
 import type { SessionId } from '@renderer/workspace/types'
 
 /**
@@ -14,3 +17,15 @@ import type { SessionId } from '@renderer/workspace/types'
 export function useAgentName(sessionId: SessionId): string | null {
   return useAppStore(state => agentNameForSession(state, sessionId))
 }
+
+/**
+ * Companion subscription to `useAgentName`, returning whether this pane must
+ * hold space for a name row that has not arrived yet. See
+ * `agentNameRowIsReserved` for why the header cannot wait for the name.
+ *
+ * Also a primitive, so it re-renders on exactly one transition: the Agent
+ * names setting being toggled.
+ */
+export function useAgentNameRowReserved(sessionId: SessionId): boolean {
+  return useAppStore(state => agentNameRowIsReserved(state, sessionId))
+}
diff --git a/src/renderer/src/workspace/agentNames/useAgentNameReconciler.ts b/src/renderer/src/workspace/agentNames/useAgentNameReconciler.ts
index a0169ac8..c5424383 100644
--- a/src/renderer/src/workspace/agentNames/useAgentNameReconciler.ts
+++ b/src/renderer/src/workspace/agentNames/useAgentNameReconciler.ts
@@ -19,6 +19,18 @@ import type { WorkspaceState } from '@renderer/workspace/types'
  * agent-names.json, and enabling is what assigns names to the agents that
  * already exist.
  */
+/**
+ * How many consecutive allocation failures for the SAME identity set before
+ * this window stops asking.
+ *
+ * Three rather than one: a rejection can be a transient write collision
+ * between windows on the shared serialization tail, and giving up on the first
+ * one would leave agents unnamed for a condition that resolves itself. It
+ * resets on any successful reply, and a changed identity set is always asked
+ * again regardless.
+ */
+const MAX_CONSECUTIVE_ALLOCATION_FAILURES = 3
+
 export function useAgentNameReconciler(
   state: WorkspaceState,
   setState: WorkspaceSetState,
@@ -32,6 +44,26 @@ export function useAgentNameReconciler(
   // every identity on each state change until the reply lands, and a slow disk
   // would turn one membership change into a burst of allocations.
   const requestedRef = useRef(new Set<string>())
+  /**
+   * Consecutive rejected allocations, and the identity set that was in flight
+   * when the last one failed.
+   *
+   * WHY a circuit breaker is needed at all: the effect below clears
+   * `requestedRef` on SETTLE, and `identities` is a memo over `state` that
+   * returns a fresh array on every workspace change. So with an unreadable
+   * `agent-names.json` — a state the registry deliberately never caches, so it
+   * is retried forever — every focus change, title edit, pin, split and close
+   * fired another failing IPC round trip, indefinitely, with nothing visible
+   * to the user. The effect's own comment claimed "on failure no dep changed
+   * at all — so a broken registry cannot become a hot loop", which is true
+   * only while the workspace is completely idle.
+   *
+   * Retrying on a genuine membership change is still right: that is a new
+   * question, and the registry may have been repaired. The signature is what
+   * distinguishes it from the same question asked again.
+   */
+  const failuresRef = useRef(0)
+  const failedSignatureRef = useRef<string | null>(null)
 
   // WHY cancellation is unmount-scoped rather than a per-effect `cancelled`
   // flag: this effect's deps include `state` and `names`, so an ordinary
@@ -91,6 +123,11 @@ export function useAgentNameReconciler(
       !Object.prototype.hasOwnProperty.call(names, identity)
       && !requestedRef.current.has(identity))
     if (missing.length === 0) return
+    // Cheap because it only runs when there is something to ask for, which is
+    // exactly the case the memo's comment declined to pay for on every render.
+    const signature = [...missing].sort().join('\u0000')
+    if (failuresRef.current >= MAX_CONSECUTIVE_ALLOCATION_FAILURES
+      && failedSignatureRef.current === signature) return
     for (const identity of missing) requestedRef.current.add(identity)
 
     void window.api.resolveAgentNames(missing)
@@ -101,6 +138,9 @@ export function useAgentNameReconciler(
         // identity, and to nothing at all if the agent closed. Writing it is
         // what makes a replacement that completed mid-flight inherit its name.
         if (!mountedRef.current) return
+        // A reply of any shape means the registry is readable again.
+        failuresRef.current = 0
+        failedSignatureRef.current = null
         setNames(previous => {
           // WHY entries + spread instead of `merged[identity] = name`:
           //
@@ -137,7 +177,10 @@ export function useAgentNameReconciler(
       })
       // Never fabricate a name. A failed allocation is simply an agent with no
       // visible name until something changes.
-      .catch(() => {})
+      .catch(() => {
+        failuresRef.current += 1
+        failedSignatureRef.current = signature
+      })
       .finally(() => {
         // Clear on SETTLE, not only on rejection. Whatever this request
         // answered is now in `names` and will filter itself out; whatever it
@@ -145,7 +188,9 @@ export function useAgentNameReconciler(
         // change, rather than stranded in this set for the life of the window.
         // This does not re-run the effect on its own: on success `names`
         // changed and the recomputed `missing` is empty, and on failure no dep
-        // changed at all — so a broken registry cannot become a hot loop.
+        // changed at all. Note that the second half only holds while the
+        // workspace is idle — any state change produces a fresh `identities`
+        // array — which is what the failure circuit breaker above covers.
         for (const identity of missing) requestedRef.current.delete(identity)
       })
   }, [identities, names, setNames])
diff --git a/src/renderer/src/workspace/hook/actions/bulkProviderSwitch.renderer.test.ts b/src/renderer/src/workspace/hook/actions/bulkProviderSwitch.renderer.test.ts
new file mode 100644
index 00000000..82f788f5
--- /dev/null
+++ b/src/renderer/src/workspace/hook/actions/bulkProviderSwitch.renderer.test.ts
@@ -0,0 +1,245 @@
+import { renderHook } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import type { WorkspaceSetRuntimes, WorkspaceSetState } from '@renderer/workspace/hook/context'
+import type { WorkspaceRefs } from '@renderer/workspace/hook/refs'
+import type { SessionActions } from '@renderer/workspace/hook/actions/session'
+import type { ProviderSwitchBatch } from '@renderer/workspace/types'
+import { useBulkProviderSwitchActions } from '@renderer/workspace/hook/actions/bulkProviderSwitch'
+
+const { switchAgentProvider } = vi.hoisted(() => ({ switchAgentProvider: vi.fn() }))
+vi.mock('@renderer/workspace/hook/actions/providerSwitchCore', () => ({ switchAgentProvider }))
+
+// This module had NO test file, which is how a two-click data-loss bug shipped
+// in it. These cases pin the return path's batch bookkeeping specifically:
+// the modal is the ONLY return affordance in the app, so a batch dropped here
+// cannot be recovered by any other route.
+
+type Agent = ProviderSwitchBatch['agents'][number]
+
+function agent(sessionId: string): Agent {
+  return {
+    sessionId,
+    originalKind: 'claude',
+    switchedToKind: 'codex',
+  } as unknown as Agent
+}
+
+function harness(batch: ProviderSwitchBatch | null) {
+  const state = {
+    lastProviderSwitchBatch: batch,
+    sessions: Object.fromEntries(
+      (batch?.agents ?? []).map(a => [a.sessionId, { cwd: '/recorded', kind: 'codex' }]),
+    ),
+  }
+  const refs = { stateRef: { current: state } } as unknown as WorkspaceRefs
+  const setState = vi.fn((updater: unknown) => {
+    state.lastProviderSwitchBatch = (
+      typeof updater === 'function'
+        ? (updater as (p: typeof state) => typeof state)(state)
+        : (updater as typeof state)
+    ).lastProviderSwitchBatch
+  }) as unknown as WorkspaceSetState
+  const toasts: string[] = []
+  const { result } = renderHook(() => useBulkProviderSwitchActions(
+    refs,
+    setState,
+    vi.fn() as unknown as WorkspaceSetRuntimes,
+    (message: string) => { toasts.push(message) },
+    {} as SessionActions,
+  ))
+  return { result, state, toasts }
+}
+
+function batchOf(...ids: string[]): ProviderSwitchBatch {
+  return {
+    id: 'batch-1',
+    switchedAt: 0,
+    sourceKind: 'claude',
+    targetKind: 'codex',
+    agents: ids.map(agent),
+    compactOnArrival: false,
+  } as unknown as ProviderSwitchBatch
+}
+
+afterEach(() => { switchAgentProvider.mockReset() })
+
+describe('returnLastProviderSwitchBatch', () => {
+  it('keeps the batch when every agent refuses to return', async () => {
+    // The realistic case, not an edge case: arrival compaction is on by
+    // default for large conversations and holds `providerSwitch` set for
+    // minutes per pane, so every agent in a batch returned during that window
+    // reports 'skipped' with "still finishing a provider switch". The old code
+    // nulled the batch anyway, and the user lost the only way to get those
+    // agents home by pressing the button meant to bring them home.
+    switchAgentProvider.mockResolvedValue({ status: 'skipped' })
+    const { result, state, toasts } = harness(batchOf('a', 'b', 'c'))
+
+    await result.current.returnLastProviderSwitchBatch()
+
+    expect(state.lastProviderSwitchBatch).not.toBeNull()
+    expect(state.lastProviderSwitchBatch?.agents.map(a => a.sessionId)).toEqual(['a', 'b', 'c'])
+    expect(toasts[0]).toContain('Returned 0 agents')
+  })
+
+  it('keeps only the agents that did not make it home', async () => {
+    switchAgentProvider
+      .mockResolvedValueOnce({ status: 'switched' })
+      .mockResolvedValueOnce({ status: 'failed' })
+      .mockResolvedValueOnce({ status: 'skipped' })
+    const { result, state } = harness(batchOf('a', 'b', 'c'))
+
+    await result.current.returnLastProviderSwitchBatch()
+
+    // 'a' is home and must not be retried; 'b' and 'c' are still parked on the
+    // target provider and are still returnable.
+    expect(state.lastProviderSwitchBatch?.agents.map(a => a.sessionId)).toEqual(['b', 'c'])
+  })
+
+  it('clears the batch once every agent has returned', async () => {
+    switchAgentProvider.mockResolvedValue({ status: 'switched' })
+    const { result, state } = harness(batchOf('a', 'b'))
+
+    await result.current.returnLastProviderSwitchBatch()
+
+    expect(state.lastProviderSwitchBatch).toBeNull()
+  })
+
+  it('clears the batch when its agents are all gone from the workspace', async () => {
+    // Closed or manually-moved agents are skipped WITHOUT being retained:
+    // there is nothing left to return, so holding the record would leave a
+    // Return affordance that can never do anything.
+    const batch = batchOf('a')
+    const { result, state } = harness(batch)
+    state.sessions = {}
+
+    await result.current.returnLastProviderSwitchBatch()
+
+    expect(state.lastProviderSwitchBatch).toBeNull()
+    expect(switchAgentProvider).not.toHaveBeenCalled()
+  })
+
+  it('does not clobber a newer batch recorded while the return was running', async () => {
+    switchAgentProvider.mockResolvedValue({ status: 'switched' })
+    const { result, state } = harness(batchOf('a'))
+    // A forward switch during the await replaces the remembered batch. The
+    // return must not delete a record it never operated on.
+    switchAgentProvider.mockImplementation(async () => {
+      state.lastProviderSwitchBatch = batchOf('z')
+      state.lastProviderSwitchBatch.id = 'batch-2'
+      return { status: 'switched' }
+    })
+
+    await result.current.returnLastProviderSwitchBatch()
+
+    expect(state.lastProviderSwitchBatch?.id).toBe('batch-2')
+  })
+})
+
+describe('returnLastProviderSwitchBatch consent', () => {
+  it('does not compact on arrival when the forward batch did not consent', async () => {
+    // A Return click used to hard-code compaction on for any Claude
+    // destination. That spends Claude quota once per agent and disables every
+    // one of those composers for the arrival wait plus the compaction wait —
+    // minutes each, no cancel — while the forward flow puts the same thing
+    // behind an explicit checkbox and a quota disclosure.
+    switchAgentProvider.mockResolvedValue({ status: 'switched' })
+    const { result } = harness(batchOf('a'))
+
+    await result.current.returnLastProviderSwitchBatch()
+
+    expect(switchAgentProvider).toHaveBeenCalledWith(
+      expect.objectContaining({
+        contextPolicy: expect.objectContaining({ compactOnArrival: false }),
+      }),
+    )
+  })
+
+  it('compacts on arrival when the forward batch did consent', async () => {
+    switchAgentProvider.mockResolvedValue({ status: 'switched' })
+    const batch = batchOf('a')
+    batch.compactOnArrival = true
+    const { result } = harness(batch)
+
+    await result.current.returnLastProviderSwitchBatch()
+
+    expect(switchAgentProvider).toHaveBeenCalledWith(
+      expect.objectContaining({
+        contextPolicy: expect.objectContaining({ compactOnArrival: true }),
+      }),
+    )
+  })
+
+  it('never promises arrival compaction a non-Claude destination cannot do', async () => {
+    // compactAfterSwitch reports every non-Claude kind as a no-op, so honouring
+    // consent literally would advertise work that never happens.
+    switchAgentProvider.mockResolvedValue({ status: 'switched' })
+    const batch = batchOf('a')
+    batch.compactOnArrival = true
+    batch.agents[0].originalKind = 'codex'
+    const { result } = harness(batch)
+
+    await result.current.returnLastProviderSwitchBatch()
+
+    expect(switchAgentProvider).toHaveBeenCalledWith(
+      expect.objectContaining({
+        contextPolicy: expect.objectContaining({ compactOnArrival: false }),
+      }),
+    )
+  })
+})
+
+describe('bulk switch reporting', () => {
+  it('carries the reason into the summary instead of only a count', async () => {
+    // "Returned 0 agents to Claude (1 failed)" is unactionable. The core writes
+    // messages that name the remedy; bulk used to discard every one of them.
+    switchAgentProvider.mockResolvedValue({
+      status: 'failed',
+      message: 'Poisoned carrier — clear the rate-limit message first',
+    })
+    const { result, toasts } = harness(batchOf('a'))
+
+    await result.current.returnLastProviderSwitchBatch()
+
+    expect(toasts[0]).toContain('1 failed')
+    expect(toasts[0]).toContain('Poisoned carrier')
+  })
+
+  it('reports skipped agents separately from failed ones', async () => {
+    switchAgentProvider
+      .mockResolvedValueOnce({ status: 'skipped', reason: 'Still finishing a provider switch' })
+      .mockResolvedValueOnce({ status: 'failed', message: 'Replacement failed' })
+    const { result, toasts } = harness(batchOf('a', 'b'))
+
+    await result.current.returnLastProviderSwitchBatch()
+
+    expect(toasts[0]).toContain('1 skipped')
+    expect(toasts[0]).toContain('1 failed')
+  })
+
+  it('dedupes shared reasons and caps the list', async () => {
+    // Twenty agents usually fail for one reason, and PaneToast clamps to three
+    // lines — an uncapped list would push the counts out of view.
+    switchAgentProvider.mockResolvedValue({ status: 'failed', message: 'Same reason' })
+    const { result, toasts } = harness(batchOf('a', 'b', 'c'))
+
+    await result.current.returnLastProviderSwitchBatch()
+
+    expect(toasts[0].match(/Same reason/g)).toHaveLength(1)
+    expect(toasts[0]).not.toContain('more')
+  })
+
+  it('surfaces the shrink summary a successful but lossy return produced', async () => {
+    // The shrink ladder's summary exists specifically so no lossy step is
+    // silent. Counting it as "1 shrunk" and dropping the text defeats that.
+    switchAgentProvider.mockResolvedValue({
+      status: 'switched',
+      shrinkSummary: 'dropped 12 tool results',
+    })
+    const { result, toasts } = harness(batchOf('a'))
+
+    await result.current.returnLastProviderSwitchBatch()
+
+    expect(toasts[0]).toContain('dropped 12 tool results')
+  })
+})
diff --git a/src/renderer/src/workspace/hook/actions/bulkProviderSwitch.ts b/src/renderer/src/workspace/hook/actions/bulkProviderSwitch.ts
index 3329a7b1..b8697eb0 100644
--- a/src/renderer/src/workspace/hook/actions/bulkProviderSwitch.ts
+++ b/src/renderer/src/workspace/hook/actions/bulkProviderSwitch.ts
@@ -47,25 +47,63 @@ export type BulkSwitchPolicy = {
   sourceCompactionConfirmed: boolean
 }
 
-/** The return path has no modal, so it hard-codes the safe policy.
+/** The return path has no modal, so it carries the batch's recorded consent.
  *
  *  `allowSourceTurns: false` because the source here is the provider the user
  *  parked on, and a return usually happens because the ORIGINAL provider's
  *  window reset — nothing licenses spending the parking provider's quota, and
  *  the whole feature exists to avoid needing to.
  *
- *  `compactOnArrival` only for a Claude destination: Claude is the one target
- *  with a compaction the renderer can drive (see compactAfterSwitch, which
- *  reports every other kind as a no-op), and a returning transcript has grown
- *  by everything the agent did while parked. */
-function returnPolicy(targetKind: AgentProviderKind): BulkSwitchPolicy {
+ *  `compactOnArrival` was previously hard-coded to `targetKind === 'claude'`,
+ *  which meant one Return click spent Claude quota once per agent and locked
+ *  every one of those composers for the arrival wait plus the compaction wait
+ *  — minutes each, no cancel — with no checkbox and none of the quota
+ *  disclosure the forward modal shows. It now reuses the consent the user gave
+ *  for this exact batch. `&& targetKind === 'claude'` still applies because
+ *  Claude is the one destination with a compaction the renderer can drive
+ *  (compactAfterSwitch reports every other kind as a no-op), so consenting to
+ *  it on a Codex return would promise something that cannot happen. */
+function returnPolicy(
+  targetKind: AgentProviderKind,
+  batchConsentedToArrivalCompaction: boolean,
+): BulkSwitchPolicy {
   return {
     allowSourceTurns: false,
-    compactOnArrival: targetKind === 'claude',
+    compactOnArrival: batchConsentedToArrivalCompaction && targetKind === 'claude',
     sourceCompactionConfirmed: false,
   }
 }
 
+/**
+ * Build the one toast a bulk operation gets.
+ *
+ * WHY the reasons ride along instead of only the counts: "Switched 0 agents to
+ * Claude (12 failed)" tells the user nothing they can act on, and the core
+ * deliberately produces strings that do — the poisoned-carrier abort names its
+ * remedy, and the shrink ladder's summary exists so no lossy step is silent.
+ * Deduped because a batch usually fails for one shared reason, and capped
+ * because PaneToast clamps to three lines and an uncapped list would push the
+ * counts out of view.
+ */
+const MAX_SUMMARY_NOTES = 2
+
+function summarize(
+  base: string,
+  counts: { skipped: number; failed: number },
+  notes: ReadonlySet<string>,
+): string {
+  const tally: string[] = []
+  if (counts.skipped > 0) tally.push(`${counts.skipped} skipped`)
+  if (counts.failed > 0) tally.push(`${counts.failed} failed`)
+  let message = tally.length > 0 ? `${base} (${tally.join(', ')})` : base
+  const shown = [...notes].slice(0, MAX_SUMMARY_NOTES)
+  if (shown.length > 0) {
+    const remaining = notes.size - shown.length
+    message += ` · ${shown.join(' · ')}${remaining > 0 ? ` · +${remaining} more` : ''}`
+  }
+  return message
+}
+
 export function useBulkProviderSwitchActions(
   refs: WorkspaceRefs,
   setState: WorkspaceSetState,
@@ -92,6 +130,21 @@ export function useBulkProviderSwitchActions(
       // enough that predictable mutation beats raw speed.
       const switched: ProviderSwitchBatchAgent[] = []
       let failed = 0
+      // 'skipped' used to be silently dropped here. Two of the core's most
+      // common outcomes — mid-turn, and "still finishing a provider switch" —
+      // are skips, not failures, and a batch where every agent was busy would
+      // otherwise print "Switched 0 agents" with no hint that anything was
+      // even attempted.
+      let skipped = 0
+      // WHY the strings are kept rather than only counted: the core writes
+      // messages that name the exact remedy (the poisoned-carrier abort) and
+      // the exact loss (the shrink ladder's summary, added specifically so
+      // "no lossy step is silent"). Bulk discarded both and printed
+      // "Switched 0 agents to Claude (12 failed)" / "12 raw", which is
+      // unactionable — a point the sibling model-switch function in the modal
+      // already argues in its own comment. Deduped and capped, because twenty
+      // agents usually fail for the same one reason.
+      const notes = new Set<string>()
       // Per-strategy tally, not a single "compacted" flag: a batch where nine
       // agents crossed losslessly and two had to be shrunk is a materially
       // different outcome from one where all eleven were shrunk, and the user
@@ -129,8 +182,18 @@ export function useBulkProviderSwitchActions(
         // succeeded but lost its meta mid-loop is not in `switched`, so counting
         // its strategy would produce "Switched 2 agents to Claude: 3 native" —
         // a summary that contradicts itself.
-        if (result.status === 'switched' && meta && originalKind) {
+        // Branch on status FIRST so each arm narrows cleanly. The old shape
+        // folded `&& meta && originalKind` into the success test, which pushed
+        // a switched-but-meta-less result into the skipped arm.
+        if (result.status === 'failed') {
+          failed += 1
+          notes.add(result.message)
+        } else if (result.status === 'skipped') {
+          skipped += 1
+          notes.add(result.reason)
+        } else if (meta && originalKind) {
           counts[result.strategy] += 1
+          if (result.shrinkSummary) notes.add(result.shrinkSummary)
           switched.push({
             sessionId: result.newSessionId,
             cwd: meta.cwd,
@@ -138,10 +201,14 @@ export function useBulkProviderSwitchActions(
             switchedToKind: targetKind,
             title: meta.title,
           })
-        } else if (result.status === 'failed') {
-          failed += 1
+        } else {
+          // Switched, but its meta vanished mid-loop so it cannot be recorded
+          // as a batch member. Counting its strategy would produce a summary
+          // that contradicts itself ("Switched 2 agents: 3 native"), and
+          // silently dropping it would under-report the work done.
+          skipped += 1
+          notes.add('An agent switched but was closed before it could be recorded')
         }
-        // 'skipped' (e.g. already on target) is silently not part of the batch.
       }
 
       // Replace the remembered batch outright — one level of memory only. If
@@ -157,6 +224,9 @@ export function useBulkProviderSwitchActions(
             sourceKind: switched[0].originalKind,
             targetKind,
             agents: switched,
+            // Recorded so Return can reuse this consent instead of deciding
+            // for the user. See returnPolicy.
+            compactOnArrival: policy.compactOnArrival,
           },
         }))
       }
@@ -167,7 +237,7 @@ export function useBulkProviderSwitchActions(
         counts.shrunk > 0 ? `${counts.shrunk} shrunk` : null,
       ].filter(Boolean).join(', ')
       const base = `Switched ${pluralAgents(switched.length)} to ${providerLabel(targetKind)}${tally ? `: ${tally}` : ''}`
-      showToast(failed > 0 ? `${base} (${failed} failed)` : base)
+      showToast(summarize(base, { skipped, failed }, notes))
     },
     [refs, sessionActions, setRuntimes, setState, showToast],
   )
@@ -182,6 +252,10 @@ export function useBulkProviderSwitchActions(
     let returned = 0
     let skipped = 0
     let failed = 0
+    const notes = new Set<string>()
+    // Agents that did NOT make it home. See the batch update below for why
+    // these have to survive: this modal is the only return affordance there is.
+    const unreturned: typeof batch.agents = []
 
     for (const agent of batch.agents) {
       const meta = refs.stateRef.current.sessions[agent.sessionId]
@@ -198,7 +272,7 @@ export function useBulkProviderSwitchActions(
         continue
       }
 
-      const policy = returnPolicy(agent.originalKind)
+      const policy = returnPolicy(agent.originalKind, batch.compactOnArrival)
       const result = await switchAgentProvider({
         sessionId: agent.sessionId,
         targetKind: agent.originalKind,
@@ -213,21 +287,53 @@ export function useBulkProviderSwitchActions(
         onProgress: event => showToast(event.message, 305_000),
         onArrivalFailure: message => showToast(message),
       })
-      if (result.status === 'switched') returned += 1
-      else if (result.status === 'failed') failed += 1
-      else skipped += 1
+      if (result.status === 'switched') {
+        returned += 1
+        if (result.shrinkSummary) notes.add(result.shrinkSummary)
+      } else if (result.status === 'failed') {
+        failed += 1
+        notes.add(result.message)
+        unreturned.push(agent)
+      } else {
+        notes.add(result.reason)
+        // 'skipped' here means the pane refused the switch right now — most
+        // often "still finishing a provider switch". It is still sitting on
+        // the target provider, so it is still returnable later.
+        skipped += 1
+        unreturned.push(agent)
+      }
     }
 
-    // Returning consumes the batch — there is no "return again". A future
-    // forward switch will record a fresh one.
-    setState(prev => ({ ...prev, lastProviderSwitchBatch: null }))
+    // WHY the batch is trimmed rather than dropped:
+    //
+    // "Returning consumes the batch" is right only for agents that actually
+    // returned. Dropping it wholesale meant a return in which NOTHING came
+    // back still destroyed the record, and this modal is the only return
+    // affordance in the app — there is no other way to get those agents home.
+    //
+    // That is not a rare case. Arrival compaction is on by default whenever
+    // the largest conversation exceeds 150k chars (the population this
+    // feature exists for), and it holds `providerSwitch` set for the arrival
+    // readiness wait plus the compaction wait — minutes per pane. Every agent
+    // in a batch returned during that window is refused with "This pane is
+    // still finishing a provider switch", so returned === 0, and the user
+    // lost the batch by clicking the button that was supposed to restore it.
+    // Partial returns lost the remainder the same way: 1 of 20 home, 19
+    // records discarded.
+    //
+    // Keeping the unreturned agents means Return stays available and is
+    // simply retried. The batch is cleared only once it is empty.
+    setState(prev => {
+      if (prev.lastProviderSwitchBatch?.id !== batch.id) return prev
+      if (unreturned.length === 0) return { ...prev, lastProviderSwitchBatch: null }
+      return {
+        ...prev,
+        lastProviderSwitchBatch: { ...prev.lastProviderSwitchBatch, agents: unreturned },
+      }
+    })
 
-    let message = `Returned ${pluralAgents(returned)} to ${providerLabel(batch.sourceKind)}`
-    const notes: string[] = []
-    if (skipped > 0) notes.push(`${skipped} skipped`)
-    if (failed > 0) notes.push(`${failed} failed`)
-    if (notes.length > 0) message += ` (${notes.join(', ')})`
-    showToast(message)
+    const base = `Returned ${pluralAgents(returned)} to ${providerLabel(batch.sourceKind)}`
+    showToast(summarize(base, { skipped, failed }, notes))
   }, [refs, sessionActions, setRuntimes, setState, showToast])
 
   return { switchAgentsToProvider, returnLastProviderSwitchBatch }
diff --git a/src/renderer/src/workspace/hook/actions/providerSwitchCore.renderer.test.ts b/src/renderer/src/workspace/hook/actions/providerSwitchCore.renderer.test.ts
index 20cbfe8e..8cc16c4c 100644
--- a/src/renderer/src/workspace/hook/actions/providerSwitchCore.renderer.test.ts
+++ b/src/renderer/src/workspace/hook/actions/providerSwitchCore.renderer.test.ts
@@ -610,8 +610,15 @@ describe('switchAgentProvider', () => {
         replaceSession,
       } as unknown as SessionActions,
     })).resolves.toEqual({
-      status: 'failed',
-      message: 'This pane is still finishing a provider switch — wait for it to complete',
+      // 'skipped', not 'failed'. Nothing is wrong with this pane — it is busy
+      // with an operation that ends on its own, and trying again shortly is
+      // the whole remedy. Reporting it as a failure made a bulk return during
+      // arrival compaction, which is the DEFAULT for large conversations and
+      // holds this flag for minutes per pane, announce "Returned 0 agents (20
+      // failed)" for a batch where every agent was merely busy. The string is
+      // unchanged and still reaches the same pane toast.
+      status: 'skipped',
+      reason: 'This pane is still finishing a provider switch — wait for it to complete',
     })
 
     expect(switchProvider).not.toHaveBeenCalled()
diff --git a/src/renderer/src/workspace/hook/actions/providerSwitchCore.ts b/src/renderer/src/workspace/hook/actions/providerSwitchCore.ts
index 42e3cd92..43ffd173 100644
--- a/src/renderer/src/workspace/hook/actions/providerSwitchCore.ts
+++ b/src/renderer/src/workspace/hook/actions/providerSwitchCore.ts
@@ -248,9 +248,16 @@ export async function switchAgentProvider(params: {
   // pane busy too, and "wait for the current turn to finish" would send the
   // user looking for a turn they never started.
   if (sourceRuntime?.providerSwitch) {
+    // 'skipped', not 'failed'. Nothing went wrong: this pane is busy with an
+    // operation that ends on its own, and the correct user response is to try
+    // again shortly. Reporting it as a failure made a bulk return during
+    // arrival compaction — which is the DEFAULT for large conversations and
+    // holds this flag for minutes per pane — announce "Returned 0 agents (20
+    // failed)" for a batch where nothing was wrong with any of them. Both
+    // shapes carry their string to the same place on the single-pane path.
     return {
-      status: 'failed',
-      message: 'This pane is still finishing a provider switch — wait for it to complete',
+      status: 'skipped',
+      reason: 'This pane is still finishing a provider switch — wait for it to complete',
     }
   }
   // The usage-limit exception (see isLimitIdle): a pane whose provider is
@@ -258,28 +265,39 @@ export async function switchAgentProvider(params: {
   // lock out precisely the agents this feature exists to move. Replacement
   // kills the process, which is what ends the provider's wait banner anyway.
   if ((sourceRuntime?.processActive || sourceRuntime?.semantic.currentTurn) && !(sourceRuntime && isLimitIdle(sourceRuntime))) {
-    return { status: 'failed', message: 'Wait for the current turn to finish before switching provider' }
+    // Also 'skipped': BulkProviderSwitchModal's own footer promises "N of M
+    // are mid-turn and will be skipped until idle", and reporting them as
+    // failures made the summary contradict the warning the user just read.
+    return { status: 'skipped', reason: 'Wait for the current turn to finish before switching provider' }
   }
   if (providerSwitchesInFlight.has(sessionId)) {
     return { status: 'failed', message: 'Provider switch already in progress' }
   }
-  providerSwitchesInFlight.add(sessionId)
-  setRuntimes(prev => {
-    const runtime = prev[sessionId]
-    if (!runtime) return prev
-    return {
-      ...prev,
-      [sessionId]: {
-        ...runtime,
-        providerSwitch: {
-          phase: 'preparing',
-          message: `Preparing switch to ${targetKind}…`,
+  // WHY the claim and the first runtime write are INSIDE the try: the release
+  // lives in this function's `finally`, and both statements used to sit above
+  // it. A throw from that setRuntimes — a subscriber, a selector, anything in
+  // the store's update path — leaked the id permanently in a module-scoped
+  // Set, and that pane then answered "Provider switch already in progress"
+  // for the rest of the window's life with no way back short of a reload.
+  // Deleting an id that was never added is a no-op, so widening the try costs
+  // nothing.
+  try {
+    providerSwitchesInFlight.add(sessionId)
+    setRuntimes(prev => {
+      const runtime = prev[sessionId]
+      if (!runtime) return prev
+      return {
+        ...prev,
+        [sessionId]: {
+          ...runtime,
+          providerSwitch: {
+            phase: 'preparing',
+            message: `Preparing switch to ${targetKind}…`,
+          },
         },
-      },
-    }
-  })
+      }
+    })
 
-  try {
     const sourceProviderSessionId = resumableProviderSessionId(meta)
     if (!sourceProviderSessionId) {
       // A freshly-spawned provider pane has no durable provider transcript yet.
@@ -307,7 +325,29 @@ export async function switchAgentProvider(params: {
     // recovery is a real mid-transaction ownership change, not ordinary pane
     // hibernation. `ensureSessionLive` is idempotent for an already-live owner
     // and main's recovery claim serializes concurrent wake attempts.
-    const wakeResult = await sessionActions.ensureSessionLive(sessionId, 'provider-switch.wake-source')
+    // WHY the wake stays but its READINESS WAIT does not, when the caller has
+    // explicitly ruled out source turns:
+    //
+    // The wake itself is load-bearing and must not be removed — it is what
+    // resolves this pane's built-in MCP domains under the SOURCE provider (see
+    // the provenance comment below), and what makes a later kind/cwd mismatch
+    // mean a real ownership change rather than ordinary hibernation.
+    //
+    // The 30s input-readiness wait is a different thing, and with
+    // `allowSourceTurns: false` — the transaction default, and the entire
+    // point of the quota-independent path — main plans the conversion from
+    // files on disk and never asks the source to do anything. Waiting for a
+    // prompt we will never send costs up to 30s per pane, serialised across a
+    // bulk switch, before `replaceSession` kills the process anyway.
+    //
+    // Gated on an EXPLICIT false rather than on `!allowSourceTurns`: an absent
+    // contextPolicy means "main decides", and the renderer must not assume
+    // which way DEFAULT_SWITCH_CONTEXT_POLICY went.
+    const wakeResult = await sessionActions.ensureSessionLive(
+      sessionId,
+      'provider-switch.wake-source',
+      ...(contextPolicy?.allowSourceTurns === false ? [{ awaitInputReady: false }] : []),
+    )
 
     // The translated target transcript must be created BEFORE we replace the
     // live pane. If translation fails, the current provider process should stay
@@ -331,25 +371,37 @@ export async function switchAgentProvider(params: {
       })
       onProgress?.({ phase: event.phase, message: event.message })
     })
-    const result = await window.api.switchProvider({
-      sourceKind,
-      // Explicit target (#394 phase 5a). This helper always KNEW the
-      // target — its callers pass it — but historically dropped it
-      // before IPC and relied on main's two-provider negation. With
-      // the negation slated for removal, the renderer's choice is now
-      // authoritative end-to-end.
-      targetKind,
-      sourceProviderSessionId,
-      sourceSessionId: sessionId,
-      cwd: meta.cwd,
-      // A policy the caller passed and this function silently dropped would be
-      // a trap for the caller that sets `allowSourceTurns` and wonders why the
-      // source was never asked to compact. Both keys are spread conditionally
-      // so an unset policy still reaches main as "absent", letting
-      // DEFAULT_SWITCH_CONTEXT_POLICY stay the single source of the defaults.
-      ...(contextPolicy ? { contextPolicy } : {}),
-      ...(sourceCompactionConfirmed ? { sourceCompactionConfirmed } : {}),
-    }).finally(unsubscribeProgress)
+    // WHY try/finally rather than `.finally(unsubscribeProgress)` on the
+    // promise: if `window.api.switchProvider` throws SYNCHRONOUSLY — a preload
+    // shape mismatch, a serialisation failure on the argument object — no
+    // promise is ever created, `.finally` is never attached, and this listener
+    // survives for the life of the renderer, writing into a session that has
+    // moved on. `startArrivalCompaction` already guards exactly this case;
+    // this path did not.
+    let result: Awaited<ReturnType<typeof window.api.switchProvider>>
+    try {
+      result = await window.api.switchProvider({
+        sourceKind,
+        // Explicit target (#394 phase 5a). This helper always KNEW the
+        // target — its callers pass it — but historically dropped it
+        // before IPC and relied on main's two-provider negation. With
+        // the negation slated for removal, the renderer's choice is now
+        // authoritative end-to-end.
+        targetKind,
+        sourceProviderSessionId,
+        sourceSessionId: sessionId,
+        cwd: meta.cwd,
+        // A policy the caller passed and this function silently dropped would be
+        // a trap for the caller that sets `allowSourceTurns` and wonders why the
+        // source was never asked to compact. Both keys are spread conditionally
+        // so an unset policy still reaches main as "absent", letting
+        // DEFAULT_SWITCH_CONTEXT_POLICY stay the single source of the defaults.
+        ...(contextPolicy ? { contextPolicy } : {}),
+        ...(sourceCompactionConfirmed ? { sourceCompactionConfirmed } : {}),
+      })
+    } finally {
+      unsubscribeProgress()
+    }
 
     if (result.kind === 'source-empty') {
       return await replaceTranscriptlessPane()
diff --git a/src/renderer/src/workspace/hook/actions/session.ts b/src/renderer/src/workspace/hook/actions/session.ts
index db1d6d3c..63606d36 100644
--- a/src/renderer/src/workspace/hook/actions/session.ts
+++ b/src/renderer/src/workspace/hook/actions/session.ts
@@ -25,6 +25,10 @@ import {
 } from '@renderer/workspace/idRemap'
 import { closeLeaf, collectLeaves, remapTileTreeSessionIds } from '@renderer/workspace/tile-tree/treeOps'
 import type { Tab } from '@renderer/workspace/types'
+import {
+  releaseIdentityCarry,
+  reserveIdentityCarry,
+} from '@renderer/workspace/agentNames/pendingIdentityCarry'
 import { sessionSpawnErrorMessage } from '@renderer/workspace/spawn/errorMessage'
 import {
   ghostsToPersist,
@@ -138,6 +142,66 @@ export async function killSessionBackendIfOwned(
   })
 }
 
+/**
+ * Shallow value-equality over two session-meta records.
+ *
+ * WHY this exists rather than letting the spread decide: several callers use
+ * the meta object's IDENTITY as a "is my target still the same pane?" token
+ * across an await (deliverTextToSession's isCurrent, both prompt-template
+ * insertion paths). A wake that changed nothing but still produced a new
+ * object read to them as "the pane was replaced", so the first insertion into
+ * any pane that needed waking always failed and the retry always worked.
+ *
+ * Compared over the union of both key sets rather than over `next` alone.
+ * That is defensive rather than load-bearing AT THIS CALL SITE: the caller
+ * builds `next` as `{...current, ...recoveredMeta}`, which is always a
+ * superset of `current`'s keys, so nothing can actually disappear here. It is
+ * written this way so the function stays correct for a caller that composes a
+ * meta object differently — a field vanishing must count as a change, or a
+ * holder gets a token that outlived the fact it stood for.
+ *
+ * (Worth knowing, and NOT introduced here: that superset property also means
+ * the wake's `withoutProvisionalProviderSession` is inert. It strips
+ * `providerSessionId`/`providerSessionIdSource` from `restoredMeta` and the
+ * spread puts them straight back from `current`. The same helper does take
+ * effect where it is spread into a FRESH object instead. Pre-existing, out of
+ * scope for a comparison function, but this is where someone will next look
+ * for it.)
+ *
+ * Shallow is sufficient for the VALUES, with one exception that
+ * `metaValuesEqual` handles: `builtInMcpDomains` is an array and is rebuilt on
+ * every wake. Everything else on SessionMeta is a primitive.
+ */
+function metaValuesEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  // WHY arrays need an element-wise pass rather than reference equality:
+  //
+  // `builtInMcpDomains` is the one array field on SessionMeta, and the wake
+  // path REBUILDS it every time — `resolveSessionBuiltInMcpDomains` ends in a
+  // filter, so it returns a fresh array even when the contents are identical.
+  // A pure `Object.is` comparison therefore reported "changed" on every wake
+  // of every agent pane, which is precisely the population this whole
+  // comparison exists to protect, and would have left the bug fixed only for
+  // plain terminals.
+  //
+  // Elements are a string union, so a shallow pass is exact. Nothing else on
+  // SessionMeta is an object or array; if that ever changes, this function is
+  // where the new shape has to be answered rather than silently compared by
+  // reference.
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((value, index) => Object.is(value, b[index]))
+  }
+  return false
+}
+
+function metaIsUnchanged(current: SessionMeta, next: SessionMeta): boolean {
+  const a = current as unknown as Record<string, unknown>
+  const b = next as unknown as Record<string, unknown>
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)])
+  for (const key of keys) if (!metaValuesEqual(a[key], b[key])) return false
+  return true
+}
+
 function softReloadRuntime(current: SessionRuntime, hasProviderSession: boolean): SessionRuntime {
   if (!hasProviderSession) {
     // WHY no-provider soft reload is non-destructive:
@@ -301,172 +365,221 @@ export function useSessionActions(
       let sessionId: SessionId
       let tmuxName: string | undefined
       let startedProviderSessionId: string | undefined
+      // What this spawn reserved, if anything. `replaceSession` owns the
+      // release for every path AFTER spawn resolves, but it never sees an id
+      // when spawn THROWS — and by then the successor may already be
+      // committed to state.sessions, so a stranded reservation would leave a
+      // real pane permanently unnamed. That is the mirror-image bug of the
+      // name leak this reservation exists to stop, so spawn owns its own
+      // failure path.
+      let reservedIdentityCarry: SessionId | null = null
       try {
-        const result = await window.api.spawnSession({
+        try {
+          const result = await window.api.spawnSession({
+            kind,
+            providerRuntime: opts?.providerRuntime,
+            cwd,
+            resumeSessionId: opts?.resumeSessionId,
+            ...(opts?.predecessorSessionId
+              ? { predecessorSessionId: opts.predecessorSessionId }
+              : {}),
+            dangerousMode,
+            useProxy,
+            recoverTmuxName: opts?.recoverTmuxName,
+            builtInMcpDomains,
+          })
+          sessionId = result.sessionId
+          tmuxName = result.tmuxName
+          startedProviderSessionId = result.providerSessionId
+          // WHY the reservation happens HERE, before this function's own commit:
+          //
+          // The gap the reconciler exploits opens the moment the successor's
+          // metadata lands in `state.sessions` without an `agentNameId`, and
+          // that is the setState a few lines below. `replaceSession` cannot
+          // reserve after `await spawn(...)` because by then React has already
+          // been given the chance to flush. Only spawn knows the id early
+          // enough.
+          //
+          // WHY this is NOT also gated on the predecessor already HAVING an
+          // identity, which a first version tried:
+          //
+          // The gate has to match the predicate the CARRY uses, and the carry
+          // reads `prev.sessions[oldId]?.agentNameId` at COMMIT time, which is
+          // later. A predecessor that is still unnamed when spawn runs can be
+          // claimed by the reconciler during the await — at which point there
+          // IS an identity to carry — and the narrower gate had left the
+          // successor claimable in that same window. It allocates a name, the
+          // commit overwrites it, and that name is orphaned forever. That is
+          // the exact leak this reservation exists to close, one step
+          // narrower.
+          //
+          // Reserving for every replacement costs nothing when there is
+          // nothing to carry: the successor simply claims after release, on
+          // the next state change, under its own id — the outcome the
+          // replacement commit's comment already describes as correct.
+          //
+          // `predecessorSessionId` is passed by `replaceSession` and nothing
+          // else, so this cannot fire for an ordinary spawn.
+          if (opts?.predecessorSessionId) {
+            reserveIdentityCarry(sessionId)
+            reservedIdentityCarry = sessionId
+          }
+          if (result.replacementTransactionId) {
+            // WHY presence, not renderer inference: only main can prove the
+            // successor targeted the predecessor's exact Codex rollout and
+            // therefore consumed the destructive handoff. replaceSession uses
+            // this marker to suppress its legacy predecessor kill; workspace
+            // persistence later commits the still-pending main transaction.
+            pendingReplacementSuccessorsRef.current.add(sessionId)
+          }
+        } catch (err) {
+          throw new Error(sessionSpawnErrorMessage(kind, err, useProxy === true))
+        }
+        const previousMeta = refs.stateRef.current.sessions[sessionId]
+        const requestedProviderSessionId = opts?.resumeSessionId ?? startedProviderSessionId
+        // WHY spawn does NOT mint agentNameId: replaceSession spawns through this
+        // same function, so a seed here lands on the SUCCESSOR and then wins the
+        // spread in the replacement commit, renaming a pane that only changed
+        // backends. Minting lives in one place — the reconciler — which sees the
+        // restored workspace and can tell a new agent from a recovered one.
+        const meta: SessionMeta = {
+          ...(previousMeta ?? {}),
+          cwd,
           kind,
+          // Write the field even when absent so a pathological reused id cannot
+          // inherit an alternate runtime from stale metadata.
           providerRuntime: opts?.providerRuntime,
-          cwd,
-          resumeSessionId: opts?.resumeSessionId,
-          ...(opts?.predecessorSessionId
-            ? { predecessorSessionId: opts.predecessorSessionId }
+          ...(tmuxName ? { tmuxName } : {}),
+          ...(kind !== 'terminal' && requestedProviderSessionId
+            ? {
+                providerSessionId: requestedProviderSessionId,
+                providerSessionIdSource: opts?.resumeSessionId
+                  ? 'resume-request' as const
+                  : 'runtime-start' as const,
+              }
+            : {}),
+          ...(isAgentProviderKind(kind) && builtInMcpDomains !== undefined
+            ? { builtInMcpDomains }
             : {}),
-          dangerousMode,
-          useProxy,
-          recoverTmuxName: opts?.recoverTmuxName,
-          builtInMcpDomains,
-        })
-        sessionId = result.sessionId
-        tmuxName = result.tmuxName
-        startedProviderSessionId = result.providerSessionId
-        if (result.replacementTransactionId) {
-          // WHY presence, not renderer inference: only main can prove the
-          // successor targeted the predecessor's exact Codex rollout and
-          // therefore consumed the destructive handoff. replaceSession uses
-          // this marker to suppress its legacy predecessor kill; workspace
-          // persistence later commits the still-pending main transaction.
-          pendingReplacementSuccessorsRef.current.add(sessionId)
         }
-      } catch (err) {
-        throw new Error(sessionSpawnErrorMessage(kind, err, useProxy === true))
-      }
-      const previousMeta = refs.stateRef.current.sessions[sessionId]
-      const requestedProviderSessionId = opts?.resumeSessionId ?? startedProviderSessionId
-      // WHY spawn does NOT mint agentNameId: replaceSession spawns through this
-      // same function, so a seed here lands on the SUCCESSOR and then wins the
-      // spread in the replacement commit, renaming a pane that only changed
-      // backends. Minting lives in one place — the reconciler — which sees the
-      // restored workspace and can tell a new agent from a recovered one.
-      const meta: SessionMeta = {
-        ...(previousMeta ?? {}),
-        cwd,
-        kind,
-        // Write the field even when absent so a pathological reused id cannot
-        // inherit an alternate runtime from stale metadata.
-        providerRuntime: opts?.providerRuntime,
-        ...(tmuxName ? { tmuxName } : {}),
-        ...(kind !== 'terminal' && requestedProviderSessionId
-          ? {
-              providerSessionId: requestedProviderSessionId,
-              providerSessionIdSource: opts?.resumeSessionId
-                ? 'resume-request' as const
-                : 'runtime-start' as const,
-            }
-          : {}),
-        ...(isAgentProviderKind(kind) && builtInMcpDomains !== undefined
-          ? { builtInMcpDomains }
-          : {}),
-      }
-      setState(prev => ({
-        ...prev,
-        sessions: {
-          ...prev.sessions,
-          // Persist tmuxName when main returns one — that's the
-          // signal that this terminal got tmux backing and is
-          // eligible for cross-restart recovery on next launch.
-          [sessionId]: meta,
-        },
-      }))
-      setRuntimes(prev => {
-        const current = prev[sessionId]
-        const base = emptyRuntime()
-        return {
+        setState(prev => ({
           ...prev,
-          [sessionId]: {
-            ...base,
-            ...(kind !== 'terminal' && opts?.providerRuntime !== 'terminal'
-              ? seedResumedRuntimeFields(current, meta)
-              : {
-                  hasOlderHistory: false,
-                  transcriptStatus: 'ready' as const,
-                  transcriptError: null,
-                  processStatus: 'started' as const,
-                  processError: null,
-                  inputReady: current?.inputReady ?? false,
-                  inputReadinessRevision: current?.inputReadinessRevision ?? -1,
-                }),
-            exited: current?.exited ?? null,
+          sessions: {
+            ...prev.sessions,
+            // Persist tmuxName when main returns one — that's the
+            // signal that this terminal got tmux backing and is
+            // eligible for cross-restart recovery on next launch.
+            [sessionId]: meta,
           },
-        }
-      })
-      if (kind !== 'terminal' && meta.providerRuntime !== 'terminal' && meta.providerSessionId) {
-        void loadInitialHistoryForSession({
-          sessionId,
-          meta,
-          refs,
-          setRuntimes,
+        }))
+        setRuntimes(prev => {
+          const current = prev[sessionId]
+          const base = emptyRuntime()
+          return {
+            ...prev,
+            [sessionId]: {
+              ...base,
+              ...(kind !== 'terminal' && opts?.providerRuntime !== 'terminal'
+                ? seedResumedRuntimeFields(current, meta)
+                : {
+                    hasOlderHistory: false,
+                    transcriptStatus: 'ready' as const,
+                    transcriptError: null,
+                    processStatus: 'started' as const,
+                    processError: null,
+                    inputReady: current?.inputReady ?? false,
+                    inputReadinessRevision: current?.inputReadinessRevision ?? -1,
+                  }),
+              exited: current?.exited ?? null,
+            },
+          }
         })
-      }
+        if (kind !== 'terminal' && meta.providerRuntime !== 'terminal' && meta.providerSessionId) {
+          void loadInitialHistoryForSession({
+            sessionId,
+            meta,
+            refs,
+            setRuntimes,
+          })
+        }
 
-      // Ghost log bootstrap — fire-and-forget, no await. If a prior
-      // run of Agent Code persisted ghosts for this sessionId, replay
-      // them through the atp reducer and merge into the runtime's
-      // ghost map. The renderer then sees the same merged feed after
-      // reload as it saw before. A missing file is not an error.
-      //
-      // WHY behind a setTimeout 0: spawnSession above set the fresh
-      // runtime via setRuntimes(prev => ...) — that update is queued
-      // and will land on the next tick. Reading the ghost log and
-      // applying it synchronously would run against the PREVIOUS
-      // runtime snapshot and its setRuntimes would clobber the
-      // fresh empty runtime. Deferring by one tick lets the empty
-      // runtime land first, then the bootstrap merge runs on top.
-      setTimeout(() => {
-        void window.api
-          .ghostRead(sessionId)
-          .then(rawEntries => {
-            if (!rawEntries || rawEntries.length === 0) return
-            const bootstrapped = reduceGhostLog(rawEntries as never[])
-            if (bootstrapped.size === 0) return
-            setRuntimes(prev => {
-              const current = prev[sessionId]
-              if (!current) return prev
-              // Merge — disk ghosts only fill slots the runtime
-              // hasn't already produced in this session. If a ghost
-              // for the same uuid exists in-memory (rare; would mean
-              // a live event beat the bootstrap read), prefer the
-              // in-memory one because it's strictly fresher.
-              let merged = new Map(current.ghosts)
-              for (const [uuid, ghost] of bootstrapped) {
-                if (!merged.has(uuid)) merged.set(uuid, ghost)
-              }
-              // Reconcile against whatever JSONL entries already
-              // landed during the initial bootstrap burst. Without
-              // this, ghosts for turns that already have committed
-              // entries in `current.entries` would stay
-              // un-superseded forever: the live JSONL ingest already
-              // ran `reconcileUpstream` against the PREVIOUS (empty)
-              // ghost map and found no matches; now that the real
-              // ghosts are landing, nothing re-checks the
-              // already-ingested entries. This pass fixes the
-              // "crashed mid-turn, resumed with an orphan ghost that
-              // actually got committed" case. See Task 7 of the
-              // 2026-04-20 rendering-fixes plan.
-              for (const entry of current.entries) {
-                merged = reconcileUpstream(entry, merged)
-              }
-              // Persist any supersedes we just produced so the next
-              // resume reads the ghosts already in their reconciled
-              // state. `ghostsToPersist` diffs by updatedAt so it
-              // only emits ghosts whose state actually changed in
-              // this pass.
-              for (const ghost of ghostsToPersist(current.ghosts, merged)) {
-                window.api.ghostAppend(sessionId, ghost)
-              }
-              return {
-                ...prev,
-                [sessionId]: { ...current, ghosts: merged },
-              }
+        // Ghost log bootstrap — fire-and-forget, no await. If a prior
+        // run of Agent Code persisted ghosts for this sessionId, replay
+        // them through the atp reducer and merge into the runtime's
+        // ghost map. The renderer then sees the same merged feed after
+        // reload as it saw before. A missing file is not an error.
+        //
+        // WHY behind a setTimeout 0: spawnSession above set the fresh
+        // runtime via setRuntimes(prev => ...) — that update is queued
+        // and will land on the next tick. Reading the ghost log and
+        // applying it synchronously would run against the PREVIOUS
+        // runtime snapshot and its setRuntimes would clobber the
+        // fresh empty runtime. Deferring by one tick lets the empty
+        // runtime land first, then the bootstrap merge runs on top.
+        setTimeout(() => {
+          void window.api
+            .ghostRead(sessionId)
+            .then(rawEntries => {
+              if (!rawEntries || rawEntries.length === 0) return
+              const bootstrapped = reduceGhostLog(rawEntries as never[])
+              if (bootstrapped.size === 0) return
+              setRuntimes(prev => {
+                const current = prev[sessionId]
+                if (!current) return prev
+                // Merge — disk ghosts only fill slots the runtime
+                // hasn't already produced in this session. If a ghost
+                // for the same uuid exists in-memory (rare; would mean
+                // a live event beat the bootstrap read), prefer the
+                // in-memory one because it's strictly fresher.
+                let merged = new Map(current.ghosts)
+                for (const [uuid, ghost] of bootstrapped) {
+                  if (!merged.has(uuid)) merged.set(uuid, ghost)
+                }
+                // Reconcile against whatever JSONL entries already
+                // landed during the initial bootstrap burst. Without
+                // this, ghosts for turns that already have committed
+                // entries in `current.entries` would stay
+                // un-superseded forever: the live JSONL ingest already
+                // ran `reconcileUpstream` against the PREVIOUS (empty)
+                // ghost map and found no matches; now that the real
+                // ghosts are landing, nothing re-checks the
+                // already-ingested entries. This pass fixes the
+                // "crashed mid-turn, resumed with an orphan ghost that
+                // actually got committed" case. See Task 7 of the
+                // 2026-04-20 rendering-fixes plan.
+                for (const entry of current.entries) {
+                  merged = reconcileUpstream(entry, merged)
+                }
+                // Persist any supersedes we just produced so the next
+                // resume reads the ghosts already in their reconciled
+                // state. `ghostsToPersist` diffs by updatedAt so it
+                // only emits ghosts whose state actually changed in
+                // this pass.
+                for (const ghost of ghostsToPersist(current.ghosts, merged)) {
+                  window.api.ghostAppend(sessionId, ghost)
+                }
+                return {
+                  ...prev,
+                  [sessionId]: { ...current, ghosts: merged },
+                }
+              })
             })
-          })
-          .catch(err => {
-            // Ghost bootstrap failures are non-fatal — the session
-            // still works, we just lose crash-recovered provisional
-            // state. Log and move on.
-            console.warn('[ghost] bootstrap read failed:', err)
-          })
-      }, 0)
+            .catch(err => {
+              // Ghost bootstrap failures are non-fatal — the session
+              // still works, we just lose crash-recovered provisional
+              // state. Log and move on.
+              console.warn('[ghost] bootstrap read failed:', err)
+            })
+        }, 0)
 
-      return sessionId
+        return sessionId
+      } catch (error) {
+        // Release ONLY on failure. On success the reservation must survive
+        // until replaceSession has committed the carried identity, which is
+        // the entire point of it.
+        if (reservedIdentityCarry) releaseIdentityCarry(reservedIdentityCarry)
+        throw error
+      }
     },
     [refs.dangerousAgentsRef, refs.useProxyStreamingRef, setRuntimes, setState],
   )
@@ -881,11 +994,37 @@ export function useSessionActions(
         setState(prev => {
           const current = prev.sessions[sessionId]
           if (!current) return prev
+          const next = { ...current, ...recoveredMeta }
+          // WHY a no-op wake must preserve the meta object's IDENTITY:
+          //
+          // Callers that survive an await across a wake use this object as
+          // their "is my target still the same pane?" token —
+          // deliverTextToSession's isCurrent(), and both prompt-template
+          // insertion paths, all compare
+          // `workspaceState.sessions[id] === originalSession`. This setState
+          // ran unconditionally, so ANY wake replaced the object even when
+          // every field was unchanged, and those guards then read "the pane
+          // changed underneath me" and cancelled.
+          //
+          // The user-visible bug: inserting a prompt template or a vault key
+          // into a pane that was exited, parked, or still spawning ALWAYS
+          // failed the first time with "target pane is gone" / "Focused pane
+          // is no longer available", then worked on the retry — because by
+          // then the session was 'started', no wake ran, and no replacement
+          // happened. That is the whole "flaky, works the second time"
+          // signature.
+          //
+          // Comparing content rather than trusting the spread is the correct
+          // fix and not merely the local one: recoveredMeta genuinely changes
+          // fields some of the time (withoutProvisionalProviderSession can
+          // drop them), so a real change must still produce a new object and
+          // still invalidate those guards. Only a no-op is made free.
+          if (metaIsUnchanged(current, next)) return prev
           return {
             ...prev,
             sessions: {
               ...prev.sessions,
-              [sessionId]: { ...current, ...recoveredMeta },
+              [sessionId]: next,
             },
           }
         })
@@ -1072,160 +1211,168 @@ export function useSessionActions(
         predecessorSessionId: oldId,
         ...(builtInMcpDomains !== undefined ? { builtInMcpDomains } : {}),
       })
-      const mainHandledPredecessor =
-        pendingReplacementSuccessorsRef.current.delete(newId)
-      // A source can close or be buried while spawn awaits. Metadata alone
-      // is not ownership: committing an unplaced successor creates an invisible
-      // process and a false "completed" lifecycle receipt (#815). Read through
-      // the synchronous domain setter because React-owned refs can lag the last
-      // close action. A no-op updater preserves store identity and notifications.
-      let sourceOwned = false
-      setState(prev => { sourceOwned = canCommit(prev); return prev })
-      if (!sourceOwned) {
-        await killSession(newId, { cwd, kind: nextKind, providerRuntime })
-        return
-      }
-      if (!mainHandledPredecessor) {
-        await killSessionBackendIfOwned(refs, oldId, oldMeta)
-      }
-      // Swap the sessionId wherever this live session is placed. Grid sessions
-      // live in one tile-tree leaf; detached Dispatch sessions live in
-      // detachedSessions with no leaf at all.
-      const idMap = new Map<SessionId, SessionId>([[oldId, newId]])
-
-      let committed = false
-      setState(prev => {
-        // Backend retirement is another await. Recheck inside the actual remap
-        // commit, before touching the source draft or returning a successor ID.
-        if (!canCommit(prev)) return prev
-        committed = true
-        const sessions = { ...prev.sessions }
-        // WHY read the title from `prev` here instead of the pre-spawn
-        // snapshot: provider switches and rewinds can wait on backend work,
-        // and the user may edit or clear the pane's title during that window.
-        // The replacement is the same logical pane with a fresh transport id,
-        // so its durable glance label must follow using the latest state rather
-        // than being lost—or resurrected from a stale snapshot—on completion.
-        const replacementTitle = prev.sessions[oldId]?.title
-        // `prev.sessions[oldId]` is still readable here: only the local
-        // `sessions` copy has had oldId deleted.
-        const carriedAgentNameId = prev.sessions[oldId]?.agentNameId
-        delete sessions[oldId]
-        // Persist the replacement provider metadata immediately
-        // instead of waiting for the first transcript line to
-        // round-trip back from main. That wait window is usually
-        // short, but it is still a real race: a workspace save or
-        // pane action that snapshots SessionMeta in that gap would
-        // see "new session id, but no providerSessionId yet" and
-        // could forget how to resume the pane on the next launch.
-        //
-        // Keeping the requested resumeSessionId here makes
-        // replaceSession the single source of truth for "this pane
-        // now points at provider X's persisted transcript Y",
-        // whether the trigger was the resume picker or the new
-        // switch-provider flow.
-        sessions[newId] = {
-          ...(sessions[newId] ?? { cwd, kind: nextKind }),
-          cwd,
-          kind: nextKind,
-          providerRuntime,
-          ...(spawnOpts.resumeSessionId
-            ? {
-                providerSessionId: spawnOpts.resumeSessionId,
-                providerSessionIdSource: 'resume-request' as const,
-              }
-            : {}),
-          ...(builtInMcpDomains !== undefined ? { builtInMcpDomains } : {}),
-          ...(replacementTitle !== undefined ? { title: replacementTitle } : {}),
-          // Last on purpose. `...(sessions[newId] ?? …)` earlier in this
-          // literal is the successor's OWN freshly-spawned metadata, so any
-          // earlier position is overwritten by it — which is exactly how the
-          // sketch renamed a pane on every provider switch.
-          //
-          // Conditional, not `?? oldId`: this site CARRIES an identity, it
-          // never creates one. If the predecessor had none — names were off,
-          // or the reconciler had not run — then no name was ever allocated to
-          // preserve, and inventing `oldId` here would make replacement a
-          // second minting site competing with the reconciler for that
-          // decision. Leaving it absent lets the reconciler claim the
-          // successor under its own id, which is the same outcome by the one
-          // rule the feature has.
-          ...(carriedAgentNameId !== undefined ? { agentNameId: carriedAgentNameId } : {}),
-        }
-        const detachedSessions = { ...prev.detachedSessions }
-        const detached = detachedSessions[oldId]
-        if (detached) {
-          delete detachedSessions[oldId]
-          detachedSessions[newId] = { ...detached, sessionId: newId }
+      // WHY a finally, and why it wraps EVERY exit path including the bail-outs:
+      // a stranded reservation would leave that pane permanently unnamed, which is
+      // the mirror-image bug and just as bad as the leak it prevents. Releasing an
+      // id that was never reserved is a no-op, so an ordinary spawn costs nothing.
+      try {
+        const mainHandledPredecessor =
+          pendingReplacementSuccessorsRef.current.delete(newId)
+        // A source can close or be buried while spawn awaits. Metadata alone
+        // is not ownership: committing an unplaced successor creates an invisible
+        // process and a false "completed" lifecycle receipt (#815). Read through
+        // the synchronous domain setter because React-owned refs can lag the last
+        // close action. A no-op updater preserves store identity and notifications.
+        let sourceOwned = false
+        setState(prev => { sourceOwned = canCommit(prev); return prev })
+        if (!sourceOwned) {
+          await killSession(newId, { cwd, kind: nextKind, providerRuntime })
+          return
         }
-        return {
-          ...prev,
-          tabs: prev.tabs.map(t => {
-            if (!collectLeaves(t.root).includes(oldId)) return t
-            return {
-              ...t,
-              root: remapTileTreeSessionIds(t.root, idMap),
-              focusedSessionId:
-                t.focusedSessionId === oldId ? newId : t.focusedSessionId,
-            }
-          }),
-          // Remap relationship pointers across ALL sessions: a linked /
-          // orchestration CHILD of the swapped session carries oldId in its
-          // linkedParentId/orchestrationParentId/orchestrationRootId, so the
-          // swap has to update those too or the child renders top-level and
-          // parent-scoped orchestration reads break. (rehydrate already does
-          // this; reload/switch/resume/rewind funnel through here and didn't.)
-          sessions: remapSessionsRelationships(sessions, idMap),
-          // A pinned agent that gets a fresh id on reload/switch must follow
-          // to the new id instead of silently dropping out of the Pinned list.
-          pinnedSessionIds: remapPinnedSessionIds(prev.pinnedSessionIds, idMap),
-          gridRelatedSelections: remapGridRelatedSelections(prev.gridRelatedSelections, idMap),
-          detachedSessions,
-          // Remap the swapped session id everywhere Dispatch holds it: the
-          // classic single-view focus AND every Tiled Dispatch lane selection
-          // (dispatchMode.tiled.lanes[].selectedSessionId). reload /
-          // provider-switch / resume / rewind all funnel through here; before
-          // this, the focused lane kept pointing at the now-dead oldId and the
-          // layout's auto-fill effect re-homed it to the first tile. Same
-          // tiled-vs-grid divergence as #266/#267/#271, fixed at the swap.
-          dispatchMode: remapTiledLanes(
-            prev.dispatchMode?.focusedSessionId === oldId
-              ? { ...prev.dispatchMode, focusedSessionId: newId }
-              : prev.dispatchMode,
-            idMap,
-          ),
+        if (!mainHandledPredecessor) {
+          await killSessionBackendIfOwned(refs, oldId, oldMeta)
         }
-      })
-      if (!committed) {
-        await killSession(newId, { cwd, kind: nextKind, providerRuntime })
-        return
-      }
-      setRuntimes(prev => {
-        // Replacement can await spawn and backend retirement while the user
-        // keeps editing. Transfer the latest draft in the same state update
-        // that retires its owner; a pre-await snapshot silently loses edits.
-        // All replacement paths share this contract. Rewind deliberately
-        // substitutes its historical prompt afterwards and keeps an undo copy.
-        const draft = prev[oldId] ?? draftFallback
-        const next = {
-          ...prev,
-          [newId]: {
-            ...(prev[newId] ?? emptyRuntime()),
-            draftInput: draft?.draftInput ?? '',
-            // Unsupported invisible attachments participate in submit guards.
-            // Preserve images only when the destination can expose them.
-            draftImages: isAgentProviderKind(nextKind) && getRendererProviderCapabilities(nextKind).supportsImageAttachments
-              ? (draft?.draftImages ?? []) : [],
-          },
+        // Swap the sessionId wherever this live session is placed. Grid sessions
+        // live in one tile-tree leaf; detached Dispatch sessions live in
+        // detachedSessions with no leaf at all.
+        const idMap = new Map<SessionId, SessionId>([[oldId, newId]])
+
+        let committed = false
+        setState(prev => {
+          // Backend retirement is another await. Recheck inside the actual remap
+          // commit, before touching the source draft or returning a successor ID.
+          if (!canCommit(prev)) return prev
+          committed = true
+          const sessions = { ...prev.sessions }
+          // WHY read the title from `prev` here instead of the pre-spawn
+          // snapshot: provider switches and rewinds can wait on backend work,
+          // and the user may edit or clear the pane's title during that window.
+          // The replacement is the same logical pane with a fresh transport id,
+          // so its durable glance label must follow using the latest state rather
+          // than being lost—or resurrected from a stale snapshot—on completion.
+          const replacementTitle = prev.sessions[oldId]?.title
+          // `prev.sessions[oldId]` is still readable here: only the local
+          // `sessions` copy has had oldId deleted.
+          const carriedAgentNameId = prev.sessions[oldId]?.agentNameId
+          delete sessions[oldId]
+          // Persist the replacement provider metadata immediately
+          // instead of waiting for the first transcript line to
+          // round-trip back from main. That wait window is usually
+          // short, but it is still a real race: a workspace save or
+          // pane action that snapshots SessionMeta in that gap would
+          // see "new session id, but no providerSessionId yet" and
+          // could forget how to resume the pane on the next launch.
+          //
+          // Keeping the requested resumeSessionId here makes
+          // replaceSession the single source of truth for "this pane
+          // now points at provider X's persisted transcript Y",
+          // whether the trigger was the resume picker or the new
+          // switch-provider flow.
+          sessions[newId] = {
+            ...(sessions[newId] ?? { cwd, kind: nextKind }),
+            cwd,
+            kind: nextKind,
+            providerRuntime,
+            ...(spawnOpts.resumeSessionId
+              ? {
+                  providerSessionId: spawnOpts.resumeSessionId,
+                  providerSessionIdSource: 'resume-request' as const,
+                }
+              : {}),
+            ...(builtInMcpDomains !== undefined ? { builtInMcpDomains } : {}),
+            ...(replacementTitle !== undefined ? { title: replacementTitle } : {}),
+            // Last on purpose. `...(sessions[newId] ?? …)` earlier in this
+            // literal is the successor's OWN freshly-spawned metadata, so any
+            // earlier position is overwritten by it — which is exactly how the
+            // sketch renamed a pane on every provider switch.
+            //
+            // Conditional, not `?? oldId`: this site CARRIES an identity, it
+            // never creates one. If the predecessor had none — names were off,
+            // or the reconciler had not run — then no name was ever allocated to
+            // preserve, and inventing `oldId` here would make replacement a
+            // second minting site competing with the reconciler for that
+            // decision. Leaving it absent lets the reconciler claim the
+            // successor under its own id, which is the same outcome by the one
+            // rule the feature has.
+            ...(carriedAgentNameId !== undefined ? { agentNameId: carriedAgentNameId } : {}),
+          }
+          const detachedSessions = { ...prev.detachedSessions }
+          const detached = detachedSessions[oldId]
+          if (detached) {
+            delete detachedSessions[oldId]
+            detachedSessions[newId] = { ...detached, sessionId: newId }
+          }
+          return {
+            ...prev,
+            tabs: prev.tabs.map(t => {
+              if (!collectLeaves(t.root).includes(oldId)) return t
+              return {
+                ...t,
+                root: remapTileTreeSessionIds(t.root, idMap),
+                focusedSessionId:
+                  t.focusedSessionId === oldId ? newId : t.focusedSessionId,
+              }
+            }),
+            // Remap relationship pointers across ALL sessions: a linked /
+            // orchestration CHILD of the swapped session carries oldId in its
+            // linkedParentId/orchestrationParentId/orchestrationRootId, so the
+            // swap has to update those too or the child renders top-level and
+            // parent-scoped orchestration reads break. (rehydrate already does
+            // this; reload/switch/resume/rewind funnel through here and didn't.)
+            sessions: remapSessionsRelationships(sessions, idMap),
+            // A pinned agent that gets a fresh id on reload/switch must follow
+            // to the new id instead of silently dropping out of the Pinned list.
+            pinnedSessionIds: remapPinnedSessionIds(prev.pinnedSessionIds, idMap),
+            gridRelatedSelections: remapGridRelatedSelections(prev.gridRelatedSelections, idMap),
+            detachedSessions,
+            // Remap the swapped session id everywhere Dispatch holds it: the
+            // classic single-view focus AND every Tiled Dispatch lane selection
+            // (dispatchMode.tiled.lanes[].selectedSessionId). reload /
+            // provider-switch / resume / rewind all funnel through here; before
+            // this, the focused lane kept pointing at the now-dead oldId and the
+            // layout's auto-fill effect re-homed it to the first tile. Same
+            // tiled-vs-grid divergence as #266/#267/#271, fixed at the swap.
+            dispatchMode: remapTiledLanes(
+              prev.dispatchMode?.focusedSessionId === oldId
+                ? { ...prev.dispatchMode, focusedSessionId: newId }
+                : prev.dispatchMode,
+              idMap,
+            ),
+          }
+        })
+        if (!committed) {
+          await killSession(newId, { cwd, kind: nextKind, providerRuntime })
+          return
         }
-        delete next[oldId]
-        return next
-      })
-      delete refs.seenUuidsRef.current[oldId]
-      clearLiveEntryWindowSession(oldId)
-      delete refs.latestScreenRef.current[oldId]
+        setRuntimes(prev => {
+          // Replacement can await spawn and backend retirement while the user
+          // keeps editing. Transfer the latest draft in the same state update
+          // that retires its owner; a pre-await snapshot silently loses edits.
+          // All replacement paths share this contract. Rewind deliberately
+          // substitutes its historical prompt afterwards and keeps an undo copy.
+          const draft = prev[oldId] ?? draftFallback
+          const next = {
+            ...prev,
+            [newId]: {
+              ...(prev[newId] ?? emptyRuntime()),
+              draftInput: draft?.draftInput ?? '',
+              // Unsupported invisible attachments participate in submit guards.
+              // Preserve images only when the destination can expose them.
+              draftImages: isAgentProviderKind(nextKind) && getRendererProviderCapabilities(nextKind).supportsImageAttachments
+                ? (draft?.draftImages ?? []) : [],
+            },
+          }
+          delete next[oldId]
+          return next
+        })
+        delete refs.seenUuidsRef.current[oldId]
+        clearLiveEntryWindowSession(oldId)
+        delete refs.latestScreenRef.current[oldId]
 
-      return newId
+        return newId
+      } finally {
+        releaseIdentityCarry(newId)
+      }
     },
     [
       refs.latestRuntimesRef,
diff --git a/src/renderer/src/workspace/hook/actions/sessionMetaIdentity.renderer.test.ts b/src/renderer/src/workspace/hook/actions/sessionMetaIdentity.renderer.test.ts
new file mode 100644
index 00000000..ddc1c764
--- /dev/null
+++ b/src/renderer/src/workspace/hook/actions/sessionMetaIdentity.renderer.test.ts
@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest'
+
+// The behaviour under test is a private helper, so this exercises the SHAPE
+// rule it enforces rather than importing it: after a wake that changed
+// nothing, the session-meta object must keep its identity.
+//
+// WHY that matters at all — it is not an optimisation:
+//
+// deliverTextToSession's isCurrent(), and both prompt-template insertion
+// paths, use the meta object's IDENTITY as their "is my target still the same
+// pane?" token across an await. ensureSessionLive committed its recovered meta
+// unconditionally, so ANY wake replaced that object even when every field was
+// identical, and those guards read it as "the pane changed underneath me" and
+// cancelled. Inserting a template or a vault key into a pane that was exited,
+// parked, or still spawning therefore ALWAYS failed the first time with
+// "target pane is gone", and always worked on the retry.
+//
+// The trap this file exists to pin: `builtInMcpDomains` is rebuilt on every
+// wake (resolveSessionBuiltInMcpDomains ends in a filter, so it returns a
+// fresh array with identical contents). A reference-equality comparison
+// reports "changed" for it every single time, which would leave the bug fixed
+// only for plain terminals — the one population that does not carry the field.
+
+type Meta = Record<string, unknown>
+
+function metaValuesEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((value, index) => Object.is(value, b[index]))
+  }
+  return false
+}
+
+function metaIsUnchanged(current: Meta, next: Meta): boolean {
+  const keys = new Set([...Object.keys(current), ...Object.keys(next)])
+  for (const key of keys) if (!metaValuesEqual(current[key], next[key])) return false
+  return true
+}
+
+describe('session meta no-op detection', () => {
+  it('treats a rebuilt but identical domain array as unchanged', () => {
+    const current = { cwd: '/recorded', kind: 'claude', builtInMcpDomains: ['workflows'] }
+    // A different array object with the same contents — exactly what every
+    // wake produces for an agent pane.
+    const next = { cwd: '/recorded', kind: 'claude', builtInMcpDomains: ['workflows'] }
+
+    expect(next.builtInMcpDomains).not.toBe(current.builtInMcpDomains)
+    expect(metaIsUnchanged(current, next)).toBe(true)
+  })
+
+  it('sees a real change to the domain list', () => {
+    expect(metaIsUnchanged(
+      { builtInMcpDomains: ['workflows'] },
+      { builtInMcpDomains: ['workflows', 'ping'] },
+    )).toBe(false)
+    expect(metaIsUnchanged(
+      { builtInMcpDomains: ['workflows'] },
+      { builtInMcpDomains: ['ping'] },
+    )).toBe(false)
+    // Order is content: the list is passed to a provider launch, so a
+    // reordering is a different launch even if the set matches.
+    expect(metaIsUnchanged(
+      { builtInMcpDomains: ['workflows', 'ping'] },
+      { builtInMcpDomains: ['ping', 'workflows'] },
+    )).toBe(false)
+  })
+
+  it('sees a scalar change', () => {
+    expect(metaIsUnchanged(
+      { cwd: '/recorded', providerRuntime: 'headless' },
+      { cwd: '/recorded', providerRuntime: 'terminal' },
+    )).toBe(false)
+  })
+
+  it('counts a DISAPPEARING field as a change', () => {
+    // withoutProvisionalProviderSession legitimately drops keys. Treating that
+    // as a no-op would hand a caller a token that outlived the fact it stood
+    // for, which is the opposite of the bug but just as wrong.
+    expect(metaIsUnchanged(
+      { cwd: '/recorded', providerSessionId: 'abc' },
+      { cwd: '/recorded' },
+    )).toBe(false)
+  })
+
+  it('counts an APPEARING field as a change', () => {
+    expect(metaIsUnchanged(
+      { cwd: '/recorded' },
+      { cwd: '/recorded', tmuxName: 'agent-1' },
+    )).toBe(false)
+  })
+
+  it('does not treat two different objects as equal just because neither is an array', () => {
+    // Nothing on SessionMeta is a plain object today. If that changes, the
+    // comparison must be taught the new shape rather than quietly reporting a
+    // difference forever — this case is the tripwire for that.
+    expect(metaIsUnchanged(
+      { nested: { a: 1 } } as Meta,
+      { nested: { a: 1 } } as Meta,
+    )).toBe(false)
+  })
+})
diff --git a/src/renderer/src/workspace/hook/persistence/codexLiveContinuity.renderer.test.tsx b/src/renderer/src/workspace/hook/persistence/codexLiveContinuity.renderer.test.tsx
index c5272c09..600e2a26 100644
--- a/src/renderer/src/workspace/hook/persistence/codexLiveContinuity.renderer.test.tsx
+++ b/src/renderer/src/workspace/hook/persistence/codexLiveContinuity.renderer.test.tsx
@@ -40,6 +40,22 @@ const { createSession, loadInitialHistoryForSession } = vi.hoisted(() => ({
   loadInitialHistoryForSession: vi.fn(),
 }))
 
+vi.mock('@main/workspaceDirectory.js', () => ({
+  // This suite drives a real SessionManager against the synthetic cwd
+  // '/fixture/project-1', which does not exist on disk. The spawn-path guard
+  // stats the cwd and would refuse the recover, so the session never starts
+  // and the JSONL identity this test waits for never arrives. Stubbed here for
+  // the same reason as sessionRecovery.integration.test.ts — these are the
+  // only two suites that construct the real manager.
+  MissingWorkspaceDirectoryError: class MissingWorkspaceDirectoryError extends Error {
+    constructor(readonly cwd: string) {
+      super(`Workspace folder is missing: ${cwd}`)
+      this.name = 'MissingWorkspaceDirectoryError'
+    }
+  },
+  assertWorkspaceDirectoryExists: vi.fn(async () => {}),
+}))
+
 vi.mock('@providers/registry.main.js', () => ({
   getMainProvider: () => ({ createSession }),
 }))
diff --git a/src/renderer/src/workspace/hook/persistence/sessionRecovery.integration.test.ts b/src/renderer/src/workspace/hook/persistence/sessionRecovery.integration.test.ts
index 7ee4e23c..a7ba468a 100644
--- a/src/renderer/src/workspace/hook/persistence/sessionRecovery.integration.test.ts
+++ b/src/renderer/src/workspace/hook/persistence/sessionRecovery.integration.test.ts
@@ -12,6 +12,21 @@ const { createSession, loadInitialHistoryForSession } = vi.hoisted(() => ({
   loadInitialHistoryForSession: vi.fn(),
 }))
 
+vi.mock('@main/workspaceDirectory.js', () => ({
+  // This suite drives real SessionManager spawns against the synthetic path
+  // '/tmp/project', which does not exist on disk. The spawn-path guard that
+  // stats the cwd is stubbed so these cases keep exercising the failure modes
+  // they were written for; workspaceDirectory.test.ts covers the guard, and
+  // sessionManager.recover.test.ts covers the manager surfacing it.
+  MissingWorkspaceDirectoryError: class MissingWorkspaceDirectoryError extends Error {
+    constructor(readonly cwd: string) {
+      super(`Workspace folder is missing: ${cwd}`)
+      this.name = 'MissingWorkspaceDirectoryError'
+    }
+  },
+  assertWorkspaceDirectoryExists: vi.fn(async () => {}),
+}))
+
 vi.mock('@providers/registry.main.js', () => ({
   getMainProvider: () => ({ createSession }),
 }))
diff --git a/src/renderer/src/workspace/terminal/xtermWebglRenderer.test.ts b/src/renderer/src/workspace/terminal/xtermWebglRenderer.test.ts
index 89f3be0a..ab5baba0 100644
--- a/src/renderer/src/workspace/terminal/xtermWebglRenderer.test.ts
+++ b/src/renderer/src/workspace/terminal/xtermWebglRenderer.test.ts
@@ -82,7 +82,7 @@ describe('xtermWebglRenderer', () => {
   it('repairs a whole atlas-layout burst after the current frame, without idle repainting', async () => {
     const addon = addonHarness()
     const terminal = terminalHarness()
-    const renderer = attachXtermWebglRenderer(terminal, async () => addon)
+    const renderer = attachXtermWebglRenderer(terminal, async () => addon, true)
     await renderer.ready
     expect(terminal.refresh).not.toHaveBeenCalled()
 
@@ -111,7 +111,7 @@ describe('xtermWebglRenderer', () => {
   it.each(['unmount', 'context loss'] as const)('cancels deferred repair after %s', async reason => {
     const addon = addonHarness()
     const terminal = terminalHarness()
-    const renderer = attachXtermWebglRenderer(terminal, async () => addon)
+    const renderer = attachXtermWebglRenderer(terminal, async () => addon, true)
     await renderer.ready
     addon.removePage()
     if (reason === 'unmount') renderer.dispose()
@@ -131,7 +131,7 @@ describe('xtermWebglRenderer', () => {
     const addon = addonHarness()
     addon.onRemoveTextureAtlasCanvas.mockImplementation(() => { throw new Error('registration failed') })
     const terminal = terminalHarness()
-    const renderer = attachXtermWebglRenderer(terminal, async () => addon)
+    const renderer = attachXtermWebglRenderer(terminal, async () => addon, true)
     await expect(renderer.ready).resolves.toBe(false)
     expect(addon.disposeAddListener).toHaveBeenCalledTimes(1)
     expect(addon.disposeRemoveListener).not.toHaveBeenCalled()
@@ -148,7 +148,7 @@ describe('xtermWebglRenderer', () => {
       return false
     })
     const terminal = terminalHarness()
-    const renderer = attachXtermWebglRenderer(terminal, async () => addon)
+    const renderer = attachXtermWebglRenderer(terminal, async () => addon, true)
     await renderer.ready
     addon.removePage()
     await Promise.resolve()
@@ -162,7 +162,7 @@ describe('xtermWebglRenderer', () => {
   it('reports readiness after handing a complete addon to the live terminal', async () => {
     const addon = addonHarness()
     const terminal = terminalHarness()
-    const renderer = attachXtermWebglRenderer(terminal, async () => addon)
+    const renderer = attachXtermWebglRenderer(terminal, async () => addon, true)
 
     await expect(renderer.ready).resolves.toBe(true)
     expect(addon.construct).toHaveBeenCalledTimes(1)
@@ -180,7 +180,7 @@ describe('xtermWebglRenderer', () => {
 
   it('disposes the context listener and addon exactly once during ordinary host teardown', async () => {
     const addon = addonHarness()
-    const renderer = attachXtermWebglRenderer(terminalHarness(), async () => addon)
+    const renderer = attachXtermWebglRenderer(terminalHarness(), async () => addon, true)
     await expect(renderer.ready).resolves.toBe(true)
 
     renderer.dispose()
@@ -193,7 +193,7 @@ describe('xtermWebglRenderer', () => {
   it('loads WebGL into a live terminal and falls back by disposing it on context loss', async () => {
     const addon = addonHarness()
     const terminal = terminalHarness()
-    const renderer = attachXtermWebglRenderer(terminal, async () => addon)
+    const renderer = attachXtermWebglRenderer(terminal, async () => addon, true)
 
     await expect(renderer.ready).resolves.toBe(true)
     expect(terminal.loadAddon).toHaveBeenCalledTimes(1)
@@ -216,7 +216,7 @@ describe('xtermWebglRenderer', () => {
     const pending = deferred<ReturnType<typeof addonHarness>>()
     const terminal = terminalHarness()
     const load = vi.fn(() => pending.promise)
-    const renderer = attachXtermWebglRenderer(terminal, load)
+    const renderer = attachXtermWebglRenderer(terminal, load, true)
     // Fence a genuinely in-flight import, not only a loader that never started.
     await Promise.resolve()
     expect(load).toHaveBeenCalledTimes(1)
@@ -240,7 +240,7 @@ describe('xtermWebglRenderer', () => {
       }
       // Optional GPU support must neither throw from attachment nor reject
       // ready: both turn recoverable renderer failures into broken terminals.
-      const renderer = attachXtermWebglRenderer(terminal, load)
+      const renderer = attachXtermWebglRenderer(terminal, load, true)
       await expect(renderer.ready).resolves.toBe(false)
       expect(terminal.loadAddon).not.toHaveBeenCalled()
       expect(() => renderer.dispose()).not.toThrow()
@@ -251,7 +251,7 @@ describe('xtermWebglRenderer', () => {
     const addon = addonHarness()
     addon.construct.mockImplementation(() => { throw new Error('unsupported GPU') })
     const terminal = terminalHarness()
-    const renderer = attachXtermWebglRenderer(terminal, async () => addon)
+    const renderer = attachXtermWebglRenderer(terminal, async () => addon, true)
 
     await expect(renderer.ready).resolves.toBe(false)
     renderer.dispose()
@@ -268,7 +268,7 @@ describe('xtermWebglRenderer', () => {
       ...terminalHarness(),
       loadAddon: vi.fn(() => { throw new Error('context allocation failed') }),
     }
-    const renderer = attachXtermWebglRenderer(terminal, async () => addon)
+    const renderer = attachXtermWebglRenderer(terminal, async () => addon, true)
 
     await expect(renderer.ready).resolves.toBe(false)
     expect(terminal.loadAddon).toHaveBeenCalledTimes(1)
@@ -283,7 +283,7 @@ describe('xtermWebglRenderer', () => {
     const addon = addonHarness()
     addon.onContextLoss.mockImplementation(() => { throw new Error('registration failed') })
     const terminal = terminalHarness()
-    const renderer = attachXtermWebglRenderer(terminal, async () => addon)
+    const renderer = attachXtermWebglRenderer(terminal, async () => addon, true)
 
     await expect(renderer.ready).resolves.toBe(false)
     renderer.dispose()
@@ -296,7 +296,7 @@ describe('xtermWebglRenderer', () => {
     const addon = addonHarness()
     addon.disposeContextListener.mockImplementation(() => { throw new Error('listener cleanup failed') })
     addon.disposeAddon.mockImplementation(() => { throw new Error('GPU cleanup failed') })
-    const renderer = attachXtermWebglRenderer(terminalHarness(), async () => addon)
+    const renderer = attachXtermWebglRenderer(terminalHarness(), async () => addon, true)
     await expect(renderer.ready).resolves.toBe(true)
     const disposeHost = vi.fn()
 
@@ -315,7 +315,7 @@ describe('xtermWebglRenderer', () => {
   it('clears ownership before a disposer re-enters context-loss cleanup', async () => {
     const addon = addonHarness()
     addon.disposeContextListener.mockImplementation(() => addon.loseContext())
-    const renderer = attachXtermWebglRenderer(terminalHarness(), async () => addon)
+    const renderer = attachXtermWebglRenderer(terminalHarness(), async () => addon, true)
     await expect(renderer.ready).resolves.toBe(true)
 
     renderer.dispose()
@@ -323,4 +323,36 @@ describe('xtermWebglRenderer', () => {
     expect(addon.disposeContextListener).toHaveBeenCalledTimes(1)
     expect(addon.disposeAddon).toHaveBeenCalledTimes(1)
   })
+
+  it('does not attach anything by default, because the GPU renderer is off', async () => {
+    // Pins the WEBGL_RENDERER_ENABLED decision. Our pinned addon-webgl 0.19.0
+    // corrupts its own texture atlas under streaming TUI output (upstream
+    // xterm.js #5883), and the fix exists only in a 0.20.0 beta whose peer
+    // range would drag @xterm/xterm itself onto a beta. Until that is stable
+    // the DOM renderer is what ships. If this case starts failing, someone
+    // re-enabled WebGL — make sure the upgrade actually happened.
+    const addon = addonHarness()
+    const terminal = terminalHarness()
+    const load = vi.fn(async () => addon)
+
+    const renderer = attachXtermWebglRenderer(terminal, load)
+
+    await expect(renderer.ready).resolves.toBe(false)
+    // Not merely inactive: the addon module is never even imported, so a
+    // disabled renderer costs no parse, no GPU context and no listeners.
+    expect(load).not.toHaveBeenCalled()
+    expect(terminal.loadAddon).not.toHaveBeenCalled()
+    // Disposing a renderer that never attached must still be safe — every
+    // call site disposes unconditionally on unmount.
+    expect(() => renderer.dispose()).not.toThrow()
+  })
+
+  it('reports not-ready without touching the terminal when explicitly disabled', async () => {
+    const terminal = terminalHarness()
+    const renderer = attachXtermWebglRenderer(terminal, async () => addonHarness(), false)
+
+    await expect(renderer.ready).resolves.toBe(false)
+    expect(terminal.loadAddon).not.toHaveBeenCalled()
+    expect(terminal.refresh).not.toHaveBeenCalled()
+  })
 })
diff --git a/src/renderer/src/workspace/terminal/xtermWebglRenderer.ts b/src/renderer/src/workspace/terminal/xtermWebglRenderer.ts
index c1ba3940..6ee30824 100644
--- a/src/renderer/src/workspace/terminal/xtermWebglRenderer.ts
+++ b/src/renderer/src/workspace/terminal/xtermWebglRenderer.ts
@@ -53,6 +53,53 @@ const loadWebglAddon = async (): Promise<WebglAddonModule> => {
   }
 }
 
+/**
+ * Is the GPU renderer allowed to attach at all?
+ *
+ * Currently NO, and this is the whole switch. Flip it back when the condition
+ * in the next paragraph is met; everything else in this file is intact and
+ * needs no other change.
+ *
+ * WHY: our pinned `@xterm/addon-webgl@0.19.0` corrupts its own texture atlas
+ * under exactly the workload this app runs all day — a provider TUI streaming
+ * heavy, colourful, constantly-redrawn output. Upstream xterm.js #5883 (merged
+ * 2026-05-21) names the two bugs precisely: a fresh atlas page replacing an old
+ * one AT THE SAME INDEX after a merge, which per-page version counters cannot
+ * detect, and a stale vertex buffer after a mid-render merge because
+ * `_requestClearModel` was set and never reset. The visible result is garbled
+ * and interleaved glyphs, characters substituted mid-word, and leftover
+ * inverse blocks that never repair because an idle terminal produces no further
+ * frame.
+ *
+ * WHY the `invalidateTextureBindings` bridge below was not enough: it can
+ * address the first bug's symptom from outside the addon. It cannot replicate
+ * the second bug's fix, nor the bounded retry loop upstream added inside
+ * `renderRows()` — both live below the addon's public surface. #789 shipped
+ * that workaround and was closed without confirming the reporter's screenshot;
+ * the corruption was reported again on 2026-09-08.
+ *
+ * WHY not simply upgrade, which is what the bridge's own comment anticipates:
+ * the fix ships only in `@xterm/addon-webgl@0.20.0-beta.219` and later, there
+ * is still no stable 0.20.0, and that beta's peer dependency is
+ * `@xterm/xterm: ^6.1.0-beta.304`. Taking it would drag the CORE terminal —
+ * the heart of every pane in the app — onto a beta as well. That is a much
+ * larger surface than the one bug being fixed.
+ *
+ * WHY this costs less than it looks: the DOM renderer is xterm's default and
+ * is correct, and it is already the tested fallback every failure path here
+ * lands on. The perf work that introduced WebGL (#783, `3b885068`) had three
+ * parts, and the two structural ones — routing raw PTY channels once per
+ * renderer via sessionDataDispatcher, and coalescing inline grid resizes —
+ * are untouched by this. VS Code ships the same escape hatch for the same
+ * symptom class as `terminal.integrated.gpuAcceleration: "off"`.
+ *
+ * FLIP THIS BACK when `@xterm/addon-webgl` has a STABLE release containing
+ * #5883 whose peer range accepts a stable `@xterm/xterm`. At that point also
+ * delete the `invalidateTextureBindings` bridge above, which exists only to
+ * paper over 0.19.0.
+ */
+const WEBGL_RENDERER_ENABLED = false
+
 /**
  * Upgrade an already-open xterm from its DOM renderer to WebGL when available.
  *
@@ -71,7 +118,22 @@ const loadWebglAddon = async (): Promise<WebglAddonModule> => {
 export function attachXtermWebglRenderer(
   terminal: TerminalAddonHost,
   loadAddon: () => Promise<WebglAddonModule> = loadWebglAddon,
+  // WHY the gate is a parameter rather than read straight from the constant:
+  // this module's suite is the only record of how the attach, fallback,
+  // context-loss and atlas-repair machinery behaves, and that machinery has to
+  // keep working for the day the constant flips back. A hard-coded read would
+  // have made all fifteen of those cases vacuous the moment WebGL went off.
+  enabled: boolean = WEBGL_RENDERER_ENABLED,
 ): XtermWebglRenderer {
+  // Bail before the dynamic import, so a disabled renderer costs nothing at
+  // all: no addon parse, no GPU context, no atlas listeners. Callers keep
+  // their existing shape and simply never see WebGL become active — the same
+  // observable result as a machine where WebGL is unavailable by policy, which
+  // this file already had to handle correctly.
+  if (!enabled) {
+    return { ready: Promise.resolve(false), dispose() {} }
+  }
+
   let disposed = false
   let addon: WebglAddonLike | null = null
   let contextLossDisposable: Disposable | null = null
diff --git a/src/renderer/src/workspace/tile-tree/AgentTerminalLeaf.tsx b/src/renderer/src/workspace/tile-tree/AgentTerminalLeaf.tsx
index 5c16b171..89f829aa 100644
--- a/src/renderer/src/workspace/tile-tree/AgentTerminalLeaf.tsx
+++ b/src/renderer/src/workspace/tile-tree/AgentTerminalLeaf.tsx
@@ -568,8 +568,11 @@ export function AgentTerminalLeaf({
               </span>
             )}
             <span className="flex-shrink-0 text-ink">raw {provider}</span>
-            <span className="truncate" title={projectDir ?? 'no project dir'}>
-              {shortenCwd(projectDir)}
+            {/* truncate-START, matching PaneHeader: keep the project directory
+                visible and drop the shared prefix instead. */}
+            <span className="truncate-start" title={projectDir ?? 'no project dir'}>
+              {/* Inner dir="ltr" required — see PaneHeader. */}
+              <span dir="ltr">{shortenCwd(projectDir)}</span>
             </span>
           </div>
           {/* TAIL pill styling copied from ScrollIndicator so both surfaces
diff --git a/src/renderer/src/workspace/tile-tree/AgentTitleHeader.tsx b/src/renderer/src/workspace/tile-tree/AgentTitleHeader.tsx
index 2cfdb59a..6285d18b 100644
--- a/src/renderer/src/workspace/tile-tree/AgentTitleHeader.tsx
+++ b/src/renderer/src/workspace/tile-tree/AgentTitleHeader.tsx
@@ -1,4 +1,7 @@
-import { useAgentName } from '@renderer/workspace/agentNames/useAgentName'
+import {
+  useAgentName,
+  useAgentNameRowReserved,
+} from '@renderer/workspace/agentNames/useAgentName'
 import type { SessionId } from '@renderer/workspace/types'
 
 // One visual contract for explicit agent titles and spoken agent names across
@@ -12,13 +15,27 @@ import type { SessionId } from '@renderer/workspace/types'
 // call sites sit on the hot pane-render path and already thread a dozen props;
 // see useAgentName for why a primitive subscription is cheaper than widening
 // them.
+//
+// WHY this row's HEIGHT is constant from first paint rather than appearing
+// with the name:
+//
+// A name arrives over IPC well after the pane mounts. Keying the row's
+// existence on the name meant every named agent pane grew ~23px mid-life on
+// every window load, which shrank the terminal box, triggered a refit, and
+// sent a second PTY resize as a SIGWINCH into a live, mid-output TUI. Ink and
+// the Claude Code TUI erase a line count computed for the frame before that
+// resize, so the redraw lands on the wrong region and leaves garbled
+// fragments behind permanently. Reserving the space removes the layout change,
+// so there is no second resize to race. See agentNameRowIsReserved.
 export function AgentTitleHeader({ sessionId, title }: { sessionId: SessionId; title?: string }) {
   const agentName = useAgentName(sessionId)
+  const reserveNameRow = useAgentNameRowReserved(sessionId)
   const visibleTitle = title?.trim()
-  // WHY the guard now checks BOTH: this row used to exist only for a title, so
+  // WHY the guard checks all three: this row used to exist only for a title, so
   // an untitled agent rendered nothing. With names on, that would hide the only
-  // address a voice operator can use while the operator can still reach it.
-  if (!visibleTitle && !agentName) return null
+  // address a voice operator can use while the operator can still reach it —
+  // and the reservation keeps the row's box stable while the name is in flight.
+  if (!visibleTitle && !agentName && !reserveNameRow) return null
 
   return (
     <div
@@ -26,7 +43,7 @@ export function AgentTitleHeader({ sessionId, title }: { sessionId: SessionId; t
       className="flex min-w-0 items-center gap-2 border-t border-border/70 bg-canvas px-3 py-1 font-code text-[11px] font-medium text-ink select-none"
       title={[agentName, visibleTitle].filter(Boolean).join(' — ')}
     >
-      {agentName && (
+      {agentName ? (
         // Fixed width contribution, never truncated: the name is the thing a
         // user says out loud, so it must survive a narrow Tiled Dispatch lane
         // even when the title does not.
@@ -36,7 +53,21 @@ export function AgentTitleHeader({ sessionId, title }: { sessionId: SessionId; t
         >
           {agentName}
         </span>
-      )}
+      ) : reserveNameRow ? (
+        // The placeholder carries the badge's exact box (border + px-1 +
+        // leading-[14px]) so the row's height cannot change when the real name
+        // replaces it. `invisible` rather than omitting it: an empty flex row
+        // collapses to its padding and would resize the terminal anyway.
+        // aria-hidden and no data-agent-name-badge, so nothing reads or
+        // queries it as a name.
+        <span
+          aria-hidden="true"
+          data-agent-name-placeholder="true"
+          className="invisible flex-shrink-0 rounded-chip border border-border px-1 leading-[14px] text-[10px] font-semibold tracking-wide"
+        >
+          &nbsp;
+        </span>
+      ) : null}
       {visibleTitle && <div className="truncate">{visibleTitle}</div>}
     </div>
   )
diff --git a/src/renderer/src/workspace/tile-tree/TerminalLeaf.tsx b/src/renderer/src/workspace/tile-tree/TerminalLeaf.tsx
index ce693d94..933a2f42 100644
--- a/src/renderer/src/workspace/tile-tree/TerminalLeaf.tsx
+++ b/src/renderer/src/workspace/tile-tree/TerminalLeaf.tsx
@@ -7,6 +7,7 @@ import { FitAddon } from '@xterm/addon-fit'
 import type { SessionId } from '@renderer/workspace/types'
 import type { Workspace } from '@renderer/workspace/workspaceStore'
 import { useAppStore } from '@renderer/app-state/hooks'
+import { PaneToast } from '@renderer/workspace/tile-tree/TileLeaf/PaneToast'
 import { useComposerDictation } from '@renderer/workspace/tile-tree/TileLeaf/useComposerDictation'
 import {
   THEME_CHANGED_EVENT,
@@ -99,6 +100,31 @@ export function TerminalLeaf({
     onMessage: message => workspace.showPaneToast(sessionId, message),
   })
 
+  // WHY this leaf renders a pane toast at all, and why it subscribes to the
+  // STRING rather than taking the runtime as a prop:
+  //
+  // Plain terminal panes were the one leaf kind that called showPaneToast
+  // (dictation at the top of this file, and the resume/backend messages
+  // below) without ever rendering PaneToast, so every one of those messages
+  // was written into the store and shown to nobody. #840 made that a dead
+  // command rather than a missing nicety: it opened terminal panes up as
+  // prompt-template and vault-key insertion targets, and routed ALL of that
+  // feature's feedback — success, "pane is not ready", "target pane is gone" —
+  // through showPaneToast. On a shell pane a failed insertion produced no
+  // toast, and the palette does not close on failure, so nothing happened at
+  // all.
+  //
+  // A primitive selector, not the whole runtime: this leaf deliberately does
+  // not re-render on runtime ticks (the xterm instance owns its own output
+  // path), and threading the runtime in as a prop would re-render it on every
+  // PTY chunk. Subscribing to the toast string re-renders on exactly the one
+  // transition that changes what is painted.
+  // Optional chain on the MAP as well as the entry: several renderer specs and
+  // the phone bundle mock the store with only the keys they use, and the
+  // repository's standing rule is that a keyless store must degrade, never
+  // throw (see agentNames/selectors.ts and PaneHeader.phoneCoupling).
+  const paneToast = useAppStore(state => state.workspaceRuntimes?.[sessionId]?.paneToast ?? null)
+
   const acknowledgeSession = workspace.acknowledgeSession
   const ensureSessionLiveRef = useRef(workspace.ensureSessionLive)
   ensureSessionLiveRef.current = workspace.ensureSessionLive
@@ -563,6 +589,16 @@ export function TerminalLeaf({
         ref={containerRef}
         className="flex-1 min-h-0 min-w-0 overflow-hidden relative"
       />
+      {/* Same slot and ordering as AgentTerminalLeaf: below the terminal box.
+          Note what this DOES cost, since the obvious reading is wrong — the
+          slot is a non-shrinking flex sibling, so while a toast is on screen
+          the xterm box really is shorter, its ResizeObserver fires, and the
+          PTY is resized down and then back up when the toast clears. That is
+          the same shape as AgentTerminalLeaf and is accepted for the same
+          reason: pane feedback that is never rendered is worse than a
+          transient reflow. It is also why the toast lives here rather than
+          overlaying the terminal, where it would hide output. */}
+      <PaneToast message={paneToast} />
     </div>
   )
 }
diff --git a/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeader.tsx b/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeader.tsx
index df1aa244..82bd8a62 100644
--- a/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeader.tsx
+++ b/src/renderer/src/workspace/tile-tree/TileLeaf/PaneHeader.tsx
@@ -121,8 +121,13 @@ export function PaneHeader({
               {paneLabel}
             </span>
           )}
-          <span className="truncate" title={projectDir ?? 'no project dir'}>
-            {shortenCwd(projectDir)}
+          {/* truncate-START: every pane shares the leading path segments, so
+              clipping the end hid the one part that identifies this agent. */}
+          <span className="truncate-start" title={projectDir ?? 'no project dir'}>
+            {/* The inner dir="ltr" is required, not decorative: the outer
+                element's rtl direction picks WHICH edge clips, and without
+                this the path's own characters are reordered with it. */}
+            <span dir="ltr">{shortenCwd(projectDir)}</span>
           </span>
         </div>
         <PaneHeaderColorFlag sessionId={sessionId} />
diff --git a/src/renderer/src/workspace/tile-tree/agentTerminalFollow.system.test.ts b/src/renderer/src/workspace/tile-tree/agentTerminalFollow.system.test.ts
index c2bf6770..bdd1c8a7 100644
--- a/src/renderer/src/workspace/tile-tree/agentTerminalFollow.system.test.ts
+++ b/src/renderer/src/workspace/tile-tree/agentTerminalFollow.system.test.ts
@@ -84,6 +84,7 @@ it('follows and restores real xterm content across trimming and buffer switches'
           await write('\\x1b[?1049h')
           tailActive = false; render()
           check(term.buffer.active.type === 'alternate' && bottom(), 'Alternate buffer was scrolled with a normal-buffer anchor')
+
           await write('\\x1b[?1049l')
           // Marker registration/disposal is public; only this diagnostic
           // enumeration requires proposed APIs. Keep them off for all behavior.
diff --git a/src/renderer/src/workspace/tile-tree/agentTerminalFollow.ts b/src/renderer/src/workspace/tile-tree/agentTerminalFollow.ts
index 4b1b7cc3..aed549cb 100644
--- a/src/renderer/src/workspace/tile-tree/agentTerminalFollow.ts
+++ b/src/renderer/src/workspace/tile-tree/agentTerminalFollow.ts
@@ -52,6 +52,16 @@ export function useAgentTerminalFollow({
     }
     if (scrollToLatestRequest === jumpBaselineRef.current) return
     jumpBaselineRef.current = scrollToLatestRequest
+    // KNOWN LIMITATION, and not fixable from here: a provider whose TUI runs
+    // on the ALTERNATE SCREEN owns its transcript internally and never evicts
+    // a line into xterm scrollback, so viewportY === baseY always holds and
+    // this call does nothing. OpenCode Terminal is exactly that case. Sending
+    // the TUI's own scroll-to-bottom chord was tried and reverted: the binding
+    // is user-configurable, so a user who has moved a destructive action onto
+    // it would have Jump to Latest abort and revert their session. The
+    // rebinding-immune route is OpenCode's POST /tui/execute-command, which
+    // needs a served transport this runtime does not use yet. See the audit
+    // doc for the full evidence.
     termRef.current?.scrollToBottom()
   }, [scrollToLatestRequest, sessionId, termRef])
 
@@ -111,6 +121,16 @@ export function useAgentTerminalFollow({
         subscription.dispose()
         savedLineRef.current?.dispose()
         savedLineRef.current = null
+        // WHY the engaged flag is reset too: detaching disposes the anchor, so
+        // there is nothing left to restore, but this flag used to survive. The
+        // xterm instance can be torn down and rebuilt under the SAME sessionId
+        // — the effect that clears per-session state is keyed on sessionId and
+        // does not re-run — so the next disengage found tailEngaged true and
+        // saved null, took the restore branch, and silently dropped the user
+        // back to wherever the fresh terminal happened to be instead of the
+        // line they were reading. Engagement describes a live terminal, so it
+        // has to end with one.
+        tailEngagedRef.current = false
       }
     },
   }), [termRef])
diff --git a/src/renderer/src/workspace/types.ts b/src/renderer/src/workspace/types.ts
index 9cc8fc8d..2bb7026b 100644
--- a/src/renderer/src/workspace/types.ts
+++ b/src/renderer/src/workspace/types.ts
@@ -585,6 +585,22 @@ export type ProviderSwitchBatch = {
   sourceKind: AgentProviderKind
   targetKind: AgentProviderKind
   agents: ProviderSwitchBatchAgent[]
+  /**
+   * Whether the user agreed to compaction-on-arrival for THIS batch, captured
+   * from the modal that asked.
+   *
+   * WHY the return path needs it rather than deciding for itself: arrival
+   * compaction spends the destination provider's quota and locks every
+   * affected composer for the arrival wait plus the compaction wait — minutes
+   * per pane, with no cancel. The forward flow puts that behind an explicit
+   * checkbox and a quota disclosure. The return flow had no modal at all and
+   * hard-coded it on for any Claude destination, so a single "Return 20" click
+   * spent Claude quota twenty times and locked twenty composers with nothing
+   * asked and nothing disclosed. Returning is the mirror of the switch the
+   * user consented to, so it reuses that consent instead of inventing new
+   * consent on the user's behalf.
+   */
+  compactOnArrival: boolean
 }
 
 export const RATIO_MIN = 0.1
diff --git a/src/shared/types/agentNames.ts b/src/shared/types/agentNames.ts
new file mode 100644
index 00000000..235aaf73
--- /dev/null
+++ b/src/shared/types/agentNames.ts
@@ -0,0 +1,28 @@
+/**
+ * Limits shared by the renderer's identity validation and main's IPC schema.
+ *
+ * WHY these live in `shared` rather than being written twice: they are one
+ * contract with two halves, and the halves silently drifted. `identityOf`
+ * (renderer) checked only that an identity was a non-empty string, while
+ * `agent-names:resolve` (main) validates `z.string().min(1).max(200)` over
+ * the whole array. A single hand-edited `workspace.json` carrying one
+ * over-long `agentNameId` therefore passed the renderer, entered the request
+ * array, and made `requestSchema.parse` reject the ENTIRE batch — which the
+ * reconciler swallows silently, so no agent in that window ever received a
+ * name and nothing said why.
+ *
+ * The renderer's own comment already named main's schema verbatim, so the
+ * intent was to mirror it; only the type half was actually mirrored, not the
+ * length half. Importing the numbers makes the next divergence impossible.
+ */
+
+/** Longest accepted `agentNameId`. Mirrors main's per-item schema. */
+export const AGENT_NAME_IDENTITY_MAX_LENGTH = 200
+
+/**
+ * Most identities one resolve request may carry.
+ *
+ * Bounded so a malformed or hostile renderer cannot make the allocator walk a
+ * huge list under the serialization tail. Far past any real workspace.
+ */
+export const AGENT_NAME_IDENTITY_REQUEST_MAX = 10_000