[Juliusolsson05]

Problem

Plain terminal panes are first-class sessions structurally: grid leaves, Dispatch rows, command targets, operator workspace.observe entries, tmux-persistent across restarts. But about 40 checks asked "is this an agent?" (isAgentProviderKind) when they meant "is this a session the user manages". So a shell could not be titled, named, pinned, jumped to by its pane label, auto-followed, inspected in Agent Status, or seen as busy. Its header was a hand-drawn terminal $ strip older than every header feature since April (folder, color flag, title/name row, Status Mode). Shells also had no activity signal at all: they only ever emitted started, data and exit.

Prompt templates and the Key Vault already reached terminals (#830 / #831 via #840). This PR finishes the job for both kinds of terminal:

• plain shells (SessionKind 'terminal', TerminalLeaf);
• agents shown in the raw terminal view (AgentTerminalLeaf).

It also closes a remote-phone leak (#866) and the terminal-view related-agent gap (#858).

What changed

Session features for every session kind (the terminal exclusions are deleted, not generalized):

• Titles: "Set Title…" (id agent.title.set unchanged) and the operator's agents.titleSet.
• Spoken names, from the same pool and under the same setting, with the name-row height reservation so a late name never SIGWINCHes a TUI running in the shell.
• Pins: "Pin Sessions…" / "Unpin Session", ids unchanged.
• Jump by pane label: "Go to A2" / A2! now reaches terminals, and the palette copy names a terminal correctly.
• Lists and panels: Agent Status panel, Close Old Agents, the Activity modal (including Bury), and the Worktrees panel.
• Operator: agents.locate/show/close/restore/list/titleSet/pinSet and agents.search (whose provider filter now accepts terminal) all accept terminals. agents.prompt refuses a terminal before any wake or write, and points to terminals.input.

One header:

• TerminalLeaf renders the shared PaneHeader, like AgentTerminalLeaf since fix(workspace): light the status header for terminal-view agent panes #853: live folder (follows cd through tmux), color flag, title/name row, Status Mode fill, TAIL pill, and the foreground command as the badge.
• Plain terminals get data-pane-id and auto-follow / Jump to Latest / Auto-follow All through the shared useTerminalFollow hook (renamed from useAgentTerminalFollow).

Shell activity:

• A new main-process TerminalForegroundMonitor reads each terminal's foreground command. tmux-backed terminals use one tmux list-panes -a per second for all managed sessions (active pane of the active window); direct PTYs use node-pty's process.
• It emits only on change, on a dedicated session:terminal-foreground channel.
• The renderer folds this into the existing processActive / activityStatus inputs. Status Mode, tab running counts, the "still working" close confirmation and the Dispatch subtitle (shell running · npm) therefore light for shells with no terminal-specific code downstream.
• A finished command marks the session unread (NEW). After restore, a per-window snapshot keeps busy shells lit across a renderer reload.

Naming: one sessionDisplayTitle rule. An untitled session is named by its live folder, then its spawn folder, never by its raw session UUID (which the close dialog used to show). A terminal's Dispatch row follows cd. Shell rows show NEW and ERROR.

Terminal view (#858): the one-line status row names the related agent being displayed (raw codex · orchestration worker-2), and a parent button returns to the owner. No chip row is added, so the TUI is never resized by this.

Small fixes found during research:

• Dispatch's "New Agent…" picker offers Terminal and files it on the clicked project.
• "Undo Clear Composer" is hidden on shells.
• Copy Last Response, View Prompts and Reader no longer appear (and silently do nothing) on OpenCode Terminal, via a shared sessionHasTranscript predicate.
• The template fill pane shows "Pastes at the terminal cursor…" instead of Replace/Append radios for terminal targets.
• Stale comments corrected.

Remote phone (#866):

• SessionFeedSource drops any frame whose session is a terminal at its single emit choke point. The check also consults the spawn-time kind, so the pre-registration starting readiness frame is covered.
• RemoteServer refuses submit, interrupt and permission-reply for non-agent sessions.
• A paired phone can no longer learn terminal session ids or press Enter or Esc in a shell.

Design decisions and tradeoffs

• Deliberately reverses feat(workspace): add persistent agent titles #660 ("plain shell terminals are intentionally out of scope"), feat(workspace): give agents stable voice-friendly names #836 ("Terminals are never named") and the Add terminal sessions to Dispatch Mode #152 v1 pin deferral. A title, a name, a pin and a header are session metadata. The operator gained terminals.input in feat(control): expose external MCP through an isolated capability SDK #793, so a named shell is routable.
• Stays agent-only (D2): prompt delivery (deliverPromptToAgent is untouched), transcript features, composer features, Reader Mode (now guarded at the action level too), and the remote phone.
• Activity uses a dedicated channel, not process-state, because the remote tap and the session recorder subscribe to process-state and must never see terminal state. The poll has an in-flight guard, a 2 s tmux timeout, and runs only while terminals exist.
• "Running" means a foreground process other than the shell. A dev server or vim keeps its pane lit, which is literally true and makes the close confirmation useful. Commands shorter than one poll interval are never seen as busy.
• TerminalLeaf keeps its no-re-render-per-chunk contract: only primitive store selectors. Dispatch rows select activityStatus only for terminal rows, so Codex's per-second working… 12s tick does not re-render agent rows.
• Command ids are unchanged (they key saved keybindings and visibility); only titles changed.

Tests

Tests sit next to the modules they protect. Tests that asserted the old exclusions were rewritten, each with the reason. Added or extended:

• terminalForeground.test.ts: classifier, track/untrack lifecycle, in-flight guard, tmux failure keeps state, direct PTYs not blocked by a pending listing.
• TmuxRegistry.test.ts: listing parser, prefix filter, active pane of the active window, paths containing tabs.
• session-runtime/terminalForeground.test.ts and useTerminalForeground.renderer.test.tsx: running/NEW semantics, snapshot waits for restore.
• TerminalLeaf.header.renderer.test.tsx: shared header, data-pane-id, command badge, Status Mode, live cwd, color flag, title row, TAIL.
• AgentTerminalLeaf.related.renderer.test.tsx: bug(workspace): terminal view hides which related agent a pane is showing #858.
• sessionDisplayTitle.test.ts, rowTitle.test.ts, closeConfirmation.test.ts.
• Pins, labels and navigation: dispatchSelectors.test.ts, paneLabels.test.ts, agentIndexNavigation.test.ts (grid, tiled-Dispatch lane, detached swap), agentIndexCommand.test.ts.
• Lists: CloseOldAgentsModal.rows.renderer.test.ts, agentStatusModel.renderer.test.ts, loadWorktreeDump.test.ts.
• agents.renderer.test.ts: terminal metadata and navigation accepted, prompt refused, show refused while Reader owns the screen.
• transcriptAvailability.test.ts, PromptTemplateFillPane.renderer.test.tsx, NewAgentPlacementOverlay.renderer.test.tsx.
• SessionFeedSource.test.ts (including the pre-registration window) and RemoteServer.integration.test.ts (submit, interrupt and permission-reply refused for terminals).
• useIpcSubscriptions.renderer.test.tsx: terminalForeground cleared on exit.

There is no SessionManager-level wiring test: it would need a real node-pty spawn, which this suite does not do. The monitor, classifier and parser carry the behavior.

Verification

Run on Node 24.14.1 at the final head:

• npm run test:contract: pass

• npm run check:keybindings: pass

• npm run typecheck: pass

• npm test: 3113 passed, 2 failed. Both are known local-only environment failures, in areas this branch does not touch:

  • imageAttachment.test.ts cites a Claude session file that was deleted from this machine;
  • store.test.ts's prompt-template migration test times out at 5 s under full-suite load and passes 8/8 on its own.

  CI's quality-gate is the authoritative run.

Process: each of the 13 implementation tasks had an independent spec and quality review; Tasks 8 and 10 each needed one fix round. An Opus whole-branch review found three important and nine minor findings. One fix wave addressed them, and a scoped Opus re-review confirmed every item.

Known limitations and follow-ups

• OpenCode Terminal still never shows "running" (bug(opencode): OpenCode Terminal runtime sessions never report running #857). It needs spinner detection in opencode-headless, because its foreground process is always opencode.
• A terminal's "last active" is stamped renderer-side. It resets on reload or restart, and is cleared when the shell exits. This fails safe: idle shells look fresh and are never wrongly closed by Close Old Agents.
• Auto-follow All Visible now also pins plain terminals. They cannot be scrolled up while it is on; previously they were never affected.
• The Worktrees panel matches shells by spawn cwd, not the live tmux cwd.
• Follow-up: reader.ts setReaderModeTarget / toggleReaderMode still check isAgentProviderKind rather than sessionHasTranscript, so OpenCode Terminal can still open an empty Reader by keybind. This predates the branch.
• Follow-up: an agent spawn that fails before registration leaves its starting readiness frame in the remote late-joiner cache. This predates the branch; it is the same class as bug(remote): remote clients can act on terminal sessions the phone is never shown #866 but for agents.

Needs a live check (the app was not launched during this work)

• Status Mode lights while npm test runs in a tmux terminal and clears when it finishes. The Dispatch row shows shell running · node and then NEW.
• A busy shell stays lit across Cmd+R.
• Set a title, pin, and "Go to A2" on a plain terminal.
• With a paired phone: terminals never appear, and no terminal id shows up in any frame.

Fixes #865
Fixes #866
Fixes #858
Refs #857 #851 #853 #830 #831 #816 #660 #152 #793

🤖 Generated with Claude Code

https://claude.ai/code/session_01LEwGeHkkhnDxU3X3chXX3F