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
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.tsindex 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.tsindex 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.tsindex 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): AgentMessageReplyerror: `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.tsindex 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.tsindex 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 — beforediff --git a/src/main/agent-messaging.test.ts b/src/main/agent-messaging.test.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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_HINTconst 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 claimeddiff --git a/src/server/canvas-control.ts b/src/server/canvas-control.tsindex 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.tsindex 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' }}