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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
feat(canvas): STARTING state — Run now is disabled while a headless start runs (#925)
review42461f359a4d
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex 8552a5f2c..b6ee5f6b2 100644--- a/src/renderer/canvas/Canvas.tsx+++ b/src/renderer/canvas/Canvas.tsx@@ -483,6 +483,7 @@ import {} from '../session/relay-tab'import { buildContextLinkNote, buildNotePushMessage, classifyLink, hiddenLinkIds, linkIdsCoveredByRopes, pairKey, planBridges, type LinkEndpoint } from '../lib/noteLink'import {+ deliveriesToRetire,launchesToFire,queueControlLaunch,LAUNCH_STALL_MS,@@ -1967,13 +1968,12 @@ export function Canvas() {).filter((f) => !launchInFlight.current.has(f.id))// Anything we were reporting on that is no longer an armed node — delivered, run by hand with// ▶, or deleted — stops being reported. Timers go with it: a stall warning for a node that has- // already started is a lie with a countdown on it.+ // already started is a lie with a countdown on it. A headless start in flight is spared: its+ // node lives in ANOTHER project by design, and its orchestrator settles it (#925).const delivery = useLaunchDelivery.getState()- for (const id of Object.keys(delivery.byId)) {- if (!nodes.some((n) => n.id === id && n.data.pendingLaunch)) {- delivery.clear(id)- clearStallTimer(id)- }+ for (const id of deliveriesToRetire(delivery.byId, (id) => nodes.some((n) => n.id === id && n.data.pendingLaunch))) {+ delivery.clear(id)+ clearStallTimer(id)}for (const f of ready) {// THE gate this whole loop turns on. Every dependency is satisfied, but that says nothingdiff --git a/src/renderer/lib/controlRouting.test.ts b/src/renderer/lib/controlRouting.test.tsindex 7f06ec1c9..812473339 100644--- a/src/renderer/lib/controlRouting.test.ts+++ b/src/renderer/lib/controlRouting.test.ts@@ -449,3 +449,13 @@ it('lists held, failed and unconfirmed launches without claiming an agent is heaexpect(text).toContain('errored [terminal] — LAST TURN ERRORED')expect(text).not.toContain('RUNNING')})++it('lists a background start as STARTING, not as the failed launch its manualOnly claim would read as (#925)', () => {+ const rows = storedNodeListing(+ [{ id: 'bg', pendingLaunch: { command: 'claude', attempted: true, manualOnly: true } }],+ {},+ { bg: { kind: 'starting', since: 1 } }+ )+ expect(rows[0].launchState).toBe('starting')+ expect(controlListingText(rows)).toBe('bg [terminal] — STARTING')+})diff --git a/src/renderer/lib/controlRouting.ts b/src/renderer/lib/controlRouting.tsindex a0d2ad25a..6d327dbb0 100644--- a/src/renderer/lib/controlRouting.ts+++ b/src/renderer/lib/controlRouting.ts@@ -190,6 +190,7 @@ const launchLabels = {queued: 'QUEUED',failed: 'LAUNCH FAILED',stalled: 'QUEUED (terminal not ready)',+ starting: 'STARTING',dropped: 'DROPPED',working: 'WORKING',unconfirmed: 'AGENT STATUS UNCONFIRMED'diff --git a/src/renderer/lib/pendingLaunch.test.ts b/src/renderer/lib/pendingLaunch.test.tsindex 6b4924cd7..60c89b688 100644--- a/src/renderer/lib/pendingLaunch.test.ts+++ b/src/renderer/lib/pendingLaunch.test.ts@@ -3,6 +3,7 @@ import {launchesToFire,queueControlLaunch,controlLaunchState,+ deliveriesToRetire,launchTooltip,unmetDeps,LAUNCH_STALL_MS,@@ -217,6 +218,23 @@ describe('launchTooltip — the QUEUED badge never goes silent (#569 item 1)', (const t = launchTooltip({ kind: 'failed', attempts: 5, at: 1 }, 'Builder', cmd)expect(t).not.toContain('Waiting for Builder')})++ it('launchTooltip explains a background start (#925)', () => {+ expect(launchTooltip({ kind: 'starting', since: 0 }, '', 'claude', undefined, false)).toMatch(+ /starting in the background/i+ )+ })++ it('a background start outranks every other sentence — none of them may offer ▶ mid-start (#925)', () => {+ for (const t of [+ launchTooltip({ kind: 'starting', since: 0 }, 'Builder', cmd, 'Builder'),+ launchTooltip({ kind: 'starting', since: 0 }, 'Builder', cmd, undefined, true)+ ]) {+ expect(t).toMatch(/starting in the background/i)+ expect(t).not.toContain('▶')+ expect(t).not.toContain('Waiting for Builder')+ }+ })})@@ -255,6 +273,7 @@ describe('control opens retain an unacknowledged launch (#827/#811)', () => {expect(controlLaunchState(false, undefined, { state: 'working', dropped: true })).toBe('dropped')expect(controlLaunchState(true, { kind: 'failed', attempts: 5, at: 1 })).toBe('failed')expect(controlLaunchState(true, { kind: 'stalled', since: 1 })).toBe('stalled')+ expect(controlLaunchState(true, { kind: 'starting', since: 1 })).toBe('starting')})})@@ -272,6 +291,32 @@ it('an exhausted delivery stays held on rerender; a stalled terminal may still bexpect(launchesToFire([node], {}, live, undefined, { new: { kind: 'stalled', since: 1 } })).toEqual([{ id: 'new', command: 'echo new' }])})+it('a background start holds the canvas delivery too — core is typing into that pane (#925)', () => {+ // The headless claim normally makes the node manualOnly first; this is the guard for a live+ // copy that has not caught up with the claim yet, when the store already says `starting`.+ const node = armed('new', [])+ expect(launchesToFire([node], {}, new Set(['new']), undefined, { new: { kind: 'starting', since: 1 } })).toEqual([])+})++describe('deliveriesToRetire — the Canvas sweep (#925)', () => {+ const byId = {+ delivered: { kind: 'failed' as const, attempts: 1, at: 1 },+ elsewhere: { kind: 'stalled' as const, since: 1 },+ starting: { kind: 'starting' as const, since: 1 },+ armed: { kind: 'stalled' as const, since: 1 }+ }++ it('retires every record whose node is not an armed node on the active canvas', () => {+ expect(deliveriesToRetire(byId, (id) => id === 'armed')).toEqual(['delivered', 'elsewhere'])+ })++ it('never retires a start in flight: it runs for a node that is NOT on the active canvas', () => {+ // Dropping it would re-enable ▶ the moment the user switches to that project, because the+ // manualOnly claim alone reads as a failed launch.+ expect(deliveriesToRetire({ starting: byId.starting }, () => false)).toEqual([])+ })+})+it('a durable manual-only launch stays held after a reload and unrelated successful hooks', () => {const node = armed('new', [])node.data.pendingLaunch!.manualOnly = truediff --git a/src/renderer/lib/pendingLaunch.ts b/src/renderer/lib/pendingLaunch.tsindex 2102f4804..051dc6f14 100644--- a/src/renderer/lib/pendingLaunch.ts+++ b/src/renderer/lib/pendingLaunch.ts@@ -47,7 +47,7 @@ export function controlLaunchState(pending: boolean,delivery: LaunchDelivery | undefined,status?: { dropped?: boolean; state?: AgentState }-): 'queued' | 'stalled' | 'failed' | 'dropped' | 'working' | undefined {+): 'queued' | 'stalled' | 'failed' | 'starting' | 'dropped' | 'working' | undefined {if (pending) return delivery?.kind ?? 'queued'if (status?.dropped) return 'dropped'if (status?.state === 'working') return 'working'@@ -126,6 +126,10 @@ export function launchesToFire(const p = n.data.pendingLaunchif (!p || !p.command || p.manualOnly || p.executor === 'server') continueif (deliveries?.[n.id]?.kind === 'failed') continue+ // A headless start (#925) owns this pane and is typing the launch into it. Its claim makes the+ // node manualOnly, which the guard above already skips; this covers a live copy that has not+ // caught up with the claim yet while the store already says so.+ if (deliveries?.[n.id]?.kind === 'starting') continueif (p.awaitSetupGroup && !(setupDone?.(p.awaitSetupGroup) ?? true)) continueif (p.after.every((d) => depSatisfied(d, status, live))) out.push({ id: n.id, command: p.command })}@@ -160,9 +164,27 @@ export const LAUNCH_STALL_MS = 45_000export type LaunchDelivery =| { kind: 'stalled'; since: number }| { kind: 'failed'; attempts: number; at: number }+ /** A headless start (#925) is in flight: core owns the pane, so ▶ must not type into it. */+ | { kind: 'starting'; since: number }/**- * The QUEUED badge's tooltip. One function for all three cases so the sentences cannot drift, and+ * Which delivery records the Canvas sweep retires: every record whose node is no longer an armed+ * node on the ACTIVE canvas (delivered, run by hand with ▶, deleted, or in another project) —+ * EXCEPT a `starting` one. A headless start (#925) runs precisely for a node that is not on the+ * active canvas, and its orchestrator owns the record end to end (`clear` on success or+ * not-persistent, `markFailed` otherwise). Retiring it here would re-enable ▶ the moment the user+ * switched to that project mid-start — the manualOnly claim alone reads as a failed launch — and ▶+ * would then type into a pane core is still typing into.+ */+export function deliveriesToRetire(+ byId: Record<string, LaunchDelivery | undefined>,+ isArmedOnCanvas: (nodeId: string) => boolean+): string[] {+ return Object.keys(byId).filter((id) => byId[id]?.kind !== 'starting' && !isArmedOnCanvas(id))+}++/**+ * The QUEUED badge's tooltip. One function for every case so the sentences cannot drift, and* so the two warnings are held to the same standard as the ordinary one: say what is true, name* what would fix it, and never claim a cause that was not measured.*@@ -170,6 +192,9 @@ export type LaunchDelivery =* why (a host that is down, a spawn that failed, a machine under load all look identical from* here), so the text says what we observed and leaves the diagnosis to the node's own overlay,* which does know.+ *+ * `starting` comes first, ahead even of the relay sentence: while core is typing the launch, no+ * sentence may offer ▶, and "waiting for X" would describe a wait that is already over.*/export function launchTooltip(delivery: LaunchDelivery | undefined,@@ -178,6 +203,7 @@ export function launchTooltip(erroredOn?: string,relay = false): string {+ if (delivery?.kind === 'starting') return 'Starting in the background — an agent asked for this session to run now.'const runs = `Runs:\n${command}`if (relay) return `Launch delivery from a relay tab is unavailable. Open the host to run this command.\n${runs}`if (delivery?.kind === 'failed')diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsxindex 129d72f46..07b7af1dd 100644--- a/src/renderer/nodes/TerminalNode.tsx+++ b/src/renderer/nodes/TerminalNode.tsx@@ -1992,6 +1992,9 @@ export function TerminalNode({const observedLaunchDelivery = useLaunchDelivery((s) => s.byId[id])const launchDelivery = observedLaunchDelivery ?? (pendingLaunch?.manualOnly? { kind: 'failed' as const, attempts: 1, at: 0 } : undefined)+ // A headless start (#925) is typing this node's launch from core: the badge says so, without the+ // warning, and ▶ stands aside — a click would splice a second copy into the pane.+ const startingNow = launchDelivery?.kind === 'starting'// A node's own first-open launch is in flight: the live `initialCommand` alias is still set// (it is cleared on every outcome) and nothing holds it. Its `pendingLaunch` is only the durable// write-ahead record — and it carries `manualOnly` from the claim until Enter lands — so showing@@ -5745,16 +5748,16 @@ export function TerminalNode({{pendingLaunch && !firstOpenInFlight && (<spanclassName={`term-node__status term-node__status--queued nodrag${- launchDelivery ? ' term-node__status--queued-warn' : ''+ launchDelivery && !startingNow ? ' term-node__status--queued-warn' : ''}`}title={launchTooltip(launchDelivery, pendingWaitingOn, pendingLaunch.command, pendingErroredOn, session.source === 'relay')}><span className="term-node__status-dot" />- {launchDelivery ? '⚠ ' : ''}QUEUED+ {startingNow ? 'STARTING' : `${launchDelivery ? '⚠ ' : ''}QUEUED`}<buttonclassName="term-node__queued-run"- disabled={session.source === 'relay'}- title={session.source === 'relay' ? "Open the host to run this command" : pendingLaunch.manualOnly ? "Retry launch at a shell prompt" : "Run now without waiting"}+ disabled={session.source === 'relay' || startingNow}+ title={session.source === 'relay' ? "Open the host to run this command" : startingNow ? "Starting in the background" : pendingLaunch.manualOnly ? "Retry launch at a shell prompt" : "Run now without waiting"}onClick={(e) => {e.stopPropagation()// Disarm only on a delivery that actually landed. Dropping `pendingLaunch`diff --git a/src/renderer/nodes/session-ready-signal.test.ts b/src/renderer/nodes/session-ready-signal.test.tsindex 1cf324f1d..982bba14b 100644--- a/src/renderer/nodes/session-ready-signal.test.ts+++ b/src/renderer/nodes/session-ready-signal.test.ts@@ -104,6 +104,14 @@ describe('the QUEUED badge carries the delivery state (source pins)', () => {)})+ it('a background start reads STARTING, without the warning, and disables ▶ (#925)', () => {+ // Core is typing the launch into this pane; a ▶ click would splice a second copy into it.+ expect(src).toContain("const startingNow = launchDelivery?.kind === 'starting'")+ expect(src).toContain("launchDelivery && !startingNow ? ' term-node__status--queued-warn' : ''")+ expect(src).toContain("{startingNow ? 'STARTING' : `${launchDelivery ? '⚠ ' : ''}QUEUED`}")+ expect(src).toContain("disabled={session.source === 'relay' || startingNow}")+ })+})describe('the eye button hides cards AND connections (source pins)', () => {diff --git a/src/renderer/state/launchDelivery.test.ts b/src/renderer/state/launchDelivery.test.tsindex 863871f82..930cb0b28 100644--- a/src/renderer/state/launchDelivery.test.ts+++ b/src/renderer/state/launchDelivery.test.ts@@ -49,3 +49,31 @@ describe('useLaunchDelivery', () => {expect(useLaunchDelivery.getState().byId['term-1']).toBeUndefined()})})++/**+ * #925 — a headless start is in flight: core owns the pane and is typing the launch into it, so+ * the node's ▶ must not type too. The orchestrator raises `starting` before it launches and+ * settles it with `clear` (started / not persistent) or `markFailed` (any other failure).+ */+describe('launchDelivery starting (#925)', () => {+ beforeEach(() => useLaunchDelivery.setState({ byId: {} }))+ it('markStarting records a starting state that markFailed / clear then replace', () => {+ useLaunchDelivery.getState().markStarting('n1')+ expect(useLaunchDelivery.getState().byId.n1?.kind).toBe('starting')+ useLaunchDelivery.getState().markFailed('n1', 1)+ expect(useLaunchDelivery.getState().byId.n1?.kind).toBe('failed')+ useLaunchDelivery.getState().markStarting('n1')+ useLaunchDelivery.getState().clear('n1')+ expect(useLaunchDelivery.getState().byId.n1).toBeUndefined()+ })+ it('markStalled never downgrades a start in flight', () => {+ useLaunchDelivery.getState().markStarting('n1')+ useLaunchDelivery.getState().markStalled('n1')+ expect(useLaunchDelivery.getState().byId.n1?.kind).toBe('starting')+ })+ it('a failure that follows a start reports the attempts it was given, not a stale count', () => {+ useLaunchDelivery.getState().markStarting('n1')+ useLaunchDelivery.getState().markFailed('n1', 1)+ expect(useLaunchDelivery.getState().byId.n1).toMatchObject({ kind: 'failed', attempts: 1 })+ })+})diff --git a/src/renderer/state/launchDelivery.ts b/src/renderer/state/launchDelivery.tsindex 9925a4fa8..29d994dc1 100644--- a/src/renderer/state/launchDelivery.ts+++ b/src/renderer/state/launchDelivery.ts@@ -13,7 +13,7 @@ import type { LaunchDelivery } from '../lib/pendingLaunch'* Absent = nothing to report: the node is simply waiting on its dependencies (which the QUEUED* badge already explains), or it has not been armed at all.*- * The states, and why both exist:+ * The states, and why each exists:* - `stalled` — the gate is OPEN (every dependency is satisfied) but the node's terminal has not* come up, so there is nothing to deliver INTO yet. We keep waiting — an SSH host that comes* back, a slow spawn and a project the user just switched to all end here first — but we say@@ -22,9 +22,15 @@ import type { LaunchDelivery } from '../lib/pendingLaunch'* - `failed` — the terminal DID come up and refused the launch anyway, for every attempt in the* backoff schedule. That is a real dead end: nothing further will retry it, so the badge must* carry the warning and point at the manual ▶.+ * - `starting` — a headless start (#925) is in flight: core has claimed the node and is typing its+ * launch into the pane. NOT a warning: the badge reads STARTING and ▶ is disabled, because a+ * click would splice a second copy of the command into the one core is typing. Its orchestrator+ * owns it end to end — `clear` on a start (or a refusal before any spawn), `markFailed` on any+ * other failure — which is why the Canvas sweep never retires it (`deliveriesToRetire`).*- * Neither state is ever inferred from silence. `stalled` is raised by a timer that starts when- * the gate opens, `failed` only after a delivery was actually attempted and refused.+ * No state is ever inferred from silence. `stalled` is raised by a timer that starts when the gate+ * opens, `failed` only after a delivery was actually attempted and refused, `starting` only by the+ * orchestrator that is about to launch.*/export type { LaunchDelivery }@@ -34,6 +40,8 @@ interface LaunchDeliveryStore {markStalled: (nodeId: string) => void/** Every attempt in the schedule was refused. Terminal: only ▶ (or a respawn) revives it. */markFailed: (nodeId: string, attempts: number) => void+ /** A headless start (#925) is about to type this node's launch: ▶ must stand aside until it settles. */+ markStarting: (nodeId: string) => void/** Delivered, disarmed, or the node is gone — nothing left to report. */clear: (nodeId: string) => void}@@ -43,9 +51,14 @@ export const useLaunchDelivery = create<LaunchDeliveryStore>((set) => ({markStalled: (nodeId) =>set((s) =>// Idempotent: the sweep can re-raise this on every re-render, and a fresh `since` on each- // would make the badge's age tick backwards. `failed` is never downgraded to `stalled`.+ // would make the badge's age tick backwards. ANY existing record wins, so `failed` is never+ // downgraded to `stalled` and a `starting` start is never overwritten by one.s.byId[nodeId] ? s : { byId: { ...s.byId, [nodeId]: { kind: 'stalled', since: Date.now() } } }),+ markStarting: (nodeId) =>+ // Unconditional: a start replaces whatever an earlier attempt left behind, `failed` included —+ // that record described the attempt this one is retrying.+ set((s) => ({ byId: { ...s.byId, [nodeId]: { kind: 'starting', since: Date.now() } } })),markFailed: (nodeId, attempts) =>set((s) => {// Never let a later, smaller count shrink the record: the manual ▶ reports its own single