[Juliusolsson05]

Fixes #671

Problem

A terminal created from Dispatch — most visibly in Tiled Dispatch — always rendered at the top of its project group, above every agent, regardless of when it was created. Agents created from the same surface append in creation order. The one row you did not just create took the top slot, and the index stopped reading as a record of what you have open.

Root cause

Not a sort bug — a structural one. splitFocused carried two Dispatch branches:

kind	what it created
!== 'terminal'	detached dispatch row (detachedSessions[id], ordered by detachedAt)
=== 'terminal'	grid leaf spliced into tab.root via splitLeaf

buildDispatchGroups emits every project group as [...gridSessionIds, ...detachedSessionIds]. Every Dispatch agent is detached and every Dispatch terminal was a grid leaf, so a terminal could never sort below an agent. That concatenation is the entire cause and is sufficient on its own — the terminal's position within the grid slice never mattered, because the whole grid slice precedes the detached rows.

An earlier revision of this PR blamed the split anchor degrading to leafIds[0]. That was wrong and review caught it: focusedLeafId is tab.focusedSessionId, which focusDispatchSession deliberately never writes, so that fallback is unreachable — and splitLeaf inserts after its anchor anyway. Corrected in the code comment, the plan, and issue #671.

Implemented behavior

The two branches are now one kind-agnostic Dispatch flow. A Dispatch terminal is a detached dispatch row filed under the same resolved project an agent would get, appearing in creation order, and landing in the focused tiled lane via applyDispatchSpawnFocus. Terminals created outside Dispatch are untouched — ⌥T in normal mode still splits the grid.

Design decisions and tradeoffs

Why the old leaf-based justification no longer holds. The removed comment cited tmux name, resize lifecycle, undo/close history, and persistence as leaf-based. Each is session-scoped, and a detached terminal was already a reachable, supported state: detachFocusedToDispatch never excluded terminals; renderWorkspaceLeaf renders kind === 'terminal' inside a Dispatch lane; TerminalLeaf wakes its own backend via ensureSessionLive, which passes recoverTmuxName.

The one exception was undo/close history, which really was grid-scoped — see below.

Why route terminals through resolveDispatchSpawnTarget. It preserves #366 (project tab and cwd both from the focused lane) without a parallel terminal resolver that can drift.

Orphan guard extended to both kinds, and it now kills the backend with the kind/cwd this call already resolved rather than through an ownership proof that re-reads a render-refreshed ref — a lagging read would make the kill silently no-op and leak the very orphan the guard exists to prevent.

Undo-close: a regression this change forced, and its fix

Moving Dispatch terminals onto the detached path put them on closeSession's detached arm, which captured no undo entry. For an agent that is a lost convenience. For a terminal it is data loss: closing one stops the attach PTY but leaves the tmux session alive, and once the row is gone from workspace.json the next launch's tmux reconcile sees a live session with no persisted owner, classifies it an orphan, and kills it (src/main/tmux/tmuxRecovery.ts). Before this branch the terminal was a grid leaf, so ⌘⇧T restored it with recoverTmuxName.

Adds a third ClosedEntry variant, 'detached'. It cannot reuse ClosedPane, whose every placement field (direction, ratio, sibling anchor) is a grid concept a detached row has no answer for. The DetachedSessionRecord is stored verbatim so detachedAt — the only thing ordering rows in a project group — survives, and undo returns the row to its position rather than the bottom of the list. Restore refuses as stale when the project tab is gone, since a record under a dead tab renders in no group and would strand a live backend. Detached agents gain an undo they never had.

Cleanups riding along

• Extracted detachedDispatchRecord — five call sites hand-wrote the identical DetachedSessionRecord; the merged branch would have been a sixth.
• Deleted dead code: resolveDispatchTerminalSplitTarget, findTerminalSessionInTab, findTerminalInLatestTab, plus the sibling leftovers from the same removed project-terminal column (pendingTerminalByTabRef, two unused imports, a dangling comment fragment).
• Bury now explains itself on a Dispatch row instead of opening a prompt that accepts a note and silently does nothing.
• Corrected comments in paneCommands.ts, NewAgentPlacementOverlay.tsx (its terminal branch is unreachable in Dispatch — now labelled as the guard it is), undoClose.ts, DispatchLayout.tsx, and two stale docs.

Tests and verification

The first revision's tests were worthless and review proved it by running them with the modules aliased to main: they hand-built the detached record and asserted buildDispatchGroups' concatenation, so they passed identically against unfixed code and could never have caught the grid branch returning.

They are replaced with specs that drive splitFocused itself. Each was confirmed to fail on main (verified in a throwaway main worktree — expected [ 'a1', 'aTerm' ] to deeply equal [ 'a1' ], expected null to match object { type: 'detached' }):

