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.

fix(messaging): queue a send to a node whose launch is still held

Fabricio Casalif51f8101d975
diff --git a/src/core/agents/agent-message-decide.test.ts b/src/core/agents/agent-message-decide.test.ts
index 758c0bdd1..da7e89b29 100644
--- a/src/core/agents/agent-message-decide.test.ts
+++ b/src/core/agents/agent-message-decide.test.ts
@@ -338,7 +338,7 @@ describe('RETRYABLE', () => {
it('answers for every outcome kind the union declares', () => {
// Runtime half. The compile-time half is below and is enforced by `npm run typecheck`.
const kinds = Object.keys(RETRYABLE) as AgentMessageOutcomeKind[]
- expect(kinds.length).toBe(17)
+ expect(kinds.length).toBe(18)
for (const k of kinds) expect(typeof RETRYABLE[k]).toBe('boolean')
})
diff --git a/src/core/agents/agent-message-decide.ts b/src/core/agents/agent-message-decide.ts
index 50b368b0e..923e82084 100644
--- a/src/core/agents/agent-message-decide.ts
+++ b/src/core/agents/agent-message-decide.ts
@@ -76,6 +76,7 @@ export type AgentMessageOutcome =
| { kind: 'targetNotAgentPane'; observed: string }
| { kind: 'targetNotPasteAware' }
| { kind: 'targetGone' }
+ | { kind: 'targetNotStarted' } // launch held, never spawned yet — queued when a queue is wired. Retryable.
| { kind: 'notPermitted'; reason: NotPermittedReason }
export type AgentMessageOutcomeKind = AgentMessageOutcome['kind']
@@ -109,6 +110,7 @@ export const RETRYABLE: Record<AgentMessageOutcomeKind, boolean> = {
targetNotAgentPane: false,
targetNotPasteAware: false,
targetGone: false,
+ targetNotStarted: true,
notPermitted: false
}
diff --git a/src/core/agents/agent-messaging.ts b/src/core/agents/agent-messaging.ts
index dc234ec23..e42435f97 100644
--- a/src/core/agents/agent-messaging.ts
+++ b/src/core/agents/agent-messaging.ts
@@ -153,6 +153,16 @@ export interface AgentMessagingDeps {
* refuse `unproven-target-owner`.
*/
paneOwnerProject(nodeId: string): string | undefined
+ /**
+ * Does THIS machine hold an undelivered launch for `nodeId` in `projectId` (`pendingLaunch`, the
+ * machine-local exec overlay — never the git-shared file)? A node opened into a project that is
+ * not on screen without `--run-now` is written with its launch held until that project is shown,
+ * so for a while it has no pane at all. Paired with `hasLiveSession` = false, that is a target
+ * that has not STARTED yet, which the queue waits out (`targetNotStarted`) instead of refusing
+ * it as unproven: an ownership proof is only ever recorded by the spawn that has not happened.
+ * Optional; absent ⇒ such a target is refused `unproven-target-owner` as before.
+ */
+ heldLaunch?(projectId: string, nodeId: string): boolean
/**
* Optional shell-specific creator gate. Server Edition supplies its process-local caller→target
* proof so message delivery cannot type into a session the caller did not spawn. Desktop omits
@@ -636,6 +646,15 @@ export function renderMessageOutcome(o: AgentMessageOutcome): AgentMessageReply
error: `targetGone: no live session exists for the target node. ${advice}`,
result: o
}
+ case 'targetNotStarted':
+ return {
+ ok: false,
+ error:
+ 'targetNotStarted: the target was opened with its launch held (its project is not on ' +
+ 'screen) and has not started yet, so there is no session to deliver into. Start it with ' +
+ `\`run --node <id>\` (or open it with --run-now next time), then send again. ${advice}`,
+ result: o
+ }
case 'notPermitted':
return {
ok: false,
@@ -709,8 +728,23 @@ export async function runDelivery(
// store's `projectId` is only a cross-check. Unprovable — no ledger entry (restart / never
// spawned here), or the ledger owner disagrees with the sole store claimant — fails closed.
const owner = projectId ? deps.paneOwnerProject(req.targetNodeId) : undefined
- if (!projectId || !owner || owner !== projectId) notPermitted = 'unproven-target-owner'
- else if (!deps.messagingEnabled(owner)) notPermitted = 'switch-off'
+ if (!projectId || !owner || owner !== projectId) {
+ // A target that has not been SPAWNED yet (its launch is held until its project is shown, or
+ // until `--run-now` / `run` starts it) has no ownership proof because the only thing that can
+ // record one is the spawn it is waiting for. That is a wait, not a refusal: answered
+ // `targetNotStarted`, which the queue holds, and the flush re-runs this whole chain against
+ // the pane the spawn will have proven. Only for NO owner and NO session — a live pane whose
+ // owner is unproven or disputed stays refused, which is the security property this gate is.
+ if (
+ projectId &&
+ !owner &&
+ deps.heldLaunch?.(projectId, req.targetNodeId) &&
+ !(await deps.hasLiveSession(req.targetNodeId))
+ ) {
+ if (!deps.messagingEnabled(projectId)) notPermitted = 'switch-off'
+ else return { kind: 'targetNotStarted' }
+ } else notPermitted = 'unproven-target-owner'
+ } else if (!deps.messagingEnabled(owner)) notPermitted = 'switch-off'
}
// Flow control (PR #208), taken as a RESERVATION rather than a pure read: `checkFlowLimits`
@@ -835,7 +869,10 @@ const BOARD_RETRY_SLACK_MS = 500
* scope/ownership/grant, and its non-readiness is a turn it happens to be in, not a boundary. */
const QUEUE_ON_BUSY: ReadonlySet<AgentMessageOutcome['kind']> = new Set([
'targetBusy',
- 'targetNotIdleUnknown'
+ 'targetNotIdleUnknown',
+ // Opened with its launch held (not on screen, no `--run-now`): flushed on its first idle after
+ // the launch lands. Its TTL runs as for any queued message, so a project nobody opens expires it.
+ 'targetNotStarted'
])
/**
diff --git a/src/core/canvas-control-core.ts b/src/core/canvas-control-core.ts
index 91e8494e1..476b6cbef 100644
--- a/src/core/canvas-control-core.ts
+++ b/src/core/canvas-control-core.ts
@@ -873,6 +873,10 @@ export function buildCanvasControlInstructions(shimPath: string): string {
' and do not report the session as started. `--cwd`/`--count`/`--group`/`--after`/`--prompt`',
' all still apply. If your project is CLOSED the node is still saved into it and the reply',
' says the project is closed; the tab is not reopened for you.',
+ ' A cold-opened node has NO session yet, so a `send` to it cannot land: it is queued and flushed',
+ ' after the node starts and finishes its first turn (its TTL still runs, so a project nobody opens',
+ ' expires it; `targetNotStarted` when it cannot be queued). To coordinate with a station now,',
+ ' open it with `--run-now` or start it with `run --node <id>`.',
' Add `--run-now` to start a cold-opened session immediately instead. Put it LAST on the line,',
' in either form (`--run-now` or `--run-now=1`): an older shim can still sit on an SSH host (it',
' is rewritten only on connect), and it takes the token after any flag as that flag\'s value,',
diff --git a/src/core/workspace-store.ts b/src/core/workspace-store.ts
index 1b486ecf3..d940d78fb 100644
--- a/src/core/workspace-store.ts
+++ b/src/core/workspace-store.ts
@@ -1977,6 +1977,22 @@ export class WorkspaceStore {
return out
}
+ /**
+ * Does THIS machine hold an undelivered launch (`pendingLaunch`) for `nodeId` in `projectId`?
+ * Read from the entry's machine-local exec overlay (`localExec`, where every ref kind keeps it),
+ * with the entry's own node copy as a fallback. Same id semantics as `persistedCanvases`. Agent
+ * messaging asks it to tell a node that has not STARTED yet from one whose pane is unproven.
+ */
+ heldLaunch(projectId: string, nodeId: string): boolean {
+ for (const e of this.index?.entries ?? []) {
+ if ((e.project ? e.project.id : e.id) !== projectId) continue
+ if (e.localExec?.[nodeId]?.pendingLaunch) return true
+ const nodes = e.project?.nodes ?? e.cache?.nodes ?? []
+ return nodes.some((n) => n.id === nodeId && !!n.pendingLaunch)
+ }
+ return false
+ }
+
/**
* Does this project exist on THIS machine, and is it SSH? The `--project` targeting gate
* (issue #338, src/core/project-grants.ts) asks the core store — never the request — before
diff --git a/src/main/agent-messaging.test.ts b/src/main/agent-messaging.test.ts
index 5752ae6e6..b485c6f25 100644
--- a/src/main/agent-messaging.test.ts
+++ b/src/main/agent-messaging.test.ts
@@ -510,3 +510,59 @@ describe('deliver-on-idle wiring (PR 7)', () => {
expect(expiredLine?.projectId).toBe('p1')
})
})
+
+describe('a target that has not started yet (launch held off screen)', () => {
+ // The field report: `open-agent` into a project not on screen, no `--run-now`, then `send` at
+ // once. The node exists only as a held launch, so no spawn has recorded its owner — and it used
+ // to be refused `unproven-target-owner` with advice to restart a session that did not exist.
+ const unstarted = (over: Partial<AgentMessagingDeps> = {}) => {
+ let started = false
+ const deps = fakeDeps({
+ heldLaunch: (projectId, id) => !started && projectId === 'p1' && id === 'b1',
+ hasLiveSession: () => started,
+ paneOwnerProject: (id) => (started && id === 'b1' ? 'p1' : undefined),
+ ...over
+ })
+ return { deps, start: () => (started = true) }
+ }
+
+ it('is answered targetNotStarted (retryable) when no queue is wired', async () => {
+ const { deps } = unstarted()
+ const { outcome, reply } = await deliverFromControl(req(), deps)
+ expect(outcome.kind).toBe('targetNotStarted')
+ expect(RETRYABLE.targetNotStarted).toBe(true)
+ expect(reply.ok).toBe(false)
+ expect(reply.error).toMatch(/run --node/)
+ expect(deps.rec.sent).toHaveLength(0)
+ })
+
+ it('is queued, then delivered once the spawn proves ownership', async () => {
+ const { deps, start } = unstarted()
+ const queue = createDeliveryQueue(deps, { schedule: () => () => {} })
+ deps.queue = queue
+ const { outcome } = await deliverFromControl(req(), deps)
+ expect(outcome.kind).toBe('queued')
+ expect(deps.rec.sent).toHaveLength(0)
+ start()
+ await queue.onTargetIdle('b1')
+ expect(deps.rec.sent).toHaveLength(1)
+ })
+
+ it('still honours the per-project switch', async () => {
+ const { deps } = unstarted({ messagingEnabled: () => false })
+ const { outcome } = await deliverFromControl(req(), deps)
+ expect(outcome).toEqual({ kind: 'notPermitted', reason: 'switch-off' })
+ })
+
+ it('a LIVE pane with no proven owner stays refused, held launch or not', async () => {
+ const { deps } = unstarted({ hasLiveSession: () => true })
+ const { outcome } = await deliverFromControl(req(), deps)
+ expect(outcome).toEqual({ kind: 'notPermitted', reason: 'unproven-target-owner' })
+ })
+
+ it('a node with no held launch and no session stays unproven', async () => {
+ const { deps } = unstarted({ heldLaunch: () => false })
+ const { outcome } = await deliverFromControl(req(), deps)
+ expect(outcome).toEqual({ kind: 'notPermitted', reason: 'unproven-target-owner' })
+ })
+})
diff --git a/src/main/index.ts b/src/main/index.ts
index 8fd0903e0..9f8bcf42f 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -1960,6 +1960,8 @@ app.whenReady().then(async () => {
// (core/agents/pane-ownership.ts). The gate trusts this over the attacker-writable store to
// decide whose grant applies; unproven ⇒ refused (PR #237 fix round 2).
paneOwnerProject: (id) => paneOwnerProject(id),
+ // A node opened off screen without `--run-now` has no pane yet: queued, not refused.
+ heldLaunch: (projectId, id) => workspaceStore.heldLaunch(projectId, id),
customAgents: () => settingsStore.get().customAgents,
appendBoardLog: (projectId, entry) => appendBoardLogVia(boardLogRouter, projectId, entry)
}
diff --git a/src/renderer/lib/coldOpen.test.ts b/src/renderer/lib/coldOpen.test.ts
index 8f54cf7bd..5c3462149 100644
--- a/src/renderer/lib/coldOpen.test.ts
+++ b/src/renderer/lib/coldOpen.test.ts
@@ -181,7 +181,8 @@ describe('group grid geometry (shared with the live addGrouped path)', () => {
describe('coldOpenMessage — ONE sentence for both cold-open sites', () => {
it('names the count, the agent, the project and the ids, and says when it starts', () => {
expect(coldOpenMessage(2, 'claude', 'Backend', ['t1', 't2'])).toBe(
- 'opened 2 claude session(s) in "Backend" (t1, t2) — queued; starts when that project is next viewed'
+ 'opened 2 claude session(s) in "Backend" (t1, t2) — queued; starts when that project is next viewed' +
+ ', or at once with the `run` verb (or pass --run-now when opening)'
)
})
diff --git a/src/renderer/lib/coldOpen.ts b/src/renderer/lib/coldOpen.ts
index 81ecad699..1f0179291 100644
--- a/src/renderer/lib/coldOpen.ts
+++ b/src/renderer/lib/coldOpen.ts
@@ -175,6 +175,11 @@ export function coldGroupChildCount(nodes: readonly ColdNode[], groupId: string)
* "next viewed", it just has to be reopened first, and an agent that is told nothing would report a
* session as started that has no process behind it.
*/
+/** Where a held node's other way to start is named, so an orchestrator that must coordinate with
+ * it now (a `send` waits for the session to exist) is not left waiting for a human to look. Part of
+ * the "queued" clause: `mergeRunNow` drops them together. */
+export const COLD_OPEN_RUN_HINT = ', or at once with the `run` verb (or pass --run-now when opening)'
+
export function coldOpenMessage(
count: number,
what: string,
@@ -184,7 +189,7 @@ export function coldOpenMessage(
): string {
return (
`opened ${count} ${what} session(s) in "${projectName}" (${ids.join(', ')}) — ` +
- 'queued; starts when that project is next viewed' +
+ `queued; starts when that project is next viewed${COLD_OPEN_RUN_HINT}` +
(opts.closed ? ' (that project is closed — reopen it from the welcome screen)' : '')
)
}
diff --git a/src/renderer/lib/headlessRun.ts b/src/renderer/lib/headlessRun.ts
index 032ba402b..3c9e50be6 100644
--- a/src/renderer/lib/headlessRun.ts
+++ b/src/renderer/lib/headlessRun.ts
@@ -7,6 +7,7 @@
import type { CanvasNodeState, PendingLaunch, Project, PtyCreateOptions } from '@shared/types'
import type { HeadlessLaunchFailure, HeadlessLaunchResult } from '@shared/headless-launch'
import { HEADLESS_COLS, HEADLESS_ROWS, localNodePtyOptions } from '@shared/node-pty-options'
+import { COLD_OPEN_RUN_HINT } from './coldOpen'
export type RunVerbPlan =
| 'nothing-queued'
@@ -199,7 +200,7 @@ export async function savePendingAnywhere(
return env.writeDisk()
}
-const STARTS_ON_VIEW = / — queued; starts when that project is next viewed/
+const STARTS_ON_VIEW = ' — queued; starts when that project is next viewed' + COLD_OPEN_RUN_HINT
const CLOSED_HINT = / \(that project is closed — reopen it from the welcome screen\)/
/** Failures after which the node's launch is exactly what the cold open left: never claimed
diff --git a/src/server/canvas-control.ts b/src/server/canvas-control.ts
index 4eaad8c01..ae5ec7f92 100644
--- a/src/server/canvas-control.ts
+++ b/src/server/canvas-control.ts
@@ -294,6 +294,7 @@ export async function initServerCanvasControl(
() => deps.settings()
),
paneOwnerProject,
+ heldLaunch: (projectId, nodeId) => deps.workspaceStore.heldLaunch(projectId, nodeId),
callerOwnsTarget: (sourceNodeId, targetNodeId) =>
factory.ownsSpawn(sourceNodeId, targetNodeId),
customAgents: () => deps.settings().customAgents,
diff --git a/src/shared/board-comment.ts b/src/shared/board-comment.ts
index fcc39e89b..94e2e6d8a 100644
--- a/src/shared/board-comment.ts
+++ b/src/shared/board-comment.ts
@@ -241,6 +241,7 @@ const OUTCOME_TEXT: Record<string, BoardCommentOutcomeView> = {
text: 'not delivered — the session cannot take a multi-line message'
},
targetGone: { tone: 'error', text: 'not delivered — the session is not running' },
+ targetNotStarted: { tone: 'error', text: 'not delivered — the session has not started yet' },
notPermitted: { tone: 'error', text: 'not delivered — not permitted' }
}