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 branch 'main' into fix/issue-569-queued-launch

enes7f8a49c90223
diff --cc CLAUDE.md
index 9464a77b9,57fb90429..5d91d5344
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@@ -1379,37 -1450,6 +1452,38 @@@ else, and its context links must keep c
Pure logic + refusal matrix in `renderer/lib/pendingLaunch.ts` (unit-tested); the dashed dep→node
edges are **derived, never persisted** (a pending dependency is a state that ends when the launch
fires — the durable relation is the context bridge `--after` also draws).
+ **(7) Delivery waits for the node's PTY, and never fails silently** (issue #569 item 1, 2026-09).
+ A satisfied dependency says nothing about whether there is a terminal to type into, and the
+ original loop conflated the two: a flat 5 × 400 ms budget started when the CANVAS held the node
+ and was spent on loading the canvas, mounting it and spawning tmux — so on a cold project switch
+ the launch was abandoned before its session existed, in a `console.warn`, and the node read
+ QUEUED forever with only the manual ▶ left. `TerminalNode` therefore publishes a **session-ready**
+ signal (`isSessionReady` / `subscribeSessionReady`, module-level like `offscreenNodes`): true for
+ an ADOPTED park (already typeable, and its create continuation ran on a previous mount) and, for
+ a fresh spawn, at the SAME `whenShellSettled` moment `writeWhenShellReady` delivers an
+ `initialCommand` — both write a CLI command line, and a line delivered across zsh's rc-file tty
+ flush comes out mangled. A **park keeps it** (a parked tmux session is still addressable by name);
+ only a real teardown clears it. The loop then WAITS instead of burning attempts, and the backoff
+ (`launchRetryDelay`, ~12 s over five attempts) covers only the residual race after readiness.
+ Because a wait with no end is the failure mode this replaces, both give-up states are **visible**
+ in the transient `state/launchDelivery.ts` and rendered by the QUEUED badge's amber ⚠ + tooltip
+ (`launchTooltip`, pure): `stalled` = gate open, no terminal yet, **still held** (raised by a
+ `LAUNCH_STALL_MS` timer with a fire-time re-ask; the launch still fires whenever the session
+ finally comes up — an SSH host reconnecting takes this path) and `failed` = the session came up
+ and refused every attempt, so nothing will retry it. Neither is ever inferred from silence, and
+ the tooltip names no cause it did not measure (the node's own overlay owns the diagnosis).
+ The open verbs' replies carry the same fact for callers OUTSIDE the app: `result.queued` +
+ `result.queuedIds` on `open-terminal`/`open-claude`/`open-agent`, always true for the
+ `--project` cold-open branch — an orchestrator was previously told "opened" either way and
+ routed work to a session that did not exist. Agent-facing copy is generated in
+ `canvas-control-core.ts` and pinned in its test, per the sync rule above.
+ **(8) An armed node must not cold-start its own agent** (found while fixing (7)). The mount-time
- cold-restore relaunch (`fresh && agentId && canResume(...)`) is now also gated on
- `!data.pendingLaunch`: a first open is `fresh` by definition, so every `--after` / `verify` node
++ cold-restore relaunch (`fresh && agentId && canResume(...)`) carries a second, independent
++ refusal beside the `paused` one (`shouldColdResume`): `!data.pendingLaunch`. A first open is
++ `fresh` by definition, so every `--after` / `verify` node
+ was launching a bare CLI on mount — the session the hold exists to prevent — and the held launch
+ then arrived as TEXT typed into it rather than as the command it is. The delivery race used to
+ mask it; gating delivery on the shell settling would have made it deterministic.
**Review panel (`verify`, 2026-07):** `verify --node <id> [--lenses …] [--focus …] [--agent …]
[--synthesis off]` opens one reviewer per LENS, each armed behind the target (`--after`) and
bridged to it, wrapped in a `Verify: <title>` group, plus a judge armed behind the whole panel.
diff --cc src/renderer/canvas/Canvas.tsx
index 261f405ce,b62976209..465aaf199
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@@ -391,19 -398,15 +401,22 @@@ import
type RelayTab,
} from '../session/relay-tab'
import { buildBackgroundLinkMaps, buildContextLinkNote, buildLinkMap, buildNotePushMessage, classifyLink, hiddenLinkIds, linkIdsCoveredByRopes, pairKey, planBridges, type LinkEndpoint } from '../lib/noteLink'
-import { dependencyEdges, launchesToFire, unmetDeps, type ArmedNode } from '../lib/pendingLaunch'
+import {
+ dependencyEdges,
+ launchesToFire,
+ launchRetryDelay,
+ unmetDeps,
+ LAUNCH_STALL_MS,
+ type ArmedNode
+} from '../lib/pendingLaunch'
+ import { triggerEdges } from '../lib/triggerCard'
import { freeSpot } from '../lib/placement'
import { pushSessionRename } from '../lib/sessionRename'
- import { useReopenHistory } from '../state/reopenHistory'
+ import { useReopenHistory, type ReopenEntry } from '../state/reopenHistory'
import { snapshotNode, recreateNodeFromSnapshot } from '../lib/reopenNode'
- import { planReopen } from '../lib/reopenPlan'
+ import { buildClosedSessionEntries, stateToReopenSnapshot } from '../lib/closedHistory'
+ import { uuid } from '../lib/uuid'
+ import { planReopen, type ReopenPlan } from '../lib/reopenPlan'
import { oneLine } from '@shared/one-line'
import { parseLenses, verifyLensPrompt, verifySynthesisPrompt } from '../lib/verifyPanel'
import { useSettings } from '../state/settings'
diff --cc src/renderer/nodes/TerminalNode.tsx
index 0012d4496,f6fdce20b..651da8ba5
--- a/src/renderer/nodes/TerminalNode.tsx
+++ b/src/renderer/nodes/TerminalNode.tsx
@@@ -3145,7 -3098,7 +3169,13 @@@ export function TerminalNode(
if (data.initialCommand) {
writeWhenShellReady(data.initialCommand)
updateNodeData(id, { initialCommand: undefined })
- } else if (fresh && agentId && canResume(agentId) && !data.pendingLaunch) {
- } else if (fresh && agentId && canResume(agentId) && shouldColdResume(pausedNow)) {
++ } else if (
++ fresh &&
++ agentId &&
++ canResume(agentId) &&
++ !data.pendingLaunch &&
++ shouldColdResume(pausedNow)
++ ) {
// Cold restart of an agent node: the live agent is gone, so re-launch it. Resume the
// prior conversation by its session id when we have one; otherwise start the agent
// fresh. Plain terminals get nothing here — just the restored shell.
diff --cc src/renderer/nodes/session-ready-signal.test.ts
index 5c6b9ad8c,000000000..84afa1abb
mode 100644,000000..100644
--- a/src/renderer/nodes/session-ready-signal.test.ts
+++ b/src/renderer/nodes/session-ready-signal.test.ts
@@@ -1,81 -1,0 +1,84 @@@
+// @vitest-environment jsdom
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { isSessionReady, subscribeSessionReady } from './TerminalNode'
+
+/**
+ * Issue #569 item 1 — the PTY-ready signal Canvas's armed-launch loop waits on.
+ *
+ * TerminalNode is impractical to mount in jsdom (xterm, a live PTY, dozens of stores), so the
+ * exported CONTRACT is exercised directly and the publish/clear sites are pinned as source
+ * tripwires — the same split `status-lifecycle.test.ts` uses.
+ */
+const src = readFileSync(join(__dirname, 'TerminalNode.tsx'), 'utf8')
+
+describe('the session-ready registry contract', () => {
+ it('an unknown node is NOT ready — the safe direction holds the launch instead of burning it', () => {
+ expect(isSessionReady('term-never-seen')).toBe(false)
+ })
+
+ it('a subscriber can be added and removed without the module retaining it', () => {
+ const seen: string[] = []
+ const off = subscribeSessionReady((id) => seen.push(id))
+ expect(typeof off).toBe('function')
+ off()
+ off() // idempotent: a double-unsubscribe on unmount must not throw
+ expect(seen).toEqual([])
+ })
+})
+
+describe('where readiness is published (source pins)', () => {
+ it('an ADOPTED (parked) terminal is ready immediately; a fresh one starts not-ready', () => {
+ // The park→remount path returns before `create()` and would otherwise never publish, leaving
+ // an armed node waiting on a session that has been live the whole time.
+ expect(src).toContain('setSessionReady(id, !!parked)')
+ })
+
+ it('a fresh session is published through the SAME shell settle the initialCommand writer uses', () => {
+ // Both write an agent CLI command line into the pane. A line delivered across zsh's rc-file
+ // tty flush comes out mangled, which is exactly what `whenShellSettled` exists to avoid — so
+ // the armed launch must not be released on a bare create-resolve.
+ expect(src).toContain('whenShellSettled(() => setSessionReady(id, true))')
+ expect(src).toContain('const writeWhenShellReady = (cmd: string): void => {')
+ expect(src).toMatch(/whenShellSettled\(\(\) => \{[\s\S]{0,400}?deliverCommand\(/)
+ })
+
+ it('only a REAL teardown clears it — a park keeps the session typeable by name', () => {
+ // The park branch returns before this line; a parked tmux session is still addressable by
+ // `sendText`, so clearing there would strand a launch that could have been delivered.
+ expect(src).toMatch(/life\.dead = true[\s\S]{0,600}?setSessionReady\(id, false\)/)
+ // Exactly three publish sites: mount (adopt-or-not), settle, teardown. A fourth means
+ // somebody has taught another path to claim readiness it cannot vouch for.
+ expect(src.match(/setSessionReady\(/g)?.length).toBe(4) // 3 call sites + the definition
+ })
+})
+
+describe('an ARMED node does not cold-start its agent under the hold (source pins)', () => {
+ it('the cold-restore relaunch is gated on there being no pendingLaunch', () => {
+ // A first open is `fresh` by definition, so without this every `--after` / `verify` node
+ // launched a bare CLI on mount — and Canvas's held launch then arrived as TEXT typed into
+ // the session the hold existed to prevent.
- expect(src).toContain('fresh && agentId && canResume(agentId) && !data.pendingLaunch')
++ // Matched inside the condition rather than as one literal line: the branch also carries the
++ // `paused` gate (shouldColdResume), and the two guards are independent refusals that must
++ // both survive a reformat.
++ expect(src).toMatch(/fresh &&\s*\n?\s*agentId &&\s*\n?\s*canResume\(agentId\) &&\s*\n?\s*!data\.pendingLaunch/)
+ })
+})
+
+describe('the QUEUED badge carries the delivery state (source pins)', () => {
+ it('the badge reads the store and renders the warning variant plus the shared tooltip', () => {
+ expect(src).toContain("useLaunchDelivery((s) => s.byId[id])")
+ expect(src).toContain('term-node__status--queued-warn')
+ expect(src).toContain('launchTooltip(launchDelivery, pendingWaitingOn, pendingLaunch.command)')
+ })
+
+ it('the manual ▶ disarms only on a delivery that landed', () => {
+ // Dropping `pendingLaunch` unconditionally threw the command away whenever the session was
+ // not up — precisely the state a user reaches for this button in.
+ expect(src).toMatch(
+ /pty\.sendText\(id, pendingLaunch\.command\)\.then\(\(ok\) => \{[\s\S]{0,600}?if \(ok\)[\s\S]{0,300}?pendingLaunch: undefined/
+ )
+ expect(src).toMatch(/else \{[\s\S]{0,200}?markFailed\(id, 1\)/)
+ })
+})