1. Ordering — ⌥T in Dispatch leaves tab.root untouched, files a detached record, terminal lands last.
2. Lane placement — the terminal occupies the focused lane, lane 0 untouched.
3. Normal mode untouched — ⌥T outside Dispatch still splits the grid.
4. Dispatch: new project terminal uses stale active tab instead of focused lane #366 with a detached lane session — restores coverage the deleted resolver's test owned and nothing replaced; without it a ⌥T beside a worktree agent could silently spawn in the parent repo.
5. Undo-close — entry captured with tmuxName; undo respawns with recoverTmuxName and re-files at the old detachedAt; a dead project tab is stale rather than stranding a backend.

The usePaneActions setup is extracted to a shared harness whose mock spawn registers SessionMeta the way the real one does — without that, selectors filtering on state.sessions drop the new session and placement assertions pass against a session that never appeared.

Ran: tsc -b tsconfig.node.json + tsc -p tsconfig.web.json --noEmit — clean on both. NODE_ENV=development npx vitest run — 2030 passed, 294 files, one pre-existing unrelated failure (imageAttachment.test.ts corpus census, open issue #669: cites a deleted personal ~/.claude transcript).

Known limitations

• A Dispatch terminal hibernates across restart like any detached session — rehydrate deliberately does not respawn them, so its shell re-attaches to tmux when its lane first renders rather than at launch. Reviewed end-to-end through main (reconcile builds its persisted list from every kind === 'terminal' row regardless of grid/detached, so a hibernated terminal is not reaped): no scrollback loss, no second shell. Verified by source inspection only — the app was not launched.
• paneLabelForSession indices shift for a tab containing a Dispatch terminal, because resolveTabSessions also orders grid-then-detached. Same coordinate the Dispatch list shows, so the two stay in agreement.
• A terminal created in normal grid mode still sorts above older detached agents. Out of scope for bug(dispatch): terminals created from Dispatch pin to the top of the session list instead of the natural flow #671 (which is about Dispatch-created terminals); the complete fix is one unified creation timestamp across grid and detached, which is a larger change.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KuvoZtYUJiGPe29KAkP94A

[Juliusolsson05]

Review findings resolved

The independent review of this branch completed at 14:36 the day after its coordinating session died, so its findings were never collected. Recovered from the transcript on disk and resolved here.

F1 (blocker) — undo restored an invisible session. restoreDetachedEntry never set activeTabId, while every other detached-filing path does (splitFocused's Dispatch branch, createDetachedDispatchAgent, restoreTabEntry). Since buildDispatchGroups filters sourceTabs to activeTabId outside global scope, undoing a row belonging to a different project tab spawned a live backend that rendered nowhere — filed correctly, filtered out of the list, and the focus set here was immediately overwritten by ClassicDispatchLayout's focus effect. No toast on this path, so undo appeared to do nothing while a provider process or a re-attached tmux session ran invisibly.

F2/F3 — bulk closes ate the undo history. The stack is a 10-entry LIFO and every detached close captured one, so a single "Close Old Agents" purge or orchestration run close could flush out the pane the user closed by mistake — and ⌘⇧T would then resurrect an agent they had deliberately cleared. Cascades were worse: closeLinkedChildren runs before the parent's entry is pushed, so a parent with two children left three entries; undo restored the parent under a new id and the children then returned carrying the old linkedParentId — un-nested, no longer cascading, writing a dead id into workspace.json that nothing scrubs.

CloseSessionOptions grows captureUndo, defaulting to capture. Close Old Agents, closeOrchestrationRun, and cascade children opt out. Single closes — including closeOrchestrationAgent, which is one deliberate act at human scale — still capture.

F4 — carry orchestrationBootstrapPromptDelivered through restore; its own doc says it must survive with the child, and spawn never sets it.

F5 — guard the new bail's killSession like restorePaneEntry does. It reaches an IPC invoke that can reject, and the bail runs with the entry already popped, so a throw lost the entry, skipped bumpUndoCloseVersion, and escaped into the keybinding handler.

F6 — drop the three parameters useDispatchActions kept after findTerminalInLatestTab and pendingTerminalByTabRef were deleted.

On the reviewer's own critique

They proved this PR's first test suite passed against main, so the F1 regression was checked the same way: it fails without the fix with expected 'tabB' to be 'tabA'. It asserts visibility through buildVisibleDispatchRows rather than the activeTabId field, because the visible row is the contract and the field is only the mechanism. The previous fixture had a single tab, which is exactly why this could not surface.

One existing test legitimately changed: orchestrationClose.test.ts pins the options object passed per child, and now has to state captureUndo: false — kept as an exact-object assertion so a future change to that opt-out has to be re-stated deliberately.

Also merged current main (three merges ahead), no conflicts.

Verification: typecheck clean both projects; full suite 2096/2097, the sole failure being the pre-existing #669 corpus fixture.