Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

Merge remote-tracking branch 'origin/main' into fix/triage-780-20260923

review0f17a9129344
diff --cc .github/workflows/ci.yml
index f954e3311,82a617967..0f48de70e
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@@ -71,4 -71,4 +71,4 @@@ jobs
run: npm run host:build
- name: Windows-relevant tests
- run: npx vitest run src/core/settled-text.test.ts src/core/native-windows-pane.test.ts src/core/fs-atomic.test.ts src/core/fs-atomic.guard.test.ts src/core/exec-path.test.ts src/core/claude-cli.test.ts src/core/codex-identity-caps.test.ts src/core/codex-cli.test.ts src/core/grok-cli.test.ts src/core/commit-message.test.ts src/core/context-link.windows.test.ts src/core/git-service.windows.test.ts src/core/usage/codex-usage.windows.test.ts src/session-host/ src/core/session-host-client.test.ts src/core/session-host-launch-ledger.test.ts src/core/session-host-client-startup-wait.test.ts src/core/agent-launch.test.ts src/core/pty-session-host.test.ts src/main/bootstrap-windows.test.ts src/main/media-protocol.test.ts src/main/remote-atomic-write.test.ts src/main/ssh-fs.test.ts src/main/remote-ssh/ssh-project.test.ts src/renderer/terminal/file-links.test.ts src/renderer/terminal/file-links.windows.test.ts src/renderer/terminal/file-link-dialect.test.ts src/renderer/terminal/host-platform.test.ts src/main/pairing-service.windows.test.ts src/main/windows-ssh-keys.test.ts src/shared/pairing-gate.test.ts src/renderer/components/settings/sections/PhoneSection.windows.test.tsx
- run: npx vitest run src/core/phone-approval.test.ts src/main/remote/standing-host.test.ts src/main/remote/approved-devices.test.ts src/renderer/lib/phone-approval.test.ts src/core/fs-atomic.test.ts src/core/fs-atomic.guard.test.ts src/core/exec-path.test.ts src/core/claude-cli.test.ts src/core/codex-identity-caps.test.ts src/core/codex-cli.test.ts src/core/grok-cli.test.ts src/core/commit-message.test.ts src/core/context-link.windows.test.ts src/core/git-service.windows.test.ts src/core/usage/codex-usage.windows.test.ts src/session-host/ src/core/session-host-client.test.ts src/core/session-host-launch-ledger.test.ts src/core/session-host-client-startup-wait.test.ts src/core/agent-launch.test.ts src/core/pty-session-host.test.ts src/main/bootstrap-windows.test.ts src/main/media-protocol.test.ts src/main/remote-atomic-write.test.ts src/main/ssh-fs.test.ts src/main/remote-ssh/ssh-project.test.ts src/renderer/terminal/file-links.test.ts src/renderer/terminal/file-links.windows.test.ts src/renderer/terminal/file-link-dialect.test.ts src/renderer/terminal/host-platform.test.ts src/main/pairing-service.windows.test.ts src/main/windows-ssh-keys.test.ts src/shared/pairing-gate.test.ts src/renderer/components/settings/sections/PhoneSection.windows.test.tsx scripts/windows-update-preflight.test.ts
++ run: npx vitest run src/core/settled-text.test.ts src/core/native-windows-pane.test.ts src/core/phone-approval.test.ts src/main/remote/standing-host.test.ts src/main/remote/approved-devices.test.ts src/renderer/lib/phone-approval.test.ts src/core/fs-atomic.test.ts src/core/fs-atomic.guard.test.ts src/core/exec-path.test.ts src/core/claude-cli.test.ts src/core/codex-identity-caps.test.ts src/core/codex-cli.test.ts src/core/grok-cli.test.ts src/core/commit-message.test.ts src/core/context-link.windows.test.ts src/core/git-service.windows.test.ts src/core/usage/codex-usage.windows.test.ts src/session-host/ src/core/session-host-client.test.ts src/core/session-host-launch-ledger.test.ts src/core/session-host-client-startup-wait.test.ts src/core/agent-launch.test.ts src/core/pty-session-host.test.ts src/main/bootstrap-windows.test.ts src/main/media-protocol.test.ts src/main/remote-atomic-write.test.ts src/main/ssh-fs.test.ts src/main/remote-ssh/ssh-project.test.ts src/renderer/terminal/file-links.test.ts src/renderer/terminal/file-links.windows.test.ts src/renderer/terminal/file-link-dialect.test.ts src/renderer/terminal/host-platform.test.ts src/main/pairing-service.windows.test.ts src/main/windows-ssh-keys.test.ts src/shared/pairing-gate.test.ts src/renderer/components/settings/sections/PhoneSection.windows.test.tsx scripts/windows-update-preflight.test.ts
diff --cc CLAUDE.md
index 95981c5b7,81b4bd1be..56e133734
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@@ -604,27 -567,15 +604,23 @@@ Lifecycle, by intent
identical call kills it and everything under it — an agent CLI mid-turn included. Issue #126: a
project switch terminated a working Claude agent, which then auto-resumed from wherever the kill
landed. The predicate is deliberately the narrowest one that closes it — a tmux-backed session is
- never protected (the kill costs a redraw), and neither is a plain terminal, a finished agent or
- an unknown state (nothing is running to lose). **A fifth lever owes the same gate.**
+ never protected (the kill costs a redraw), and neither is a plain terminal. **An IDLE agent CLI on
+ a non-persistent pty IS protected** (`agentProcess`, `agentProcessInPane`; not once hibernated,
+ paused, dropped, or once its CLI announced a SessionEnd, `sessionEnded`, which is its own
+ transient flag because `state: undefined` alone is also what an idle agent looks like): killing it looked free because cold restore `--resume`s it on revive, but the
+ resumed CLI fires `SessionStart:resume` and idles with no further hook event, the status mirror
+ leaves it unverified, and agent messaging refused it for as long as it stayed idle — measured
+ 2026-09-13 on Windows native ptys. The mirror now also lets a verified `idle_prompt` right after a
+ verified `SessionStart` commit a verified non-inferred `done` (`MirrorEntry.sessionStarted`), and
+ the decider reports a proven node reset by a boundary as `targetNotIdleUnknown`, not
+ `targetStatusStale`. **A fifth lever owes the same gate.**
- The fifth is the offscreen release of an ARMED node (`--after`, `shouldDeferReleaseForHeldLaunch`,
- 2026-09-02): the held launch is delivered by session NAME, so with tmux underneath the release is
- harmless and the node stays `sessionReady` (the teardown keeps the flag for an offscreen release
- of a tmux-backed session); on the plain-shell fallback the release would destroy the very pane
- the launch is typed into, so it is deferred while armed. MEASURED before the fix: a released
- QUEUED node held its launch through its dependency going `done`, the badge claimed the terminal
- "has not started yet", and only a camera travel (revive) ever fired it — "the chain works when I
- look at it" was this.
+ The fifth is the offscreen release of an ARMED node (`shouldDeferReleaseForHeldLaunch`):
+ held launches now require the attached transport for echo verification, on every backend.
+ Keep that transport until delivery or recovery; a blind paste by session name loses the
+ shell-init repair and canonical-line protections.
- **Node unmount (project switch)** → the RENDERER **parks** the terminal (`TerminalNode.tsx`
`parkedTerminals`): the xterm instance + its attached PTY stay alive with the `.xterm` element
- detached from the DOM, so a remount within `TERM_PARK_MS` (5 min) re-adopts them — instant, and
+ detached from the DOM, so a remount within the park window re-adopts them — instant, and
exact (the tmux client never detaches, so mouse-tracking/alternate-screen modes and scrollback
carry over; do NOT "optimize" this into a respawn+redraw — a fresh xterm on a reused client
misses the attach-time mode sequences and breaks scrolling). The park timer then runs the real
diff --cc CONTRIBUTING.md
index 29b242d42,30a0f9faf..a2c731359
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@@ -56,21 -56,28 +56,43 @@@ handler needs something only Electron h
**injected dep** whose absence is a documented degrade — see `registerTranscriptIpc` /
`registerContextEnsureIpc` — rather than a reason to keep the whole handler in `src/main`.
+**Windows agent messaging:** direct ConPTY terminals are looked up by the runtime node index,
+not the persistence key. `NativeWindowsPane` checks console membership, the unambiguous native
+process chain and process birth times, and frames paste only after the terminal requested it.
+Do not replace that read with a stored `agentId` or the restart heuristic's deepest descendant.
+An interpreter such as `node` is named by its script's package `bin` entry, never as `node`, so
+npm-installed CLIs such as Codex are recognized. A session released by park expiry or offscreen
+release is still messageable: existence and routing ask the backend, not the attached client.
+Never put the submitting Enter in the same write as a message paste: `core/settled-submit.ts`
+pastes, waits for the envelope to render, then submits separately, on every backend.
+The persistent session-host transport has its own versioned messaging extension: the host checks
+its session generation, OS process identity and emulator before writing. An older live host keeps
+its terminals and refuses the extension; never restart it automatically or fall back to sendKeys.
+Message dispatch publishes pending canvas edits before main resolves scope, without overwriting
+an unresolved file conflict. See `docs/windows-session-host.md`.
+
+ Claude usage identity is scoped to the same config directory as its credentials. Read organization
+ metadata even when credentials already include an email, and degrade to the email-only row when
+ metadata cannot be read. Managed usage must never fall back to an unscoped system Keychain token:
+ that would label one account's limits with another account's organization.
+
+ Context-link maps authorize reads. Publish changes to edges, linked metadata, and background
+ projects independently of canvas geometry updates; a debounce reset by every node render can
+ starve publication indefinitely. Only merge projects owned by the same core, and use the rendered
+ canvas's project epoch during tab switches. Core must revoke removed links before asynchronous
+ transcript discovery or debug-file writes finish; an older write must never restore that access.
+ Coalesce renderer updates before building the workspace map, without resetting the scheduled task.
+ Intermediate publications retain resolved transcript paths only for unchanged identities; changing
+ a session/account/location/hook path or removing the target invalidates that cache immediately.
+
+ Windows installer safety (#829): `build/installer.nsh` overrides NSIS's process-killing check.
+ A running app or session host blocks install/uninstall, and a failed process query blocks too.
+ Never restore automatic host termination: quitting the app preserves those live sessions.
+ Update preparation must keep saved canvas nodes: exit programs normally, quit, then have the user
+ verify and stop any remaining host. Never recommend **End session** (it deletes nodes). Cold agent
+ resume depends on supported, saved conversation history; it does not preserve running tasks.
+ See `docs/windows-session-host.md` for the user-controlled preparation/recovery steps and limits.
+
## Three surfaces
A feature is not done until you have decided how it behaves on each — even if the decision is "not
@@@ -706,8 -824,56 +839,62 @@@ Two files, two audiences
invariant that only lives in a commit message is one refactor away from being violated by someone
who never saw it.
+**Windows text submission waits for the composer.** Use `core/settled-text.ts` for native PTY and
+session-host `sendText`: adjacent paste/Enter writes can be consumed in one read. The bounded
+screen check may leave text unsubmitted; a true result means text was accepted, not that a turn
+started. Never retry the paste just because no submit was observed. Collapsed or hidden pastes
+may need manual Enter; device testing remains necessary.
++
+ An unanswered Claude `AskUserQuestion` is correlated by session and tool-use ID in the core
+ mirror, independently of its short-lived display stash. Ordinary hooks, subagent activity and
+ unrelated transcript results must not clear attention or archive its inbox card. Both shells
+ use `recordQuestionResult` for transcript rescue (including Escape/decline), and broadcast the
+ mirror's effective event. Keep result IDs through local and SSH tails; a boolean “some tool
+ finished” is insufficient. Explicit new user turns, interrupts and session boundaries reset it.
+
+ Remote Codex account safety (#736): managed SSH Codex sessions and agent-less login terminals
+ require a known safe account id and a safe resolved remote home before spawning. The remote env
+ builder supplies their private `CODEX_HOME`; never fall back to the system login when that scope
+ is unavailable. System SSH Codex retains the host environment, including during early attach
+ before home discovery; never inject a guessed `HOME` or `CODEX_HOME`. Custom Codex harnesses use
+ the same guard. Desktop supports remote account lifecycle; the Server browser still explicitly
+ rejects managed Codex account management.
+
+ - Media URLs live for the app run. Remote cache pruning must keep files already handed to
+ players; the cache cap is soft until restart. Use the existing `video` node for audio too.
+ - Subagent reload replay is display-only and current-host-only. Never replay status/permission
+ events or treat a replayed card as verified process ownership; subscribe before taking its snapshot.
+
+ **Phone consent belongs to the verified handshake, not the browse socket.** A standing phone's
+ SAS request survives transport closure only until its 120-second deadline; approval requires the
+ issued id and displayed box key together. Keep request/reply outcomes distinct (stale request,
+ failed pin save, missing IPC response, saved-but-disconnected). All production pin/revoke writers
+ must use `updateApprovedDevices` for the whole read/modify/write, so concurrent updates cannot
+ lose approvals or resurrect revoked keys. Server Edition does not host this legacy relay path.
+
+ Managed Codex login terminals are agent-less: core identifies their provider from the saved
+ account list. Before opening one, await `useSettings.getState().flush()` after adding the account.
+ The normal 300 ms coalesced save is too late: an unknown id can launch against the system home.
+
+ Claude child `PreToolUse`/`PostToolUse`/`PostToolUseFailure` hooks must not drive parent state.
+ Child `PermissionRequest` and attention `Notification` hooks still reach needs-you and phone
+ approvals, including the raw approval summary and deterministic reply ticket. Keep raw summary
+ recording before the child transcript-association guard in both shells.
+
+ A held parent question can overlap child permissions: retain its question card and waiting
+ state while publishing each approval ticket separately. Approval replies resolve only their
+ own ticket; the picker stays pending until its correlated answer or explicit reset.
+ When the parent answers first, retain concurrent approval tickets and blocked attention until
+ their own replies; ordinary tool activity cannot settle them. Explicit turn/session resets
+ still cancel both kinds of pending attention.
+
+ Optional hook ownership failures must never stop Desktop window creation or Server boot. Use the
+ shared nonfatal startup path and surface its actionable diagnostic. A responding HTTP port is not
+ nodeterm identity: verify bearer acceptance and rejection. Legacy SSH endpoint migration requires
+ ownership proof, an unchanged-file check, and stdin-only credential transfer; a project name alone
+ is not permission to replace another installation's advertisement.
+
+ Held approval attention must not replace subagent, recurring or background-task events, or refresh
+ state evidence from those lifecycle hooks. A parent may ask several questions while a child ticket
+ is outstanding: track each new picker and preserve child approval cards independently, including
+ when their display titles match. Answering either resolves only that question or ticket.
diff --cc src/renderer/canvas/Canvas.tsx
index e633ecba7,f17188c19..a57691de1
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@@ -2773,9 -2793,34 +2795,34 @@@ export function Canvas()
const persist = useCallback(async () => {
commitActiveToStore()
- await writeDisk()
+ return await writeDisk()
}, [commitActiveToStore, writeDisk])
+ // Persist the attempt before a writer can send even its first byte. React Flow remains the
+ // live source: update its ref synchronously before serializing, not after an async setNodes.
+ useEffect(() => registerLaunchCommit(activeSession.api, async (nodeId, command, manual) => {
+ const projectId = useProjects.getState().activeProjectId
+ if (!canCommitCanvas(nodesProjectIdRef.current, projectId)) return 'deferred'
+ const node = nodesRef.current.find((n) => n.id === nodeId)
+ if (!node) return 'deferred'
+ return commitOwnedLaunchAttempt(activeSession.api, api, {
+ pending: node.data.pendingLaunch,
+ command,
+ manual,
+ update: (pendingLaunch) => {
+ const next = nodesRef.current.map((n) => n.id === nodeId
+ ? { ...n, data: { ...n.data, pendingLaunch } } : n)
+ nodesRef.current = next
+ setNodes(next)
+ markDirty()
+ commitActiveToStore()
+ },
+ save: async () => {
+ await api.workspace.save(useProjects.getState().toWorkspace())
+ }
+ })
+ }), [activeSession.api, api, commitActiveToStore, markDirty, setNodes])
+
// Global kanban reads ALL lanes from serialized `p.nodes`, but the active project's
// live React Flow nodes may have uncommitted edits (title rename, new node). Commit
// before the board mounts so the active lane matches the canvas — the other lanes are