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.

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.tsx
index 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 nothing
diff --git a/src/renderer/lib/controlRouting.test.ts b/src/renderer/lib/controlRouting.test.ts
index 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 hea
expect(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.ts
index 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.ts
index 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 b
expect(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 = true
diff --git a/src/renderer/lib/pendingLaunch.ts b/src/renderer/lib/pendingLaunch.ts
index 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.pendingLaunch
if (!p || !p.command || p.manualOnly || p.executor === 'server') continue
if (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') continue
if (p.awaitSetupGroup && !(setupDone?.(p.awaitSetupGroup) ?? true)) continue
if (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_000
export 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.tsx
index 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 && (
<span
className={`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`}
<button
className="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.ts
index 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.ts
index 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.ts
index 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