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(control): a retried open does not open a second node (--request-id)

review1dc5b3d5202e
diff --git a/CLAUDE.md b/CLAUDE.md
index d076b44de..f7fd2f0f5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -3149,6 +3149,47 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile
**A new verb must not DEPEND on the fix**: the shim is rewritten locally every app boot but onto
an SSH host only inside `RemoteHooks.setup()` (on connect), so an already-connected project keeps
the old loop with no signal on the wire. Give every flag a value and both loops agree.
+ **A retried call must not open a second node (`--request-id`, `core/control-request-ledger.ts`).**
+ The reply to an open can be lost while the open went through — the agent's own tool call is
+ killed (~2 min for a Bash tool call while a slow host holds the POST), the ssh tunnel drops
+ mid-reply, or the shim's endpoint walk re-posts after a transport that failed AFTER the request
+ was read — and the agent's natural retry used to open a second agent, team or worktree. The
+ verbs that create something (`REQUEST_ID_VERBS`) take `--request-id <id>`, and the shim also
+ sends its own `requestId` form field, generated once per RUN (`od` of `/dev/urandom`, else
+ pid+time), on every POST of that run, so its own re-post is covered for an agent that never read
+ the docs. Rules a refactor must not undo: (1) **the ledger lives in the hook server's `/control/`
+ route** (core), the one place desktop main's forwarder and the Server Edition's
+ `createServerEditionControlHandler` both sit behind — putting it in either shell's handler
+ leaves the other without it; (2) rows are keyed **(verified caller node, id)** only — an
+ unverified caller gets no dedupe rather than a shared bucket, and an explicit id from one is
+ answered with `REQUEST_ID_UNVERIFIED_NOTE`; (3) the row is **claimed before the handler runs**,
+ synchronously after the lookup, so two concurrent POSTs cannot both run; (4) a fingerprint (verb
+ + args minus the id, key order ignored) makes the same id with a different call a
+ `request-id-conflict`; (5) a settled row stores the WHOLE reply and a replay returns it (text:
+ a `replayed:` first line; JSON: `replayed: true`) — a refusal included, so an id never runs
+ twice; (6) a handler that cannot say whether its effect happened answers `indeterminate: true`
+ (desktop main's 120 s wait, now `src/main/control-forward.ts`: the renderer is not cancelled, and
+ an `open-worktree` whose `git worktree add` outlives the wait still completes) or throws, and the
+ row becomes UNKNOWN — refused, never re-run; the forwarder hands a late renderer answer back via
+ the handler's `onLateAnswer`, and settlement only moves up (unknown → answer, never the reverse);
+ (7) an explicit id on a verb outside the set is REFUSED (`request-id-unsupported`), like
+ `--dry-run` — an agent believing its `write` is protected when it is not is the failure the flag
+ exists to end — while a malformed or out-of-set per-run id is silently ignored; (8) a dry run
+ neither claims nor replays. The ledger is **process memory** (24 h, 256 per caller, 4096 in total,
+ in-flight rows never evicted): an app restart between the effect and the retry runs the retry
+ again, which is the case that matters least and costs a store with atomic writes on every call
+ to cover. The timeout sentence is now verb-aware (`controlTimeoutError`): only a confirm-gated
+ verb, whose dialog dismisses itself at the same deadline, is still called "safe to retry". An SSH
+ host keeps the shim it got at its last connect, so until that project reconnects its runs carry
+ no per-run id (an explicit `--request-id` still works through the old loop). Agent-facing text
+ is rendered from `REQUEST_ID_VERBS` / `REQUEST_ID_RETRYABLE` / `REQUEST_ID_OUTCOME_GLOSS`
+ (`requestIdDocLines`). Tests: the ledger alone, the route (both dialects, in flight, conflict,
+ late answer, throw), the Server Edition handler behind it, and the real shim under `/bin/sh`
+ through a proxy that forwards the request and drops the reply — the re-post case, red before.
+ Deliberately NOT in the set: reads (a replay would serve a stale snapshot, and `browser
+ --cookies` would sit in memory for a day), the idempotent-by-nature verbs, and the
+ human-confirmed / rate-limited ones (`write`, `send`, `settings`, `report-issue`) — widening it
+ to those is a separate decision.
**WHICH CANVAS ANSWERS, and why an open never moves the camera** (`renderer/lib/controlRouting.ts`
+ `renderer/lib/coldOpen.ts`). React Flow holds only the ACTIVE project's nodes, but every other
open project's tmux sessions keep running, so a control call routinely arrives from a node the
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a32e55b4d..ac6c85258 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -335,6 +335,17 @@ anything else. Board-level fields survive every transform — `pullLinks` is one
against the renderer's dispositions — deliberately cross-layer, because that is the only way
"every verb" is checked rather than remembered.
+- **A canvas-control verb that creates something must be safe to retry.** An agent whose reply
+ was lost (its tool call timed out, the tunnel dropped) runs the same command again, and the
+ shim's endpoint walk re-posts on its own. The hook server's `/control/` route — the one place
+ desktop main and the Server Edition both sit behind — keys a ledger on (verified caller node,
+ request id) and replays the first reply instead of running the call twice
+ (`src/core/control-request-ledger.ts`). A new verb that opens a node, a team, a worktree or a frame
+ joins `REQUEST_ID_VERBS` in the same PR; the agent-facing text renders from that set. A handler
+ that gives up before it knows whether its effect happened answers `indeterminate: true`, never a
+ plain failure that says "safe to retry" — the retry would then open a second one. Do not move the
+ ledger into one shell's handler: the other shell silently loses it.
+
- **A new canvas-control open path must record who opened the node.** When a station stops, the
agent that opened it is told (`src/core/agents/station-notice.ts`) — and a rope alone cannot say
who that is, because an `--after` node is roped to the stations it waited on too, with the same id
diff --git a/src/core/agents/agent-message-flow.ts b/src/core/agents/agent-message-flow.ts
index 6ca39178b..f0abe67da 100644
--- a/src/core/agents/agent-message-flow.ts
+++ b/src/core/agents/agent-message-flow.ts
@@ -3,7 +3,7 @@ import type { AgentMessageOutcome } from './agent-message-decide'
/**
* FLOW CONTROL — the first throttle the control surface has ever had.
*
- * What exists today is timeouts (`SLOWLORIS_MS` → `CONTROL_CEILING_MS`, the 120 s `pendingControl`
+ * What exists today is timeouts (`SLOWLORIS_MS` → `CONTROL_CEILING_MS`, the 120 s control-forward
* bound) and a one-at-a-time confirmation serializer (`confirmBusy()`). A timeout is not a throttle
* and a modal is not a budget — and messaging skips the modal entirely once the per-project switch
* is on, so even the accidental brake is gone. These two limits are the replacement.
diff --git a/src/core/agents/hook-server.request-id.test.ts b/src/core/agents/hook-server.request-id.test.ts
new file mode 100644
index 000000000..78e75e6ff
--- /dev/null
+++ b/src/core/agents/hook-server.request-id.test.ts
@@ -0,0 +1,250 @@
+// A retried control call must not open a second node — exercised at the ONE place both shells pass:
+// the hook server's `/control/` route. Desktop main and the Server Edition each register a handler
+// behind it; neither sees a request the ledger answered, which is what these tests count.
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import http from 'node:http'
+import { initPlatform, resetPlatformForTests } from '../platform'
+import { fakePlatform } from '../platform-fake'
+import { hookServer } from './hook-server'
+import { nodeAuthToken } from './node-auth-token'
+import { REQUEST_ID_REPLAYED_LEAD } from '../control-request-ledger'
+
+const secret = Buffer.alloc(32, 7)
+let dir: string
+type Cmd = { verb: string; nodeId: string; args: Record<string, string>; verified: boolean }
+let handled: Cmd[] = []
+let next: (cmd: Cmd, late?: (r: { ok: boolean; message?: string }) => void) => Promise<{
+ ok: boolean
+ message?: string
+ result?: unknown
+ error?: string
+ indeterminate?: boolean
+}>
+
+beforeAll(async () => {
+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-reqid-'))
+ resetPlatformForTests()
+ initPlatform(fakePlatform({ userDataDir: dir }))
+ await hookServer.start()
+ hookServer.setNodeAuthSecret(secret)
+ hookServer.setControlHandler(async (cmd) => {
+ handled.push({ verb: cmd.verb, nodeId: cmd.nodeId, args: cmd.args, verified: cmd.verified })
+ return next(cmd, cmd.onLateAnswer)
+ })
+})
+beforeEach(() => {
+ handled = []
+ let n = 0
+ next = async (cmd) => ({ ok: true, message: `opened n${++n}`, result: { ids: [`n${n}`], verb: cmd.verb } })
+})
+afterAll(() => {
+ hookServer.setIdentityStrictOverride(() => undefined)
+ hookServer.clearNodeAuthSecretForTests()
+ hookServer.stop()
+ resetPlatformForTests()
+ fs.rmSync(dir, { recursive: true, force: true })
+})
+
+let seq = 0
+/** A fresh caller node per test, so rows from one test never answer another. */
+const freshNode = (): string => `src-${++seq}`
+
+function post(
+ verb: string,
+ opts: {
+ node: string
+ args?: Record<string, string>
+ cliRequestId?: string
+ json?: boolean
+ verified?: boolean
+ }
+): Promise<{ status: number; body: string }> {
+ const { node, args = {}, cliRequestId, json = false, verified = true } = opts
+ const body = json
+ ? JSON.stringify({ nodeId: node, args, ...(cliRequestId ? { requestId: cliRequestId } : {}) })
+ : new URLSearchParams({
+ nodeId: node,
+ ...(cliRequestId ? { requestId: cliRequestId } : {}),
+ ...Object.fromEntries(Object.entries(args).map(([k, v]) => [`arg.${k}`, v]))
+ }).toString()
+ return new Promise((resolve, reject) => {
+ const req = http.request(
+ {
+ host: '127.0.0.1',
+ port: hookServer.getPort(),
+ path: `/control/${verb}`,
+ method: 'POST',
+ headers: {
+ 'x-nodeterm-hook-token': hookServer.getToken(),
+ ...(verified ? { 'x-nodeterm-node-token': nodeAuthToken(secret, node) } : {}),
+ 'content-type': json ? 'application/json' : 'application/x-www-form-urlencoded',
+ accept: json ? 'application/json' : 'text/plain'
+ }
+ },
+ (res) => {
+ let text = ''
+ res.setEncoding('utf8')
+ res.on('data', (c) => (text += c))
+ res.on('end', () => resolve({ status: res.statusCode!, body: text }))
+ }
+ )
+ req.on('error', reject)
+ req.end(body)
+ })
+}
+
+describe('control route: --request-id makes a retried open idempotent', () => {
+ it('the same id twice runs the handler ONCE and replays the original reply, marked as a replay', async () => {
+ const node = freshNode()
+ const args = { agent: 'claude', prompt: 'build it', 'request-id': 'wave1-a' }
+ const first = await post('open-agent', { node, args })
+ expect(first).toEqual({ status: 200, body: 'opened n1\n' })
+ const again = await post('open-agent', { node, args })
+ expect(again.status).toBe(200)
+ expect(again.body.split('\n')[0]).toContain(REQUEST_ID_REPLAYED_LEAD)
+ expect(again.body).toContain('wave1-a')
+ expect(again.body).toContain('opened n1')
+ expect(again.body).not.toContain('opened n2')
+ expect(handled).toHaveLength(1)
+ })
+
+ it('the JSON dialect replays the whole stored reply plus `replayed: true`', async () => {
+ const node = freshNode()
+ const args = { agent: 'claude', 'request-id': 'r-json' }
+ const first = JSON.parse((await post('open-agent', { node, args, json: true })).body)
+ const again = JSON.parse((await post('open-agent', { node, args, json: true })).body)
+ expect(again).toEqual({ ...first, replayed: true, requestId: 'r-json' })
+ expect(handled).toHaveLength(1)
+ })
+
+ it('the handler never sees the id', async () => {
+ await post('open-agent', { node: freshNode(), args: { agent: 'claude', 'request-id': 'x1' }, cliRequestId: 'cli-1' })
+ expect(handled[0].args).toEqual({ agent: 'claude' })
+ })
+
+ it('the same id with different args is a conflict: refused, nothing runs', async () => {
+ const node = freshNode()
+ await post('open-agent', { node, args: { agent: 'claude', 'request-id': 'r1' } })
+ const clash = await post('open-agent', { node, args: { agent: 'codex', 'request-id': 'r1' } })
+ expect(clash.status).toBe(409)
+ expect(clash.body).toMatch(/^request-id-conflict: /)
+ expect(handled).toHaveLength(1)
+ })
+
+ it('a retry while the first call is still running is refused as in flight — still one node', async () => {
+ const node = freshNode()
+ let release!: () => void
+ next = () =>
+ new Promise((resolve) => {
+ release = () => resolve({ ok: true, message: 'opened slow-1' })
+ })
+ const args = { agent: 'claude', 'request-id': 'slow' }
+ const firstP = post('open-agent', { node, args })
+ await vi_waitFor(() => handled.length === 1)
+ const during = await post('open-agent', { node, args })
+ expect(during.status).toBe(409)
+ expect(during.body).toMatch(/^request-in-flight: /)
+ release()
+ expect((await firstP).body).toBe('opened slow-1\n')
+ const after = await post('open-agent', { node, args })
+ expect(after.body).toContain('opened slow-1')
+ expect(handled).toHaveLength(1)
+ })
+
+ it('distinct ids open two nodes', async () => {
+ const node = freshNode()
+ await post('open-agent', { node, args: { agent: 'claude', 'request-id': 'a' } })
+ await post('open-agent', { node, args: { agent: 'claude', 'request-id': 'b' } })
+ expect(handled).toHaveLength(2)
+ })
+
+ it("the shim's own per-run id dedupes a re-post of the same run, and two runs are two calls", async () => {
+ const node = freshNode()
+ await post('open-terminal', { node, cliRequestId: 'cli-aaaa' })
+ const repost = await post('open-terminal', { node, cliRequestId: 'cli-aaaa' })
+ expect(repost.body).toContain('opened n1')
+ await post('open-terminal', { node, cliRequestId: 'cli-bbbb' })
+ expect(handled).toHaveLength(2)
+ })
+
+ it('an explicit id wins over the per-run one', async () => {
+ const node = freshNode()
+ await post('open-terminal', { node, args: { 'request-id': 'mine' }, cliRequestId: 'cli-1' })
+ await post('open-terminal', { node, args: { 'request-id': 'mine' }, cliRequestId: 'cli-2' })
+ expect(handled).toHaveLength(1)
+ })
+
+ it('an unverified caller gets NO dedupe (never a shared bucket) and an explicit id says so', async () => {
+ const node = freshNode()
+ const args = { 'request-id': 'legacy-1' }
+ const a = await post('open-terminal', { node, args, verified: false })
+ const b = await post('open-terminal', { node, args, verified: false })
+ expect(handled).toHaveLength(2)
+ expect(a.body).toMatch(/request id ignored/i)
+ expect(b.body).toMatch(/request id ignored/i)
+ // The per-run id alone is silent: the caller never asked for anything.
+ const c = await post('open-terminal', { node, cliRequestId: 'cli-9', verified: false })
+ expect(c.body).not.toMatch(/request id ignored/i)
+ })
+
+ it('a dry run bypasses the ledger: the real call with the same id still runs', async () => {
+ const node = freshNode()
+ await post('open-agent', { node, args: { agent: 'claude', 'dry-run': '', 'request-id': 'd1' } })
+ const real = await post('open-agent', { node, args: { agent: 'claude', 'request-id': 'd1' } })
+ expect(real.body).not.toContain(REQUEST_ID_REPLAYED_LEAD)
+ expect(handled).toHaveLength(2)
+ })
+
+ it('an explicit id on a verb that creates nothing is refused before the handler', async () => {
+ const res = await post('rename', { node: freshNode(), args: { node: 'n1', title: 'x', 'request-id': 'r' } })
+ expect(res.status).toBe(400)
+ expect(res.body).toMatch(/^request-id-unsupported: /)
+ expect(handled).toHaveLength(0)
+ })
+
+ it('an invalid explicit id is refused before the handler', async () => {
+ const res = await post('open-terminal', { node: freshNode(), args: { 'request-id': 'no spaces please' } })
+ expect(res.status).toBe(400)
+ expect(res.body).toMatch(/^request-id-invalid: /)
+ expect(handled).toHaveLength(0)
+ })
+
+ it('an answer that could not say whether the effect happened settles as unknown; a late answer is then replayed', async () => {
+ const node = freshNode()
+ let late!: (r: { ok: boolean; message?: string }) => void
+ next = async (_cmd, onLate) => {
+ late = onLate!
+ return { ok: false, error: 'no answer within 120s', indeterminate: true }
+ }
+ const args = { branch: 'feat-x', 'request-id': 'wt-1' }
+ await post('open-worktree', { node, args })
+ const unknown = await post('open-worktree', { node, args })
+ expect(unknown.status).toBe(409)
+ expect(unknown.body).toMatch(/^request-outcome-unknown: /)
+ late({ ok: true, message: 'opened worktree feat-x' })
+ const replay = await post('open-worktree', { node, args })
+ expect(replay.status).toBe(200)
+ expect(replay.body).toContain('opened worktree feat-x')
+ expect(handled).toHaveLength(1)
+ })
+
+ it('a handler that throws leaves the id unknown: the retry is refused, not re-run', async () => {
+ const node = freshNode()
+ next = async () => {
+ throw new Error('renderer went away')
+ }
+ const args = { 'request-id': 'boom' }
+ await post('open-terminal', { node, args })
+ const retry = await post('open-terminal', { node, args })
+ expect(retry.body).toMatch(/^request-outcome-unknown: /)
+ expect(handled).toHaveLength(1)
+ })
+})
+
+async function vi_waitFor(cond: () => boolean): Promise<void> {
+ for (let i = 0; i < 200 && !cond(); i++) await new Promise((r) => setTimeout(r, 5))
+ if (!cond()) throw new Error('condition never became true')
+}
diff --git a/src/core/agents/hook-server.slowloris.test.ts b/src/core/agents/hook-server.slowloris.test.ts
index 4a98b9583..a976a2b11 100644
--- a/src/core/agents/hook-server.slowloris.test.ts
+++ b/src/core/agents/hook-server.slowloris.test.ts
@@ -1,7 +1,7 @@
// The slowloris guard is a RECEIVE-phase guard, and this pins that it stays one.
//
// A destructive /control/ verb (write, close) parks in the renderer for as long as the user takes
-// to answer the confirmation dialog — by design, up to the desktop's 120s `pendingControl` bound.
+// to answer the confirmation dialog — by design, up to the desktop's 120s control-forward bound.
// The 2s guard used to apply to the whole request lifetime, so it destroyed that socket mid-dialog:
// the sh shim reported "control endpoint unreachable" (curl exit 52 at ~2019ms) while a late
// confirm STILL delivered the text — the agent was told nothing happened when it had, and may
diff --git a/src/core/agents/hook-server.ts b/src/core/agents/hook-server.ts
index 56e3e4f48..6e36305d0 100644
--- a/src/core/agents/hook-server.ts
+++ b/src/core/agents/hook-server.ts
@@ -32,6 +32,17 @@ import {
type IdentityDecision
} from './node-identity-policy'
import { posixQuote } from '../../shared/ssh'
+import { dryRunRequested } from '../../shared/control-verbs'
+import {
+ ControlRequestLedger,
+ REQUEST_ID_RETRYABLE,
+ REQUEST_ID_UNVERIFIED_NOTE,
+ controlCallFingerprint,
+ requestIdGate,
+ requestIdOutcomeMessage,
+ requestIdReplayLine,
+ type LedgerClaim
+} from '../control-request-ledger'
// v2 advertises NODETERM_NODE_TOKEN_DIR so clients read their per-node capability from a file
// rather than receiving it in argv. Nothing consumes the posted version server-side, so the bump
@@ -43,10 +54,10 @@ const SLOWLORIS_MS = 2000
// phase (a client that dribbles bytes to pin a socket), not for the handler. But it is replaced
// with a HIGHER ceiling, never removed: a confirmation-gated control verb legitimately parks
// while the renderer waits for the user's answer, yet nothing may park forever. The desktop shell
-// bounds a control request at 120s (`pendingControl` in src/main/index.ts) — a bound that lives
-// OUTSIDE core, so a future core-side handler with no bound of its own would inherit an unbounded
-// socket if this were `setTimeout(0)`. 130s sits comfortably above that, so in the desktop the
-// handler's own timeout always wins and this only ever fires as a backstop.
+// bounds a control request at 120s (`createControlForwarder`, src/main/control-forward.ts) — a
+// bound that lives OUTSIDE core, so a future core-side handler with no bound of its own would
+// inherit an unbounded socket if this were `setTimeout(0)`. 130s sits comfortably above that, so
+// in the desktop the handler's own timeout always wins and this only ever fires as a backstop.
// Exported so a caller that parks on this socket can assert its own deadline sits under it by
// RUNNING the comparison rather than by copying the number into a comment (the delivery receipt,
// `agent-message.ts`, does exactly that).
@@ -122,18 +133,25 @@ function parseForm(body: string): Record<string, string> {
export function parseControlBody(
raw: string,
contentType: string
-): { nodeId: string; args: Record<string, string> } {
+): { nodeId: string; args: Record<string, string>; requestId?: string } {
if (contentType.includes('application/x-www-form-urlencoded')) {
const form = parseForm(raw)
const args: Record<string, string> = {}
for (const [k, v] of Object.entries(form)) {
if (k.startsWith('arg.') && k.length > 4) args[k.slice(4)] = v
}
- return { nodeId: form.nodeId ?? '', args }
+ // `requestId` is the id the shim generates once per RUN (not the caller's `--request-id`,
+ // which arrives as `arg.request-id`): what lets the shim's own endpoint-walk re-post be
+ // recognised as the same call. See control-request-ledger.ts.
+ return { nodeId: form.nodeId ?? '', args, ...(form.requestId ? { requestId: form.requestId } : {}) }
}
try {
- const parsed = JSON.parse(raw) as { nodeId?: string; args?: Record<string, string> }
- return { nodeId: parsed.nodeId ?? '', args: parsed.args ?? {} }
+ const parsed = JSON.parse(raw) as { nodeId?: string; args?: Record<string, string>; requestId?: unknown }
+ return {
+ nodeId: parsed.nodeId ?? '',
+ args: parsed.args ?? {},
+ ...(typeof parsed.requestId === 'string' && parsed.requestId ? { requestId: parsed.requestId } : {})
+ }
} catch {
return { nodeId: '', args: {} }
}
@@ -328,13 +346,26 @@ export class HookServer {
// claims a node ONLY when this is true — a `legacy`/warned caller opens a browser but owns
// nothing, so it can drive nothing. `browser-ownership-source.test.ts` guards the source.
verified: boolean
+ // Present only when the request CLAIMED a row in the request ledger. A handler that gives
+ // up before its effect is known (desktop main's 120s wait on the renderer) answers with
+ // `indeterminate: true` and may hand the real answer back here when it arrives: the
+ // ledger then replays it to a retry instead of refusing it as unknown.
+ onLateAnswer?: (reply: { ok: boolean; message?: string; result?: unknown; error?: string }) => void
}) => Promise<{
ok: boolean
message?: string
result?: unknown
error?: string
+ // The handler could not tell whether its effect happened (see control-request-ledger.ts).
+ indeterminate?: boolean
}>)
| null = null
+ /**
+ * Retried control calls (`--request-id`, or the shim's per-run id). In memory, like
+ * `provenNodes`: it records what happened on THIS process's socket, and a restart forgets it —
+ * see the header of control-request-ledger.ts for why that is the right trade.
+ */
+ private requestLedger = new ControlRequestLedger({ inFlightStaleMs: CONTROL_CEILING_MS })
// Context-link reads. Same shape as the control handler, but it answers with TEXT (a rendered
// transcript / summary / terminal capture) rather than acting on the canvas.
private contextLinkHandler:
@@ -653,10 +684,11 @@ export class HookServer {
}
if (reqUrl.pathname.startsWith('/control/')) {
const verb = decodeURIComponent(reqUrl.pathname.replace(/^\/control\//, ''))
- const { nodeId, args } = parseControlBody(
- await readBody(req),
- String(req.headers['content-type'] ?? '')
- )
+ const {
+ nodeId,
+ args: rawArgs,
+ requestId: cliRequestId
+ } = parseControlBody(await readBody(req), String(req.headers['content-type'] ?? ''))
// Body fully received: hand the socket from the receive-phase guard to the much larger
// handler ceiling. A destructive control verb parks here for as long as the user takes
// to answer the confirmation dialog, and the 2s guard used to destroy the socket mid-
@@ -664,6 +696,11 @@ export class HookServer {
// late confirm still delivered, so the agent was told nothing happened when it had.
req.setTimeout(CONTROL_CEILING_MS, () => req.destroy())
const wantsText = String(req.headers.accept ?? '').includes('text/plain')
+ // The request id is not an argument of any verb: take it out here, once, so no handler
+ // (and no parser that refuses flags it does not know) ever meets it. A bad EXPLICIT id is
+ // refused below, after identity — the order every other refusal on this route keeps.
+ const idGate = requestIdGate(verb, rawArgs, cliRequestId)
+ const args = idGate.kind === 'pass' ? idGate.args : rawArgs
// IDENTITY, and it runs BEFORE the handler: the promise of a refusal is that nothing
// happened, and a check after the handler is a check that happened too late.
const { verdict, decision } = this.identityGate(
@@ -717,12 +754,83 @@ export class HookServer {
}
return
}
- const result = this.controlHandler
- ? await this.controlHandler({ verb, nodeId, args, verified: verdict === 'verified' })
- : { ok: false, error: 'control unavailable' }
+ if (idGate.kind === 'refuse') {
+ const refusal = requestIdOutcomeMessage(idGate.outcome, { verb })
+ this.writeControlReply(res, wantsText, 400, { ok: false, error: idGate.outcome, message: refusal })
+ return
+ }
+ // RETRIED CALLS. Claimed HERE, before the handler, because from this instant the truthful
+ // answer to "did it happen?" is "it may have" — and here is the one place both shells'
+ // handlers pass. Keyed by the VERIFIED caller only: an unverified caller's id would share
+ // a bucket with anyone claiming its node id, so it gets no dedupe at all (and is told, when
+ // it asked for one). A dry run creates nothing, so it neither claims nor answers from a row.
+ let claim: LedgerClaim | undefined
+ let idNote = ''
+ if (idGate.requestId && !dryRunRequested(args)) {
+ if (verdict === 'verified') {
+ const decided = this.requestLedger.begin(
+ nodeId,
+ idGate.requestId,
+ controlCallFingerprint(verb, args)
+ )
+ if (decided.kind === 'replay') {
+ const stored = decided.reply
+ const lead = requestIdReplayLine(idGate.requestId, Date.now() - decided.firstRunAt)
+ if (wantsText) {
+ const text = stored.ok
+ ? stored.message ?? JSON.stringify(stored.result ?? {})
+ : stored.message ?? stored.error ?? 'control request failed'
+ res.writeHead(stored.ok ? 200 : 400, { 'content-type': 'text/plain; charset=utf-8' })
+ res.end(`${lead}\n${text}\n`)
+ } else {
+ res.writeHead(stored.ok ? 200 : 400, { 'content-type': 'application/json' })
+ res.end(JSON.stringify({ ...stored, replayed: true, requestId: idGate.requestId }))
+ }
+ return
+ }
+ if (decided.kind === 'refuse') {
+ const refusal = requestIdOutcomeMessage(decided.outcome, {
+ verb,
+ requestId: idGate.requestId,
+ ageMs: Date.now() - decided.firstRunAt
+ })
+ this.writeControlReply(res, wantsText, 409, {
+ ok: false,
+ error: decided.outcome,
+ message: refusal,
+ retryable: REQUEST_ID_RETRYABLE[decided.outcome]
+ })
+ return
+ }
+ claim = decided.claim
+ } else if (idGate.explicit) {
+ idNote = REQUEST_ID_UNVERIFIED_NOTE
+ }
+ }
+ const held = claim
+ let result: Awaited<ReturnType<NonNullable<HookServer['controlHandler']>>>
+ try {
+ result = this.controlHandler
+ ? await this.controlHandler({
+ verb,
+ nodeId,
+ args,
+ verified: verdict === 'verified',
+ ...(held ? { onLateAnswer: (late) => held.settleLate(late) } : {})
+ })
+ : { ok: false, error: 'control unavailable' }
+ } catch (e) {
+ // Nobody can say what a handler that threw got done: the id stays unknown, and its retry
+ // is refused rather than run a second time.
+ held?.settleUnknown()
+ throw e
+ }
+ held?.settle(result)
// Which note, not whether: an unmintable node warned with the restart line is sent round
// the same loop the refusal path already knows better than to send it round.
- const note = decision === 'allow-with-warning' ? this.identityWarningNote(nodeId) : ''
+ const note = [decision === 'allow-with-warning' ? this.identityWarningNote(nodeId) : '', idNote]
+ .filter(Boolean)
+ .join('\n')
// The POSIX-sh shim asks for text/plain: it has no JSON parser, so the server does the
// rendering the Node CLI used to do client-side. Everything else keeps the JSON shape.
if (wantsText) {
@@ -987,6 +1095,26 @@ export class HookServer {
return verifyNodeToken(this.nodeAuthSecretOrNull(), nodeId, provided) === 'verified'
}
+ /**
+ * One control reply in either dialect, for the route's own answers (the request-id outcomes):
+ * the sentence for the POSIX-sh shim, which prints one line and has no JSON parser; the whole
+ * object for a structured client, which keys on `error`.
+ */
+ private writeControlReply(
+ res: ServerResponse,
+ wantsText: boolean,
+ status: number,
+ body: { ok: false; error: string; message: string; retryable?: boolean }
+ ): void {
+ if (wantsText) {
+ res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' })
+ res.end(`${body.message}\n`)
+ return
+ }
+ res.writeHead(status, { 'content-type': 'application/json' })
+ res.end(JSON.stringify(body))
+ }
+
/**
* The identity gate for `/control/*` and `/context-link/*` — one call site for the verdict, the
* latch and the policy, so the two routes cannot drift into two different rules.
diff --git a/src/core/canvas-control-core.ts b/src/core/canvas-control-core.ts
index d63629a26..0fde6136d 100644
--- a/src/core/canvas-control-core.ts
+++ b/src/core/canvas-control-core.ts
@@ -32,6 +32,14 @@ import {
import { STATION_NOTICE_FROM } from '../shared/agents/agent-messaging'
import { PR_DEADLINE_DEFAULT_MS, PR_DEADLINE_MAX_MS, PR_WAIT_MAX, afterPrFlagRefusal } from '../shared/pr-wait'
import { ISSUE_BRANCH_SLUG_MAX, issueWorktreeBranch } from '../shared/issue-worktree'
+import {
+ REQUEST_ID_MAX_LENGTH,
+ REQUEST_ID_OUTCOME_GLOSS,
+ REQUEST_ID_REPLAYED_LEAD,
+ REQUEST_ID_RETRYABLE,
+ REQUEST_ID_VERBS,
+ REQUEST_LEDGER_TTL_MS
+} from './control-request-ledger'
/**
* The messaging verbs' retry guidance, RENDERED from `RETRYABLE` — the table is the source, and
@@ -455,6 +463,42 @@ function dryRunDocLines(): string[] {
]
}
+/**
+ * The `--request-id` paragraph both agent-facing bodies share, RENDERED from the ledger's tables
+ * (`control-request-ledger.ts`) — the verb set, the retry split, the glosses, the replay lead and
+ * the retention — the same derive-don't-retype rule as `messagingGuidanceLines`, so an outcome or a
+ * verb added there lands in the text an agent reads the day it is added.
+ */
+function requestIdDocLines(): string[] {
+ const yes: string[] = []
+ const no: string[] = []
+ for (const [kind, retryable] of Object.entries(REQUEST_ID_RETRYABLE)) {
+ const line = `\`${kind}\` (${REQUEST_ID_OUTCOME_GLOSS[kind as keyof typeof REQUEST_ID_OUTCOME_GLOSS]})`
+ ;(retryable ? yes : no).push(line)
+ }
+ const hours = Math.round(REQUEST_LEDGER_TTL_MS / 3_600_000)
+ return [
+ 'Retrying safely (`--request-id`):',
+ `- The verbs that create something (${[...REQUEST_ID_VERBS].join(', ')}) take`,
+ ` \`--request-id <id>\`: 1-${REQUEST_ID_MAX_LENGTH} letters, digits, \`.\`, \`_\`, \`:\` or \`-\`, starting with`,
+ ' a letter or digit. Give each operation its own id (a uuid, or a name like `wave2-reviewer-1`).',
+ '- When a call\'s reply never reached you — your tool call timed out, the connection dropped, the',
+ ' output was cut off — run the SAME command with the SAME id. nodeterm recognises it and, instead',
+ ' of opening a second node, returns the first call\'s reply, whose first line starts',
+ ` \`${REQUEST_ID_REPLAYED_LEAD}\`. Without an id, repeating an open whose reply you lost can open it twice.`,
+ '- A reply you DID see is the answer for that id, a refusal included: to try again after a',
+ ' refusal, or to open another node on purpose, use a NEW id. The same id with different flags is',
+ ' refused, and opens nothing.',
+ `- Retry with the SAME id after a short wait: ${yes.join('; ')}.`,
+ `- A same-id retry never clears these — fix the call: ${no.join('; ')}.`,
+ '- Without `--request-id` the CLI still tags each RUN with its own id, so its own automatic',
+ ' re-send to another endpoint never opens twice — but a second run is a second call. An id is',
+ ` matched only for a session whose node identity is verified (the reply says so otherwise), for ${hours} hours,`,
+ ' and not across an app restart. An SSH host keeps the CLI it got at its last connect: until that',
+ ' project reconnects, `--request-id` works there but runs carry no automatic id.'
+ ]
+}
+
/**
* The `--issue` SHAPE gate, shared by both shells: the Server Edition runs it inside
* `parseControlRequest`, and desktop main runs it in its control handler before forwarding (desktop
@@ -597,6 +641,8 @@ export function buildCanvasControlInstructions(shimPath: string): string {
'',
...dryRunDocLines(),
'',
+ ...requestIdDocLines(),
+ '',
'Server Edition ownership is fail-closed: every request requires verified node identity, and',
'a caller may mutate or message only nodes it opened during the current server run.',
'Restarting the server clears that creator proof; persisted nodes and queued launches are never',
@@ -957,6 +1003,17 @@ ${OWNED_ENDPOINT_FALLBACK_SH}
nt_out=$(mktemp 2>/dev/null || echo "/tmp/nodeterm-control.$$")
+# ONE id for this RUN, sent on every POST of it (see control-request-ledger.ts). The endpoint walk
+# below re-posts the same call when the first transport failed with no answer — but a request can
+# be read and executed and only the REPLY lost, and a second POST was then a second open. With the
+# id, the server recognises its own re-post and replays the first reply instead. A second RUN gets a
+# new id: repeating a command on purpose is a new call (an agent retrying after a lost reply passes
+# --request-id to say otherwise). Random bytes when the system has them, else pid + time — the
+# server ignores a malformed one rather than refusing the call.
+nt_request_id=$(od -An -N12 -tx1 /dev/urandom 2>/dev/null | tr -d ' \\n')
+[ -n "$nt_request_id" ] || nt_request_id="$$-$(date +%s 2>/dev/null)"
+nt_request_id="cli-$nt_request_id"
+
# One POST against the CURRENT endpoint vars — call as \`nt_control_post "$@"\` so the translated
# curl args reach it. Sets nt_code: '' when there is no transport to try at all, curl's
# %{http_code} otherwise ('000' = the transport failed before any HTTP answer). nt_had_transport
@@ -970,14 +1027,16 @@ nt_control_post() {
curl -sS -o "$nt_out" -w '%{http_code}' -X POST --config - \\
--unix-socket "$NODETERM_HOOK_SOCK" "http://localhost/control/$nt_verb" \\
-H "Accept: text/plain" \\
- --data-urlencode "nodeId=\${NODETERM_NODE_ID}" "$@" 2>/dev/null)
+ --data-urlencode "nodeId=\${NODETERM_NODE_ID}" \\
+ --data-urlencode "requestId=$nt_request_id" "$@" 2>/dev/null)
elif [ -n "$NODETERM_HOOK_PORT" ]; then
nt_had_transport=1
nt_code=$(nt_hook_headers |
curl -sS -o "$nt_out" -w '%{http_code}' -X POST --config - \\
"http://127.0.0.1:\${NODETERM_HOOK_PORT}/control/$nt_verb" \\
-H "Accept: text/plain" \\
- --data-urlencode "nodeId=\${NODETERM_NODE_ID}" "$@" 2>/dev/null)
+ --data-urlencode "nodeId=\${NODETERM_NODE_ID}" \\
+ --data-urlencode "requestId=$nt_request_id" "$@" 2>/dev/null)
fi
}
# Only a dead transport or an explicit wrong-owner (421) answer permits failover; 403 stays final.
@@ -1098,6 +1157,8 @@ value is allowed anywhere on the line, not only at the end.
${dryRunDocLines().join('\n')}
+${requestIdDocLines().join('\n')}
+
Server Edition ownership is fail-closed: every request requires verified node identity, and a
caller may mutate or message only nodes it opened during the current server run. Restarting
the server clears that creator proof; persisted nodes and queued launches are never auto-adopted,
diff --git a/src/core/control-request-ledger.test.ts b/src/core/control-request-ledger.test.ts
new file mode 100644
index 000000000..421fe681f
--- /dev/null
+++ b/src/core/control-request-ledger.test.ts
@@ -0,0 +1,294 @@
+import { describe, expect, it } from 'vitest'
+import {
+ ControlRequestLedger,
+ REQUEST_ID_MAX_LENGTH,
+ REQUEST_ID_RETRYABLE,
+ REQUEST_ID_VERBS,
+ controlCallFingerprint,
+ isValidRequestId,
+ requestIdGate
+} from './control-request-ledger'
+
+const reply = (message: string, ok = true) => ({ ok, message })
+
+describe('isValidRequestId', () => {
+ it('accepts uuids, hex and slugs', () => {
+ expect(isValidRequestId('7f3c2a9e-1b4d-4e8a-9c0f-2d5e6a7b8c9d')).toBe(true)
+ expect(isValidRequestId('cli-0a1b2c3d4e5f60718293a4b5')).toBe(true)
+ expect(isValidRequestId('wave2.reviewer:3_a')).toBe(true)
+ expect(isValidRequestId('a'.repeat(REQUEST_ID_MAX_LENGTH))).toBe(true)
+ })
+
+ it('refuses empty, overlong, leading punctuation and anything outside the charset', () => {
+ for (const bad of [
+ '',
+ 'a'.repeat(REQUEST_ID_MAX_LENGTH + 1),
+ '-leading-dash',
+ '.dot',
+ 'has space',
+ 'new\nline',
+ 'slash/id',
+ 'semi;colon',
+ '$(id)',
+ 'ünicode'
+ ]) {
+ expect(isValidRequestId(bad), JSON.stringify(bad)).toBe(false)
+ }
+ })
+})
+
+describe('controlCallFingerprint', () => {
+ it('ignores key order and the request id itself', () => {
+ const a = controlCallFingerprint('open-agent', { agent: 'claude', prompt: 'x', 'request-id': 'r1' })
+ const b = controlCallFingerprint('open-agent', { prompt: 'x', agent: 'claude' })
+ expect(a).toBe(b)
+ })
+
+ it('differs by verb, by value and by the presence of a flag', () => {
+ const base = controlCallFingerprint('open-agent', { agent: 'claude' })
+ expect(controlCallFingerprint('open-claude', { agent: 'claude' })).not.toBe(base)
+ expect(controlCallFingerprint('open-agent', { agent: 'codex' })).not.toBe(base)
+ expect(controlCallFingerprint('open-agent', { agent: 'claude', count: '2' })).not.toBe(base)
+ // An empty flag is a flag: `--verbose` (arg.verbose=) is not the same call as no flag.
+ expect(controlCallFingerprint('open-agent', { agent: 'claude', verbose: '' })).not.toBe(base)
+ })
+
+ it('cannot be confused by a separator inside a value', () => {
+ expect(controlCallFingerprint('open-agent', { a: 'b', c: 'd' })).not.toBe(
+ controlCallFingerprint('open-agent', { a: 'b","c":"d' })
+ )
+ })
+})
+
+describe('ControlRequestLedger', () => {
+ const clock = () => {
+ let t = 1_000_000
+ return { now: () => t, advance: (ms: number) => (t += ms) }
+ }
+
+ it('runs the first call, then replays its WHOLE reply for the same id instead of running again', () => {
+ const c = clock()
+ const ledger = new ControlRequestLedger({ now: c.now })
+ const first = ledger.begin('src', 'r1', 'fp')
+ expect(first.kind).toBe('run')
+ if (first.kind !== 'run') return
+ const original = { ok: true, message: 'opened n1', result: { ids: ['n1'], queued: false } }
+ first.claim.settle(original)
+ c.advance(5_000)
+ const again = ledger.begin('src', 'r1', 'fp')
+ expect(again).toEqual({ kind: 'replay', reply: original, firstRunAt: 1_000_000 })
+ })
+
+ it('a refusal the caller already got is replayed too — the same id never runs twice', () => {
+ const ledger = new ControlRequestLedger()
+ const first = ledger.begin('src', 'r1', 'fp')
+ if (first.kind !== 'run') throw new Error('expected run')
+ first.claim.settle(reply('open-agent requires --agent <id>', false))
+ const again = ledger.begin('src', 'r1', 'fp')
+ expect(again.kind).toBe('replay')
+ if (again.kind === 'replay') expect(again.reply.ok).toBe(false)
+ })
+
+ it('the same id with a different call is a conflict — in flight AND after it settled', () => {
+ const ledger = new ControlRequestLedger()
+ const first = ledger.begin('src', 'r1', 'fp-a')
+ if (first.kind !== 'run') throw new Error('expected run')
+ expect(ledger.begin('src', 'r1', 'fp-b')).toMatchObject({ kind: 'refuse', outcome: 'request-id-conflict' })
+ first.claim.settle(reply('ok'))
+ expect(ledger.begin('src', 'r1', 'fp-b')).toMatchObject({ kind: 'refuse', outcome: 'request-id-conflict' })
+ })
+
+ it('a retry while the first call is still running is refused as in flight, never re-run', () => {
+ const c = clock()
+ const ledger = new ControlRequestLedger({ now: c.now, inFlightStaleMs: 60_000 })
+ const first = ledger.begin('src', 'r1', 'fp')
+ expect(first.kind).toBe('run')
+ c.advance(3_000)
+ expect(ledger.begin('src', 'r1', 'fp')).toEqual({
+ kind: 'refuse',
+ outcome: 'request-in-flight',
+ firstRunAt: 1_000_000
+ })
+ })
+
+ it('an in-flight call older than the stale bound answers as outcome-unknown, still never re-run', () => {
+ const c = clock()
+ const ledger = new ControlRequestLedger({ now: c.now, inFlightStaleMs: 60_000 })
+ ledger.begin('src', 'r1', 'fp')
+ c.advance(60_001)
+ expect(ledger.begin('src', 'r1', 'fp')).toMatchObject({ kind: 'refuse', outcome: 'request-outcome-unknown' })
+ })
+
+ it('an indeterminate answer settles as unknown; a late answer then replaces it (monotone upward)', () => {
+ const ledger = new ControlRequestLedger()
+ const first = ledger.begin('src', 'r1', 'fp')
+ if (first.kind !== 'run') throw new Error('expected run')
+ first.claim.settle({ ok: false, error: 'no answer within 120s', indeterminate: true })
+ expect(ledger.begin('src', 'r1', 'fp')).toMatchObject({ kind: 'refuse', outcome: 'request-outcome-unknown' })
+ first.claim.settleLate({ ok: true, message: 'opened worktree' })
+ expect(ledger.begin('src', 'r1', 'fp')).toMatchObject({
+ kind: 'replay',
+ reply: { ok: true, message: 'opened worktree' }
+ })
+ })
+
+ it('settlement is monotone: nothing overwrites a settled row, and a late unknown is a no-op', () => {
+ const ledger = new ControlRequestLedger()
+ const first = ledger.begin('src', 'r1', 'fp')
+ if (first.kind !== 'run') throw new Error('expected run')
+ first.claim.settle(reply('opened n1'))
+ first.claim.settleUnknown()
+ first.claim.settle({ ok: false, error: 'late', indeterminate: true })
+ first.claim.settleLate(reply('something else'))
+ first.claim.settle(reply('second settle'))
+ expect(ledger.begin('src', 'r1', 'fp')).toMatchObject({ kind: 'replay', reply: { message: 'opened n1' } })
+ })
+
+ it('a handler that threw leaves the row unknown', () => {
+ const ledger = new ControlRequestLedger()
+ const first = ledger.begin('src', 'r1', 'fp')
+ if (first.kind !== 'run') throw new Error('expected run')
+ first.claim.settleUnknown()
+ expect(ledger.begin('src', 'r1', 'fp')).toMatchObject({ kind: 'refuse', outcome: 'request-outcome-unknown' })
+ })
+
+ it('distinct ids run independently, and so does the same id from another caller', () => {
+ const ledger = new ControlRequestLedger()
+ expect(ledger.begin('src', 'r1', 'fp').kind).toBe('run')
+ expect(ledger.begin('src', 'r2', 'fp').kind).toBe('run')
+ expect(ledger.begin('other', 'r1', 'fp').kind).toBe('run')
+ })
+
+ it('a row older than the retention window is forgotten', () => {
+ const c = clock()
+ const ledger = new ControlRequestLedger({ now: c.now, ttlMs: 10_000 })
+ const first = ledger.begin('src', 'r1', 'fp')
+ if (first.kind !== 'run') throw new Error('expected run')
+ first.claim.settle(reply('opened'))
+ c.advance(10_001)
+ expect(ledger.begin('src', 'r1', 'fp').kind).toBe('run')
+ })
+
+ it('caps rows per caller by evicting the oldest SETTLED one, never one still in flight', () => {
+ const ledger = new ControlRequestLedger({ perCallerMax: 3 })
+ const inFlight = ledger.begin('src', 'r0', 'fp') // stays in flight throughout
+ expect(inFlight.kind).toBe('run')
+ for (const id of ['r1', 'r2', 'r3']) {
+ const d = ledger.begin('src', id, 'fp')
+ if (d.kind !== 'run') throw new Error('expected run')
+ d.claim.settle(reply(id))
+ }
+ // r1 was the oldest settled row, so it went; the in-flight r0 did not.
+ expect(ledger.begin('src', 'r0', 'fp').kind).toBe('refuse')
+ expect(ledger.begin('src', 'r2', 'fp').kind).toBe('replay')
+ expect(ledger.begin('src', 'r3', 'fp').kind).toBe('replay')
+ expect(ledger.begin('src', 'r1', 'fp').kind).toBe('run')
+ // Another caller's rows never count against this one's cap.
+ expect(ledger.begin('other', 'x', 'fp').kind).toBe('run')
+ })
+
+ it('caps rows globally the same way', () => {
+ const ledger = new ControlRequestLedger({ globalMax: 2 })
+ for (const [caller, id] of [['a', 'r1'], ['b', 'r2'], ['c', 'r3']]) {
+ const d = ledger.begin(caller, id, 'fp')
+ if (d.kind !== 'run') throw new Error('expected run')
+ d.claim.settle(reply(id))
+ }
+ expect(ledger.begin('a', 'r1', 'fp').kind).toBe('run')
+ expect(ledger.begin('c', 'r3', 'fp').kind).toBe('replay')
+ })
+
+ it("a claim can only settle ITS row — never a newer row that reused the key after it was forgotten", () => {
+ const c = clock()
+ const ledger = new ControlRequestLedger({ now: c.now, ttlMs: 10_000 })
+ const old = ledger.begin('src', 'r1', 'fp')
+ if (old.kind !== 'run') throw new Error('expected run')
+ c.advance(10_001)
+ const fresh = ledger.begin('src', 'r1', 'fp')
+ expect(fresh.kind).toBe('run')
+ old.claim.settle(reply('from the forgotten attempt'))
+ expect(ledger.begin('src', 'r1', 'fp')).toMatchObject({ kind: 'refuse', outcome: 'request-in-flight' })
+ })
+})
+
+describe('requestIdGate', () => {
+ it('an explicit --request-id wins over the CLI-generated one and is stripped from the args', () => {
+ expect(requestIdGate('open-agent', { agent: 'claude', 'request-id': 'mine-1' }, 'cli-abc')).toEqual({
+ kind: 'pass',
+ args: { agent: 'claude' },
+ requestId: 'mine-1',
+ explicit: true
+ })
+ })
+
+ it('the CLI-generated id is used when no explicit one is passed', () => {
+ expect(requestIdGate('open-agent', { agent: 'claude' }, 'cli-abc')).toEqual({
+ kind: 'pass',
+ args: { agent: 'claude' },
+ requestId: 'cli-abc',
+ explicit: false
+ })
+ })
+
+ it('an invalid explicit id is refused before anything runs', () => {
+ expect(requestIdGate('open-agent', { agent: 'claude', 'request-id': 'no spaces' }, undefined)).toMatchObject({
+ kind: 'refuse',
+ outcome: 'request-id-invalid'
+ })
+ expect(requestIdGate('open-agent', { 'request-id': '' }, undefined)).toMatchObject({
+ kind: 'refuse',
+ outcome: 'request-id-invalid'
+ })
+ })
+
+ it('an explicit id on a verb that creates nothing is refused, never silently ignored', () => {
+ expect(requestIdGate('rename', { node: 'n1', title: 't', 'request-id': 'r1' }, undefined)).toMatchObject({
+ kind: 'refuse',
+ outcome: 'request-id-unsupported'
+ })
+ })
+
+ it('a CLI-generated id is ignored — never refused — when it is malformed or the verb creates nothing', () => {
+ expect(requestIdGate('open-agent', { agent: 'claude' }, 'bad id')).toEqual({
+ kind: 'pass',
+ args: { agent: 'claude' },
+ explicit: false
+ })
+ expect(requestIdGate('rename', { node: 'n1' }, 'cli-abc')).toEqual({
+ kind: 'pass',
+ args: { node: 'n1' },
+ explicit: false
+ })
+ })
+
+ it('covers every verb that creates a node or a worktree', () => {
+ for (const verb of [
+ 'open-terminal',
+ 'open-claude',
+ 'open-agent',
+ 'spawn-team',
+ 'verify',
+ 'open-worktree',
+ 'branch',
+ 'show-image',
+ 'show-video',
+ 'show-web',
+ 'open-browser',
+ 'group'
+ ]) {
+ expect(REQUEST_ID_VERBS.has(verb), verb).toBe(true)
+ }
+ })
+})
+
+describe('REQUEST_ID_RETRYABLE', () => {
+ it('in-flight and unknown are retryable with the same id; the others never clear on their own', () => {
+ expect(REQUEST_ID_RETRYABLE).toEqual({
+ 'request-in-flight': true,
+ 'request-outcome-unknown': true,
+ 'request-id-conflict': false,
+ 'request-id-invalid': false,
+ 'request-id-unsupported': false
+ })
+ })
+})
diff --git a/src/core/control-request-ledger.ts b/src/core/control-request-ledger.ts
new file mode 100644
index 000000000..e8f0bccd4
--- /dev/null
+++ b/src/core/control-request-ledger.ts
@@ -0,0 +1,384 @@
+// A retried canvas-control call must not open a second node.
+//
+// WHY THIS EXISTS. An orchestrating agent opens stations with the control shim, and the reply to
+// that call can be lost while the call itself went through: the agent's own tool call is killed
+// (a Bash tool call dies at about two minutes while a slow host or a confirm holds the POST), the
+// ssh tunnel drops mid-reply, or the shim's endpoint walk re-posts to another candidate after a
+// transport that failed AFTER the request was read. The agent reasonably runs the same command
+// again, and before this module a second agent, a second worktree, a second team was the answer.
+//
+// THE RULES, each for a reason:
+// - A call may carry an operation id (`--request-id`, or the one the shim generates per RUN so
+// its own re-posts are covered for an agent that never read the docs). Rows are keyed
+// (caller node, id), and the caller is the VERIFIED node only: an unverified caller gets no
+// dedupe rather than a shared bucket, where two nodes could collide on each other's ids.
+// - A fingerprint of what the call DOES (verb + args, minus the id itself) is stored with the
+// row. The same id with a different fingerprint is a conflict, refused: reusing an id for a
+// different call is a bug in the caller, and silently answering with the first call's reply
+// would hide it.
+// - The row is CLAIMED before the handler runs, because from that instant the truthful answer
+// to "did this happen?" is "it may have". A retry of a claimed row is refused, never run.
+// - A row settles with the WHOLE reply the handler gave, and a replay returns that reply, not
+// what the same call would do now. A refusal is a reply too: the same id never runs twice.
+// - A handler that could not tell whether its effect happened (desktop main gave up waiting on
+// the renderer; the handler threw) settles the row as UNKNOWN. That is still refused, and
+// settlement only ever moves UP: a late answer may replace unknown, nothing replaces a reply.
+// - Retention is bounded: 24 h, and a cap per caller and in total. An in-flight row is never
+// evicted by a cap (evicting it would let its own retry run a second time).
+//
+// PROCESS MEMORY, deliberately. The ledger lives in the one process that executes the call (the
+// hook server's `/control/` route, which BOTH shells pass through). An app restart between the
+// effect and the retry empties it, and that retry runs again. That is the case that matters least:
+// a restart inside the seconds-to-minutes between a lost reply and its retry is rare, and it also
+// rotates the endpoint the shim posts to, so the shim's own re-post never reaches the new process
+// with the old id anyway. Persisting it would mean a store, a schema and atomic writes on every
+// control call for that corner.
+//
+// Pure: no clock, no I/O, no network. The route wires it (src/core/agents/hook-server.ts).
+import { createHash } from 'node:crypto'
+
+/**
+ * The verbs that CREATE something — a node, a team, a worktree, a frame. The ones this module
+ * exists for. The others are left out on purpose, each for its own reason:
+ * - reads (`list`, `board`, `settings --get`, `browser --read`): nothing to protect, and a
+ * replay would serve a stale snapshot — and, for `browser --cookies`, keep a page's cookies in
+ * memory for a day;
+ * - verbs that are idempotent by nature (`close`, `rename`, `color`, `assign`, `move`,
+ * `open-project`) — running one twice lands where running it once did;
+ * - the human-confirmed and rate-limited ones (`write`, `send`/`reply`/`notify`, `settings`,
+ * `report-issue`), which already carry their own brake; widening the set to them is a
+ * separate decision.
+ * An explicit `--request-id` on a verb outside the set is REFUSED rather than ignored: an agent
+ * that believes its `write` is protected when it is not is the failure this flag exists to end.
+ */
+export const REQUEST_ID_VERBS: ReadonlySet<string> = new Set([
+ 'open-terminal',
+ 'open-claude',
+ 'open-agent',
+ 'spawn-team',
+ 'verify',
+ 'open-worktree',
+ 'branch',
+ 'show-image',
+ 'show-video',
+ 'show-web',
+ 'open-browser',
+ 'group'
+])
+
+export const REQUEST_ID_MAX_LENGTH = 64
+// A leading letter or digit keeps an id from ever reading as a flag (`-x`) or a path (`.x`); the
+// charset is what a uuid, a hex token or a hand-written slug (`wave2.reviewer:3`) needs and nothing
+// that could mean something to a shell, a URL or a log line.
+const REQUEST_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/
+
+export function isValidRequestId(raw: string): boolean {
+ return raw.length > 0 && raw.length <= REQUEST_ID_MAX_LENGTH && REQUEST_ID_RE.test(raw)
+}
+
+export type RequestIdOutcome =
+ | 'request-in-flight'
+ | 'request-outcome-unknown'
+ | 'request-id-conflict'
+ | 'request-id-invalid'
+ | 'request-id-unsupported'
+
+/**
+ * Whether retrying the SAME command with the SAME id can change the answer. Data, not prose: the
+ * agent-facing text is RENDERED from this table (`requestIdDocLines`), the same rule the messaging
+ * outcomes follow, so a new outcome lands in the docs the day it is added.
+ * - in flight: the first call's reply is still coming, so a later retry gets it;
+ * - unknown: a late answer may still arrive (desktop main hands one back after its own timeout),
+ * so a later retry can get it — and when it never does, the answer tells the caller to `list`;
+ * - the rest are the caller's mistake and never clear on their own.
+ */
+export const REQUEST_ID_RETRYABLE: Record<RequestIdOutcome, boolean> = {
+ 'request-in-flight': true,
+ 'request-outcome-unknown': true,
+ 'request-id-conflict': false,
+ 'request-id-invalid': false,
+ 'request-id-unsupported': false
+}
+
+/** What each outcome means, in the words the agent-facing docs render (never re-typed there). */
+export const REQUEST_ID_OUTCOME_GLOSS: Record<RequestIdOutcome, string> = {
+ 'request-in-flight': 'the first call with that id is still running',
+ 'request-outcome-unknown':
+ 'the first call ended without a confirmed answer, so it may have taken effect — if it keeps ' +
+ 'saying this, run `list` before opening anything again',
+ 'request-id-conflict': 'the id was already used for a different call',
+ 'request-id-invalid': `the id is not 1-${REQUEST_ID_MAX_LENGTH} letters, digits, \`.\`, \`_\`, \`:\` or \`-\``,
+ 'request-id-unsupported': 'the verb creates nothing and takes no id'
+}
+
+/** How long ago, in the unit a reader would use. */
+function ago(ms: number): string {
+ const s = Math.max(0, Math.round(ms / 1000))
+ if (s < 120) return `${s}s`
+ const m = Math.round(s / 60)
+ if (m < 120) return `${m}m`
+ return `${Math.round(m / 60)}h`
+}
+
+/** The first line of a replayed reply. Exported so tests (and the docs) quote it, never re-type it. */
+export const REQUEST_ID_REPLAYED_LEAD = 'replayed:'
+
+export function requestIdReplayLine(requestId: string, ageMs: number): string {
+ return (
+ `${REQUEST_ID_REPLAYED_LEAD} this is the reply to request ${requestId}, first run ${ago(ageMs)} ago — ` +
+ 'nothing new was run.'
+ )
+}
+
+/** Appended when the caller passed `--request-id` but its node identity is not verified. */
+export const REQUEST_ID_UNVERIFIED_NOTE =
+ 'request id ignored: this session\'s node identity is not verified, so a retry cannot be matched ' +
+ 'to this call — run `list` before repeating it.'
+
+/**
+ * One line per outcome, the machine name first so the text dialect (which carries no `error`
+ * field) still names it. Every one says what did NOT happen, because the question the caller is
+ * asking after a lost reply is "did I just open a second one?".
+ */
+export function requestIdOutcomeMessage(
+ outcome: RequestIdOutcome,
+ ctx: { requestId?: string; verb: string; ageMs?: number }
+): string {
+ const id = ctx.requestId ?? ''
+ const since = ctx.ageMs === undefined ? '' : ` (first run ${ago(ctx.ageMs)} ago)`
+ switch (outcome) {
+ case 'request-in-flight':
+ return (
+ `request-in-flight: request ${id} is still running${since} — nothing new was started. ` +
+ 'Run the same command with the same --request-id again in a few seconds to get its reply.'
+ )
+ case 'request-outcome-unknown':
+ return (
+ `request-outcome-unknown: request ${id} ended without a confirmed answer${since}, so it MAY ` +
+ 'have taken effect — nothing new was started. Retry the same command with the same ' +
+ '--request-id in a minute: an answer that arrives late is returned then. If it keeps saying ' +
+ 'this, run `list` before opening anything again, and use a new --request-id only for ' +
+ 'something that is not there.'
+ )
+ case 'request-id-conflict':
+ return (
+ `request-id-conflict: request id ${id} was already used for a different call${since} — ` +
+ 'nothing was done. Use a new --request-id for a new call; reuse an id only to retry the ' +
+ 'exact same command.'
+ )
+ case 'request-id-invalid':
+ return (
+ `request-id-invalid: --request-id must be 1-${REQUEST_ID_MAX_LENGTH} letters, digits, '.', ` +
+ "'_', ':' or '-', starting with a letter or digit — nothing was done."
+ )
+ case 'request-id-unsupported':
+ return (
+ `request-id-unsupported: --request-id applies only to the verbs that create something ` +
+ `(${[...REQUEST_ID_VERBS].join(', ')}); ${ctx.verb} does not take it — nothing was done.`
+ )
+ }
+}
+
+/** A handler reply, as stored and replayed. `indeterminate` marks one that could not say whether
+ * the effect happened; it settles the row as unknown and is never replayed as an answer. */
+export interface ControlReply {
+ ok: boolean
+ message?: string
+ result?: unknown
+ error?: string
+ indeterminate?: boolean
+}
+
+/**
+ * What the call DOES: the verb plus every arg except the id itself, in a canonical order. Values
+ * are compared literally — `--count 1` and no `--count` are different calls, because deciding they
+ * are the same would mean re-implementing every verb's defaults here. JSON of an array of pairs,
+ * so no value can forge a boundary between two keys.
+ */
+export function controlCallFingerprint(verb: string, args: Record<string, string>): string {
+ const entries = Object.entries(args)
+ .filter(([k]) => k !== 'request-id')
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+ return createHash('sha256').update(JSON.stringify([verb, entries])).digest('hex')
+}
+
+export type RequestIdGate =
+ | { kind: 'pass'; args: Record<string, string>; requestId?: string; explicit: boolean }
+ | { kind: 'refuse'; outcome: 'request-id-invalid' | 'request-id-unsupported' }
+
+/**
+ * Decide which id (if any) a control call carries. `args['request-id']` is the caller's explicit
+ * `--request-id`; `cliRequestId` is the one the shim generated for this run. The explicit id wins.
+ * The id is always stripped from the args a handler sees: no verb reads it, and a parser that
+ * refuses flags it does not know must never meet it.
+ *
+ * Asymmetric on purpose: a bad EXPLICIT id is refused (the caller asked for protection it would
+ * not get), a bad CLI-generated one is ignored (a shim whose random source failed must not make
+ * every open fail).
+ */
+export function requestIdGate(
+ verb: string,
+ args: Record<string, string>,
+ cliRequestId: string | undefined
+): RequestIdGate {
+ const { 'request-id': explicitId, ...rest } = args
+ if (explicitId !== undefined) {
+ if (!isValidRequestId(explicitId)) return { kind: 'refuse', outcome: 'request-id-invalid' }
+ if (!REQUEST_ID_VERBS.has(verb)) return { kind: 'refuse', outcome: 'request-id-unsupported' }
+ return { kind: 'pass', args: rest, requestId: explicitId, explicit: true }
+ }
+ if (cliRequestId !== undefined && isValidRequestId(cliRequestId) && REQUEST_ID_VERBS.has(verb)) {
+ return { kind: 'pass', args: rest, requestId: cliRequestId, explicit: false }
+ }
+ return { kind: 'pass', args: rest, explicit: false }
+}
+
+/** Settles the row a `begin` claimed — and only that row (see `ControlRequestLedger.begin`). */
+export interface LedgerClaim {
+ /** The handler answered. An `indeterminate` answer settles the row as unknown. */
+ settle(reply: ControlReply): void
+ /** The handler threw: nobody knows what happened. */
+ settleUnknown(): void
+ /** An answer that arrived after the row was already settled as unknown. */
+ settleLate(reply: ControlReply): void
+}
+
+export type LedgerDecision =
+ | { kind: 'run'; claim: LedgerClaim }
+ | { kind: 'replay'; reply: ControlReply; firstRunAt: number }
+ | {
+ kind: 'refuse'
+ outcome: 'request-in-flight' | 'request-outcome-unknown' | 'request-id-conflict'
+ firstRunAt: number
+ }
+
+interface Row {
+ caller: string
+ fingerprint: string
+ claimedAt: number
+ touchedAt: number
+ state: 'in-flight' | 'settled' | 'unknown'
+ reply?: ControlReply
+}
+
+export const REQUEST_LEDGER_TTL_MS = 24 * 60 * 60 * 1000
+export const REQUEST_LEDGER_PER_CALLER_MAX = 256
+export const REQUEST_LEDGER_GLOBAL_MAX = 4096
+
+export interface ControlRequestLedgerOptions {
+ now?: () => number
+ ttlMs?: number
+ perCallerMax?: number
+ globalMax?: number
+ /** An in-flight row older than this answers as unknown (still refused). The route passes the
+ * socket ceiling, past which the caller's own request has already been cut off. */
+ inFlightStaleMs?: number
+}
+
+export class ControlRequestLedger {
+ // Insertion order = claim order, which is what the caps evict by.
+ private rows = new Map<string, Row>()
+ private perCaller = new Map<string, number>()
+ private readonly now: () => number
+ private readonly ttlMs: number
+ private readonly perCallerMax: number
+ private readonly globalMax: number
+ private readonly inFlightStaleMs: number
+
+ constructor(opts: ControlRequestLedgerOptions = {}) {
+ this.now = opts.now ?? Date.now
+ this.ttlMs = opts.ttlMs ?? REQUEST_LEDGER_TTL_MS
+ this.perCallerMax = opts.perCallerMax ?? REQUEST_LEDGER_PER_CALLER_MAX
+ this.globalMax = opts.globalMax ?? REQUEST_LEDGER_GLOBAL_MAX
+ this.inFlightStaleMs = opts.inFlightStaleMs ?? 10 * 60 * 1000
+ }
+
+ /**
+ * Look the (caller, id) pair up and either CLAIM it for this call or answer from the row.
+ * Synchronous on purpose: the look-up and the claim happen with no await between them, so two
+ * requests arriving together cannot both be told to run.
+ */
+ begin(caller: string, requestId: string, fingerprint: string): LedgerDecision {
+ const now = this.now()
+ this.prune(now)
+ const key = `${caller}\u0000${requestId}`
+ const found = this.rows.get(key)
+ if (found) {
+ const firstRunAt = found.claimedAt
+ if (found.fingerprint !== fingerprint) return { kind: 'refuse', outcome: 'request-id-conflict', firstRunAt }
+ if (found.state === 'settled' && found.reply) return { kind: 'replay', reply: found.reply, firstRunAt }
+ if (found.state === 'in-flight' && now - found.claimedAt <= this.inFlightStaleMs) {
+ return { kind: 'refuse', outcome: 'request-in-flight', firstRunAt }
+ }
+ return { kind: 'refuse', outcome: 'request-outcome-unknown', firstRunAt }
+ }
+ const row: Row = { caller, fingerprint, claimedAt: now, touchedAt: now, state: 'in-flight' }
+ this.rows.set(key, row)
+ this.perCaller.set(caller, (this.perCaller.get(caller) ?? 0) + 1)
+ this.enforceCaps(caller)
+ // The claim closes over THIS row object, never the key: a row forgotten by retention or a cap
+ // and then re-claimed under the same key is a different object, so a late answer from the
+ // forgotten call can only ever write to the detached row nobody reads.
+ const store = (reply: ControlReply): void => {
+ const { indeterminate: _drop, ...kept } = reply
+ row.reply = kept
+ row.state = 'settled'
+ row.touchedAt = this.now()
+ }
+ return {
+ kind: 'run',
+ claim: {
+ settle: (reply) => {
+ if (row.state !== 'in-flight') return
+ if (reply.indeterminate) {
+ row.state = 'unknown'
+ row.touchedAt = this.now()
+ return
+ }
+ store(reply)
+ },
+ settleUnknown: () => {
+ if (row.state !== 'in-flight') return
+ row.state = 'unknown'
+ row.touchedAt = this.now()
+ },
+ settleLate: (reply) => {
+ if (row.state !== 'unknown' || reply.indeterminate) return
+ store(reply)
+ }
+ }
+ }
+ }
+
+ /** Test seam: how many rows are held. */
+ sizeForTests(): number {
+ return this.rows.size
+ }
+
+ private prune(now: number): void {
+ for (const [key, row] of this.rows) {
+ if (now - row.touchedAt > this.ttlMs) this.drop(key, row)
+ }
+ }
+
+ private enforceCaps(caller: string): void {
+ if ((this.perCaller.get(caller) ?? 0) > this.perCallerMax) this.evictOldest((row) => row.caller === caller)
+ if (this.rows.size > this.globalMax) this.evictOldest(() => true)
+ }
+
+ private evictOldest(match: (row: Row) => boolean): void {
+ for (const [key, row] of this.rows) {
+ if (row.state !== 'in-flight' && match(row)) {
+ this.drop(key, row)
+ return
+ }
+ }
+ }
+
+ private drop(key: string, row: Row): void {
+ this.rows.delete(key)
+ const n = (this.perCaller.get(row.caller) ?? 1) - 1
+ if (n > 0) this.perCaller.set(row.caller, n)
+ else this.perCaller.delete(row.caller)
+ }
+}
diff --git a/src/main/canvas-control-core.test.ts b/src/main/canvas-control-core.test.ts
index 9c08800ea..ba94005ab 100644
--- a/src/main/canvas-control-core.test.ts
+++ b/src/main/canvas-control-core.test.ts
@@ -14,6 +14,13 @@ import {
CODEX_SANDBOX_RETRY_LINE
} from '../core/agents/hook-sandbox-hint-sh'
import { RETRYABLE } from '../core/agents/agent-message-decide'
+import {
+ REQUEST_ID_MAX_LENGTH,
+ REQUEST_ID_OUTCOME_GLOSS,
+ REQUEST_ID_REPLAYED_LEAD,
+ REQUEST_ID_RETRYABLE,
+ REQUEST_ID_VERBS
+} from '../core/control-request-ledger'
import { BOARD_COMMENT_FROM_PREFIX, BOARD_COMMENT_REPLY_TO } from '../shared/board-comment'
import {
STATION_NOTICE_COMMON_OPTIONS,
@@ -690,6 +697,40 @@ describe('parseControlRequest', () => {
}
})
+ // --- retried calls (src/core/control-request-ledger.ts) ----------------------------------------
+ // The request-id contract an agent reads must be the TABLES': which verbs take an id, which
+ // outcomes a same-id retry can change, what a replay looks like. Rendered, never re-typed, so a
+ // verb or an outcome added to the ledger lands in both bodies the day it is added.
+ it('both bodies document --request-id, rendered from the ledger tables', () => {
+ for (const [name, body] of [
+ ['skill', buildCanvasSkillBody('/x/shim.sh')],
+ ['instructions', buildCanvasControlInstructions('/x/shim.sh')]
+ ] as const) {
+ const at = body.indexOf('Retrying safely')
+ expect(at, `${name}: the section exists`).toBeGreaterThan(-1)
+ const section = body.slice(at, body.indexOf('\n\n', at))
+ for (const verb of REQUEST_ID_VERBS) expect(section, `${name}: ${verb}`).toContain(verb)
+ expect(section).toContain(`1-${REQUEST_ID_MAX_LENGTH}`)
+ expect(section).toContain(`\`${REQUEST_ID_REPLAYED_LEAD}\``)
+ expect(section).toMatch(/SAME command with the SAME id/)
+ expect(section).toMatch(/refusal included/)
+ expect(section).toMatch(/NEW id/)
+ expect(section).toMatch(/verified/)
+ expect(section).toMatch(/24 hours/)
+ const yesAt = section.indexOf('Retry with the SAME id after a short wait')
+ const noAt = section.indexOf('A same-id retry never clears these')
+ expect(yesAt, name).toBeGreaterThan(-1)
+ expect(noAt, name).toBeGreaterThan(yesAt)
+ const yes = section.slice(yesAt, noAt)
+ const no = section.slice(noAt)
+ for (const [kind, retryable] of Object.entries(REQUEST_ID_RETRYABLE)) {
+ expect(retryable ? yes : no, `${name}: ${kind} in its group`).toContain(`\`${kind}\``)
+ expect(retryable ? no : yes, `${name}: ${kind} not in the other`).not.toContain(`\`${kind}\``)
+ expect(section).toContain(REQUEST_ID_OUTCOME_GLOSS[kind as keyof typeof REQUEST_ID_OUTCOME_GLOSS])
+ }
+ }
+ })
+
// --- station-failure notices (src/core/agents/station-notice.ts) ------------------------------
// The agent that opened a station is told when it stops — the text it reads about that must be
// the TABLE's, so a reason or a retry sentence changed in @shared/station-notice lands here the
diff --git a/src/main/canvas-control-shim.request-id.test.ts b/src/main/canvas-control-shim.request-id.test.ts
new file mode 100644
index 000000000..3e464f192
--- /dev/null
+++ b/src/main/canvas-control-shim.request-id.test.ts
@@ -0,0 +1,152 @@
+// A retried open must not open a second node — the real generated shim, run by the real /bin/sh,
+// against the real hook server and its request ledger.
+//
+// The case nothing else can reach: the shim's OWN re-post. The primary endpoint here is a proxy
+// that forwards the request to the hook server and then drops the connection instead of relaying
+// the reply — so the server did the work and curl saw nothing (`000`). That is exactly what makes
+// the shim walk to another endpoint of the same app and POST again (issue #445's failover). Before
+// the per-run request id, that re-post was a second call and opened a second node.
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest'
+import { execFile } from 'node:child_process'
+import fs from 'node:fs'
+import net from 'node:net'
+import os from 'node:os'
+import path from 'node:path'
+import { promisify } from 'node:util'
+import { CONTROL_SHIM_SCRIPT } from '../core/canvas-control-core'
+import { hookServer } from '../core/agents/hook-server'
+import { nodeAuthToken } from '../core/agents/node-auth-token'
+import { REQUEST_ID_REPLAYED_LEAD } from '../core/control-request-ledger'
+import { initPlatform, resetPlatformForTests } from '../core/platform'
+import { fakePlatform } from '../core/platform-fake'
+
+const run = promisify(execFile)
+const SECRET = Buffer.alloc(32, 13)
+
+let dir = ''
+let shim = ''
+let tokens = ''
+let liveEndpoint = ''
+let droppingEndpoint = ''
+let home = ''
+let proxy: net.Server
+let proxied = 0
+let handled: { verb: string; args: Record<string, string> }[] = []
+
+beforeAll(async () => {
+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'nodeterm-shim-rid-'))
+ resetPlatformForTests()
+ initPlatform(fakePlatform({ userDataDir: path.join(dir, 'userdata') }))
+ shim = path.join(dir, 'nodeterm.sh')
+ fs.writeFileSync(shim, CONTROL_SHIM_SCRIPT, { mode: 0o755 })
+ await hookServer.start()
+ hookServer.setNodeAuthSecret(SECRET)
+ hookServer.setControlHandler(async (cmd) => {
+ handled.push({ verb: cmd.verb, args: cmd.args })
+ return { ok: true, message: `opened node #${handled.length}` }
+ })
+
+ // Every node proves itself: the ledger keys only VERIFIED callers.
+ tokens = path.join(dir, 'tokens')
+ fs.mkdirSync(tokens)
+ for (const id of ['node-a', 'node-b', 'node-c']) {
+ fs.writeFileSync(path.join(tokens, id), `${nodeAuthToken(SECRET, id)}\n`, { mode: 0o600 })
+ }
+ const endpointFile = (port: number): string =>
+ `NODETERM_HOOK_PORT='${port}'\n` +
+ `NODETERM_HOOK_TOKEN='${hookServer.getToken()}'\n` +
+ "NODETERM_HOOK_VERSION='2'\n" +
+ `NODETERM_NODE_TOKEN_DIR='${tokens}'\n`
+ liveEndpoint = path.join(dir, 'live.env')
+ fs.writeFileSync(liveEndpoint, endpointFile(hookServer.getPort()))
+
+ // The dropping proxy: request through, reply swallowed, connection closed.
+ proxy = net.createServer((client) => {
+ proxied++
+ const upstream = net.connect(hookServer.getPort(), '127.0.0.1')
+ client.pipe(upstream)
+ upstream.once('data', () => {
+ client.destroy()
+ upstream.destroy()
+ })
+ client.on('error', () => upstream.destroy())
+ upstream.on('error', () => client.destroy())
+ })
+ await new Promise<void>((resolve) => proxy.listen(0, '127.0.0.1', resolve))
+ droppingEndpoint = path.join(dir, 'dropping.env')
+ fs.writeFileSync(droppingEndpoint, endpointFile((proxy.address() as net.AddressInfo).port))
+
+ // The live endpoint the walk finds: the Server Edition slot under $HOME, the first candidate
+ // `nt_candidates` prints — the same arrangement the #445 failover test uses.
+ home = path.join(dir, 'home')
+ fs.mkdirSync(path.join(home, '.nodeterm-server'), { recursive: true })
+ fs.writeFileSync(path.join(home, '.nodeterm-server', 'hook-endpoint.env'), endpointFile(hookServer.getPort()))
+})
+
+beforeEach(() => {
+ handled = []
+ proxied = 0
+})
+
+afterAll(async () => {
+ hookServer.clearNodeAuthSecretForTests()
+ hookServer.stop()
+ await new Promise<void>((resolve) => proxy.close(() => resolve()))
+ resetPlatformForTests()
+ fs.rmSync(dir, { recursive: true, force: true })
+})
+
+function callShim(
+ node: string,
+ endpoint: string,
+ args: string[]
+): Promise<{ stdout: string; stderr: string }> {
+ return run('/bin/sh', [shim, ...args], {
+ env: {
+ PATH: process.env.PATH ?? '',
+ NODETERM_CANVAS_CONTROL: '1',
+ NODETERM_NODE_ID: node,
+ NODETERM_HOOK_ENDPOINT: endpoint,
+ HOME: home
+ }
+ })
+}
+
+describe('canvas-control shim: a retried open does not open a second node', () => {
+ it("the shim's own re-post after a dropped reply is recognised: ONE node, and the reply says so", async () => {
+ const { stdout } = await callShim('node-a', droppingEndpoint, ['open-agent', '--agent', 'claude'])
+ // The first POST went through the proxy and was dropped; the walk re-posted to the live one.
+ expect(proxied).toBeGreaterThanOrEqual(1)
+ expect(handled).toHaveLength(1)
+ expect(stdout.split('\n')[0]).toContain(REQUEST_ID_REPLAYED_LEAD)
+ expect(stdout).toContain('opened node #1')
+ })
+
+ it('an agent that re-runs the command with the same --request-id gets the first reply, not a second node', async () => {
+ const args = ['open-agent', '--agent', 'claude', '--prompt', 'review it', '--request-id', 'review-1']
+ const first = await callShim('node-b', liveEndpoint, args)
+ expect(first.stdout.trim()).toBe('opened node #1')
+ const again = await callShim('node-b', liveEndpoint, args)
+ expect(again.stdout).toContain(REQUEST_ID_REPLAYED_LEAD)
+ expect(again.stdout).toContain('opened node #1')
+ expect(handled).toHaveLength(1)
+ expect(handled[0].args).toEqual({ agent: 'claude', prompt: 'review it' })
+ })
+
+ it('the same --request-id with a different call is refused, and nothing is opened', async () => {
+ await callShim('node-c', liveEndpoint, ['open-agent', '--agent', 'claude', '--request-id', 'x-1'])
+ const err = await callShim('node-c', liveEndpoint, ['open-agent', '--agent', 'codex', '--request-id', 'x-1']).then(
+ () => null,
+ (e: { code: number; stderr: string }) => e
+ )
+ expect(err?.code).toBe(1)
+ expect(err?.stderr).toMatch(/request-id-conflict/)
+ expect(handled).toHaveLength(1)
+ })
+
+ it('two runs without --request-id are two calls: the per-run id protects a run, not a repeat', async () => {
+ await callShim('node-a', liveEndpoint, ['open-terminal'])
+ await callShim('node-a', liveEndpoint, ['open-terminal'])
+ expect(handled).toHaveLength(2)
+ })
+})
diff --git a/src/main/canvas-control-shim.test.ts b/src/main/canvas-control-shim.test.ts
index 4c104847e..5f9bf47dd 100644
--- a/src/main/canvas-control-shim.test.ts
+++ b/src/main/canvas-control-shim.test.ts
@@ -235,6 +235,8 @@ describe('canvas-control shim over a unix socket', () => {
expect(lastSeen()?.token).toBe('tok-remote')
expect(parseControlBody(lastSeen()?.body ?? '', 'application/x-www-form-urlencoded')).toEqual({
nodeId: 'node-1',
+ // The per-run id the server's request ledger keys the shim's own re-posts by.
+ requestId: expect.stringMatching(/^cli-[0-9a-f]{24}$/),
args: { count: '2' }
})
})
@@ -249,6 +251,8 @@ describe('canvas-control shim over a unix socket', () => {
expect(lastSeen()?.path).toBe('/control/link')
expect(parseControlBody(lastSeen()?.body ?? '', 'application/x-www-form-urlencoded')).toEqual({
nodeId: 'node-1',
+ // The per-run id the server's request ledger keys the shim's own re-posts by.
+ requestId: expect.stringMatching(/^cli-[0-9a-f]{24}$/),
args: { to: 'n2,n3', from: 'n1' }
})
})
diff --git a/src/main/control-forward.test.ts b/src/main/control-forward.test.ts
new file mode 100644
index 000000000..792422d94
--- /dev/null
+++ b/src/main/control-forward.test.ts
@@ -0,0 +1,83 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createControlForwarder, controlTimeoutError } from './control-forward'
+
+beforeEach(() => vi.useFakeTimers())
+afterEach(() => vi.useRealTimers())
+
+describe('createControlForwarder', () => {
+ it('resolves with the renderer answer that carries its request id', async () => {
+ const sent: string[] = []
+ const fwd = createControlForwarder({ timeoutMs: 1000 })
+ const p = fwd.forward('open-agent', (id) => sent.push(id))
+ fwd.answer({ requestId: sent[0], ok: true, message: 'opened n1' })
+ await expect(p).resolves.toEqual({ ok: true, message: 'opened n1' })
+ })
+
+ it('a timeout is INDETERMINATE: the renderer may still do it, so nobody may claim it did not happen', async () => {
+ const fwd = createControlForwarder({ timeoutMs: 1000 })
+ const p = fwd.forward('open-worktree', () => {})
+ vi.advanceTimersByTime(1000)
+ const r = await p
+ expect(r.ok).toBe(false)
+ expect(r.indeterminate).toBe(true)
+ })
+
+ it('an answer that arrives after the timeout is handed to the late-answer callback, once', async () => {
+ const sent: string[] = []
+ const late = vi.fn()
+ const fwd = createControlForwarder({ timeoutMs: 1000, lateWindowMs: 60_000 })
+ const p = fwd.forward('open-worktree', (id) => sent.push(id), late)
+ vi.advanceTimersByTime(1000)
+ await p
+ fwd.answer({ requestId: sent[0], ok: true, message: 'opened worktree feat-x' })
+ fwd.answer({ requestId: sent[0], ok: true, message: 'a duplicate answer' })
+ expect(late).toHaveBeenCalledTimes(1)
+ expect(late).toHaveBeenCalledWith({ ok: true, message: 'opened worktree feat-x' })
+ })
+
+ it('forgets a late answer past its window, and never calls a callback nobody registered', async () => {
+ const sent: string[] = []
+ const late = vi.fn()
+ const fwd = createControlForwarder({ timeoutMs: 1000, lateWindowMs: 5000 })
+ const p = fwd.forward('open-terminal', (id) => sent.push(id), late)
+ vi.advanceTimersByTime(1000)
+ await p
+ vi.advanceTimersByTime(5000)
+ fwd.answer({ requestId: sent[0], ok: true, message: 'too late' })
+ expect(late).not.toHaveBeenCalled()
+ // No callback: a late answer is dropped exactly as before.
+ const q = fwd.forward('open-terminal', (id) => sent.push(id))
+ vi.advanceTimersByTime(1000)
+ await q
+ expect(() => fwd.answer({ requestId: sent[1], ok: true })).not.toThrow()
+ })
+
+ it('an answer for an unknown request id is ignored', () => {
+ const fwd = createControlForwarder({ timeoutMs: 1000 })
+ expect(() => fwd.answer({ requestId: 'nope', ok: true })).not.toThrow()
+ })
+})
+
+describe('controlTimeoutError', () => {
+ it('a confirm-gated verb keeps its dialog wording: the dialog dismisses itself at the same deadline', () => {
+ expect(controlTimeoutError('write', 120_000)).toBe(
+ 'no answer within 120s — the confirmation dialog has been dismissed; safe to retry'
+ )
+ })
+
+ it('a verb that creates something is NOT called safe to retry: the renderer was not cancelled', () => {
+ const msg = controlTimeoutError('open-worktree', 120_000)
+ expect(msg).toMatch(/^no answer within 120s/)
+ expect(msg).not.toMatch(/safe to retry/)
+ expect(msg).toMatch(/may still complete/)
+ expect(msg).toMatch(/--request-id/)
+ expect(msg).toMatch(/`list`/)
+ })
+
+ it('any other verb is told to check before retrying, and is not pointed at a flag it cannot take', () => {
+ const msg = controlTimeoutError('rename', 120_000)
+ expect(msg).not.toMatch(/safe to retry/)
+ expect(msg).not.toMatch(/--request-id/)
+ expect(msg).toMatch(/may still complete/)
+ })
+})
diff --git a/src/main/control-forward.ts b/src/main/control-forward.ts
new file mode 100644
index 000000000..0058e9d22
--- /dev/null
+++ b/src/main/control-forward.ts
@@ -0,0 +1,95 @@
+// Desktop main's half of a canvas-control call: forward it to the renderer's dispatch and wait for
+// the one answer, bounded. Pulled out of `src/main/index.ts` (it was the `pendingControl` map) so
+// the timeout and what follows it are tested by EFFECT rather than by reading index.ts.
+//
+// A TIMEOUT HERE IS NOT A REFUSAL. Main gives up waiting; the renderer is not told and does not
+// stop. A confirm dialog dismisses itself at the same deadline (ConfirmState.expiresAt), but a verb
+// with no dialog — an `open-worktree` whose `git worktree add` outlives the wait, an open whose
+// issue lookup is slow — goes on and does its work after the caller was told it got no answer. So
+// the timeout answers `indeterminate: true` (the request ledger then refuses a retry as "unknown"
+// instead of running it a second time), and an answer that arrives afterwards is handed to the
+// caller's `onLate` so the ledger can replay what really happened to the next retry.
+import { randomUUID } from 'node:crypto'
+import { isDestructiveVerb } from '../shared/control-verbs'
+import { REQUEST_ID_VERBS } from '../core/control-request-ledger'
+
+export interface ControlForwardReply {
+ ok: boolean
+ message?: string
+ result?: unknown
+ error?: string
+ indeterminate?: boolean
+}
+
+/**
+ * The timeout's sentence, by what the verb could still be doing. Only a confirm-gated verb may be
+ * called safe to retry: its dialog is gone, so nothing was confirmed. Anything else may still
+ * complete, and telling an agent it is safe to retry an open is how a second node gets opened.
+ */
+export function controlTimeoutError(verb: string, timeoutMs: number): string {
+ const lead = `no answer within ${timeoutMs / 1000}s`
+ if (isDestructiveVerb(verb)) return `${lead} — the confirmation dialog has been dismissed; safe to retry`
+ if (REQUEST_ID_VERBS.has(verb)) {
+ return (
+ `${lead} — the request was not cancelled and may still complete, so it may have taken effect: ` +
+ 'retry the same command with the same --request-id to get its answer, or run `list` before ' +
+ 'opening anything again'
+ )
+ }
+ return `${lead} — the request was not cancelled and may still complete; check its effect before retrying`
+}
+
+/** How long a late renderer answer is still worth handing back. Past it the ledger row stays
+ * unknown and a retry is told to `list`. */
+export const LATE_CONTROL_ANSWER_MS = 30 * 60 * 1000
+
+export function createControlForwarder(opts: {
+ timeoutMs: number
+ lateWindowMs?: number
+ newId?: () => string
+}): {
+ /** Send via `send(requestId)` and wait for `answer` with that id, at most `timeoutMs`. */
+ forward(
+ verb: string,
+ send: (requestId: string) => void,
+ onLate?: (reply: ControlForwardReply) => void
+ ): Promise<ControlForwardReply>
+ /** The renderer's answer (the `agentControlResult` IPC). */
+ answer(payload: { requestId: string } & ControlForwardReply): void
+} {
+ const newId = opts.newId ?? randomUUID
+ const lateWindowMs = opts.lateWindowMs ?? LATE_CONTROL_ANSWER_MS
+ const pending = new Map<string, { resolve: (r: ControlForwardReply) => void; timer: NodeJS.Timeout }>()
+ const late = new Map<string, { onLate: (r: ControlForwardReply) => void; timer: NodeJS.Timeout }>()
+ return {
+ forward(verb, send, onLate) {
+ const requestId = newId()
+ return new Promise<ControlForwardReply>((resolve) => {
+ const timer = setTimeout(() => {
+ pending.delete(requestId)
+ if (onLate) {
+ const lateTimer = setTimeout(() => late.delete(requestId), lateWindowMs)
+ late.set(requestId, { onLate, timer: lateTimer })
+ }
+ resolve({ ok: false, error: controlTimeoutError(verb, opts.timeoutMs), indeterminate: true })
+ }, opts.timeoutMs)
+ pending.set(requestId, { resolve, timer })
+ send(requestId)
+ })
+ },
+ answer({ requestId, ...reply }) {
+ const waiting = pending.get(requestId)
+ if (waiting) {
+ clearTimeout(waiting.timer)
+ pending.delete(requestId)
+ waiting.resolve(reply)
+ return
+ }
+ const after = late.get(requestId)
+ if (!after) return
+ clearTimeout(after.timer)
+ late.delete(requestId)
+ after.onLate(reply)
+ }
+ }
+}
diff --git a/src/main/control-shim-parse.test.ts b/src/main/control-shim-parse.test.ts
index 568f5a2c1..3998fd05a 100644
--- a/src/main/control-shim-parse.test.ts
+++ b/src/main/control-shim-parse.test.ts
@@ -16,16 +16,17 @@ import os from 'node:os'
import path from 'node:path'
import { CONTROL_SHIM_SCRIPT } from '../core/canvas-control-core'
import { runNowRequested } from '../shared/control-verbs'
+import { isValidRequestId } from '../core/control-request-ledger'
let dir = ''
-/** Run the shim and return the `arg.<name>=<value>` pairs it handed curl, in order. */
-const run = (args: string[]): string[] => {
+/** Run the shim and return every argv element it handed curl, one per line. */
+const runRaw = (args: string[], extraBin?: string): string[] => {
const log = path.join(dir, 'argv.log')
fs.writeFileSync(log, '')
execFileSync('sh', [path.join(dir, 'shim.sh'), ...args], {
env: {
- PATH: `${path.join(dir, 'bin')}:${process.env.PATH ?? ''}`,
+ PATH: `${extraBin ? `${extraBin}:` : ''}${path.join(dir, 'bin')}:${process.env.PATH ?? ''}`,
NODETERM_CANVAS_CONTROL: '1',
NODETERM_HOOK_PORT: '1',
NODETERM_NODE_ID: 'n1',
@@ -34,14 +35,14 @@ const run = (args: string[]): string[] => {
},
encoding: 'utf8'
})
- // One argv element per line; keep only the translated pairs (`nodeId=…` and curl's own flags
- // are not part of what this file is about).
- return fs
- .readFileSync(log, 'utf8')
- .split('\n')
- .filter((l) => l.startsWith('arg.'))
+ return fs.readFileSync(log, 'utf8').split('\n')
}
+/** Run the shim and return the `arg.<name>=<value>` pairs it handed curl, in order. */
+// Only the translated pairs: `nodeId=…`, `requestId=…` and curl's own flags are not part of what
+// this file is about.
+const run = (args: string[]): string[] => runRaw(args).filter((l) => l.startsWith('arg.'))
+
beforeAll(() => {
dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ctlshim-'))
fs.mkdirSync(path.join(dir, 'bin'))
@@ -57,6 +58,44 @@ beforeAll(() => {
afterAll(() => fs.rmSync(dir, { recursive: true, force: true }))
+// The per-RUN request id: what lets the server recognise the shim's own endpoint-walk re-post as
+// the SAME call rather than a second open (src/core/control-request-ledger.ts). One run = one id,
+// on every POST of that run; two runs = two ids, because a second run is a second call.
+describe('the control shim tags each run with its own request id', () => {
+ const ids = (args: string[], extraBin?: string): string[] =>
+ runRaw(args, extraBin)
+ .filter((l) => l.startsWith('requestId='))
+ .map((l) => l.slice('requestId='.length))
+
+ it('sends exactly one well-formed id per POST, and never as an arg', () => {
+ const got = ids(['open-agent', '--agent', 'claude'])
+ expect(got).toHaveLength(1)
+ expect(isValidRequestId(got[0])).toBe(true)
+ expect(run(['open-agent', '--agent', 'claude'])).toEqual(['arg.agent=claude'])
+ })
+
+ it('two runs get two different ids', () => {
+ const [a] = ids(['open-terminal'])
+ const [b] = ids(['open-terminal'])
+ expect(a).not.toBe(b)
+ })
+
+ it('with no working od (no random source), it still sends a well-formed id', () => {
+ const noOd = path.join(dir, 'no-od')
+ fs.mkdirSync(noOd, { recursive: true })
+ fs.writeFileSync(path.join(noOd, 'od'), '#!/bin/sh\nexit 1\n', { mode: 0o755 })
+ const got = ids(['open-terminal'], noOd)
+ expect(got).toHaveLength(1)
+ expect(got[0]).toMatch(/^cli-\d+-\d+$/)
+ expect(isValidRequestId(got[0])).toBe(true)
+ })
+
+ it('an explicit --request-id rides as an ordinary arg next to the per-run id', () => {
+ expect(run(['open-terminal', '--request-id', 'wave1-a'])).toEqual(['arg.request-id=wave1-a'])
+ expect(ids(['open-terminal', '--request-id', 'wave1-a'])).toHaveLength(1)
+ })
+})
+
describe('the control shim translates flags', () => {
it('a --flag followed by another --flag does NOT eat it', () => {
// THE BUG: this used to yield ['arg.read=--node'] and `b1` was lost with no error anywhere.
diff --git a/src/main/index.ts b/src/main/index.ts
index 9077198b6..dc060d42c 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -276,6 +276,7 @@ import { DRY_RUN_VERBS, dryRunRequested, dryRunRefusal } from '../shared/control
import { issueFlagRefusal } from '../core/canvas-control-core'
import { afterPrFlagRefusal } from '../shared/pr-wait'
import { CONTROL_REQUEST_TIMEOUT_MS } from '../shared/control-confirm'
+import { createControlForwarder } from './control-forward'
import { initTranscriptIndex, searchTranscripts } from '../core/transcript-index'
import { initTelemetry } from './telemetry'
import { initClaudeUsage } from './claude-usage'
@@ -3416,13 +3417,10 @@ app.whenReady().then(async () => {
// confirm dialog collect itself once this timer has already abandoned the request (main sends
// no expiry event), and two copies of the deadline is the drift this repo keeps paying for.
// See @shared/control-confirm.
- const pendingControl = new Map<
- string,
- {
- resolve: (r: { ok: boolean; message?: string; result?: unknown; error?: string }) => void
- timer: NodeJS.Timeout
- }
- >()
+ // The map and its timer live in `control-forward.ts`, where a timeout answers INDETERMINATE (the
+ // renderer is not cancelled and may still act) and a late answer is handed back to the request
+ // ledger rather than dropped — see that module's header.
+ const controlForwarder = createControlForwarder({ timeoutMs: CONTROL_REQUEST_TIMEOUT_MS })
// Who owns which agent-opened browser node, THIS app run only. In-memory, never persisted, never
// read from project.json (Task 4.3/4.4). Consumed by PR 5 (attach/lease), PR 6 (indicator/Stop).
const browserLedger = new BrowserControlLedger()
@@ -3588,18 +3586,12 @@ app.whenReady().then(async () => {
(
_e,
payload: { requestId: string; ok: boolean; message?: string; result?: unknown; error?: string }
- ) => {
- const pending = pendingControl.get(payload.requestId)
- if (!pending) return
- clearTimeout(pending.timer)
- pendingControl.delete(payload.requestId)
- pending.resolve(payload)
- }
+ ) => controlForwarder.answer(payload)
)
// The `browser` verb resolve round-trip (Task 7.2). Main asks the renderer to resolve a source
// node's owning project, control-capability and the LIVE per-project capability value; the renderer
- // answers here. Modelled on `pendingControl`, but its own map with its own short (2s) timeout so a
- // slow canvas can NEVER consume the 120s pending-control budget.
+ // answers here. Modelled on the control forwarder (`control-forward.ts`), but its own map with its
+ // own short (2s) timeout so a slow canvas can NEVER consume the 120s pending-control budget.
const pendingBrowserResolve = new Map<string, (r: BrowserResolve) => void>()
ipcMain.on(
IPC.browserControlResolveResult,
@@ -3765,7 +3757,7 @@ app.whenReady().then(async () => {
: { ok: false, error: result.error, message: result.message }
)
}
- hookServer.setControlHandler(async ({ verb, nodeId, args, verified }) => {
+ hookServer.setControlHandler(async ({ verb, nodeId, args, verified, onLateAnswer }) => {
// `--dry-run` (issue #532) is honoured by the spawn verbs only, and this gate runs FIRST —
// before the browser intercept, the open-project gates and the renderer forward — because a
// verb that cannot dry-run must REFUSE rather than silently perform: a `close --dry-run`
@@ -3832,25 +3824,17 @@ app.whenReady().then(async () => {
}
const target = getMainWindow()
if (!target) return { ok: false, error: 'window unavailable' }
- const requestId = randomUUID()
- const result = await new Promise<{ ok: boolean; message?: string; result?: unknown; error?: string }>((resolve) => {
- const timer = setTimeout(() => {
- pendingControl.delete(requestId)
- // Name the timeout and say it is retryable. A DENIAL is a different answer with different
- // guidance (`denied by user`, final, never retried), and the old wording — "no response /
- // not confirmed" — read as though it covered both, so a caller that had merely waited out
- // an unanswered dialog treated it as a refusal and gave up.
- resolve({
- ok: false,
- // The dialog is not left behind any more: it carries the same deadline and dismisses
- // itself (ConfirmState.expiresAt), which is what stops a retry hitting "a confirmation
- // is already pending" for the rest of the app run.
- error: `no answer within ${CONTROL_REQUEST_TIMEOUT_MS / 1000}s — the confirmation dialog has been dismissed; safe to retry`
- })
- }, CONTROL_REQUEST_TIMEOUT_MS)
- pendingControl.set(requestId, { resolve, timer })
- target.webContents.send(IPC.agentControl, { requestId, sourceNodeId: nodeId, verb, args })
- })
+ // The timeout is NAMED, and what it says depends on the verb (`controlTimeoutError`): a DENIAL
+ // is a different answer (`denied by user`, final), and only a confirm-gated verb, whose dialog
+ // dismisses itself at the same deadline (ConfirmState.expiresAt), may be called safe to retry.
+ // An open is not cancelled by main giving up, so its timeout is indeterminate and its late
+ // answer goes back to the request ledger through `onLateAnswer`.
+ const result = await controlForwarder.forward(
+ verb,
+ (requestId) =>
+ target.webContents.send(IPC.agentControl, { requestId, sourceNodeId: nodeId, verb, args }),
+ onLateAnswer
+ )
// Record browser ownership the moment an open-browser succeeds — and ONLY when the caller's
// identity verdict for THIS request was `verified` (main's own verdict, not anything off the
// wire or project.json). A `legacy`/warned caller may open a browser but owns nothing, so it
diff --git a/src/server/control-unsupported.test.ts b/src/server/control-unsupported.test.ts
index 511deace9..d0d2b4531 100644
--- a/src/server/control-unsupported.test.ts
+++ b/src/server/control-unsupported.test.ts
@@ -410,3 +410,51 @@ describe('a failing verb that carries only `error` is rendered exactly as before
}
})
})
+
+/**
+ * A retried open on the Server Edition. The request ledger lives in the hook-server route, which
+ * this edition's handler sits behind exactly as desktop main's does — so the edition inherits the
+ * dedupe without a line of its own. Proven here with the REAL enabled handler, so a future change
+ * that moves the ledger into one shell's handler goes red for the other.
+ */
+describe('the enabled Server Edition handler, behind the request ledger', () => {
+ it('opens ONE agent for a request id posted twice, and answers the second from the first', async () => {
+ const openAgent = vi.fn(async () => ({ ok: true as const, message: 'opened agent-new', result: { id: 'agent-new' } }))
+ const handler = createServerEditionControlHandler({
+ openProject: vi.fn(),
+ openTerminal: vi.fn(),
+ openAgent,
+ close: vi.fn(),
+ link: vi.fn(),
+ group: vi.fn(),
+ rename: vi.fn(),
+ color: vi.fn(),
+ sticky: vi.fn(),
+ settings: vi.fn(),
+ run: vi.fn(),
+ deliver: vi.fn()
+ })
+ hookServer.setControlHandler(handler)
+ try {
+ const post = () =>
+ fetch(`http://127.0.0.1:${hookServer.getPort()}/control/open-agent`, {
+ method: 'POST',
+ headers: {
+ 'X-Nodeterm-Hook-Token': hookServer.getToken(),
+ 'X-Nodeterm-Node-Token': nodeAuthToken(SECRET, 'se-src'),
+ 'content-type': 'application/x-www-form-urlencoded',
+ accept: 'text/plain'
+ },
+ body: 'nodeId=se-src&requestId=cli-5e1f&arg.agent=claude'
+ })
+ expect((await (await post()).text()).trim()).toBe('opened agent-new')
+ const again = await (await post()).text()
+ expect(again).toMatch(/^replayed:/)
+ expect(again).toContain('opened agent-new')
+ expect(openAgent).toHaveBeenCalledTimes(1)
+ expect(openAgent).toHaveBeenCalledWith('se-src', { agent: 'claude' }, true)
+ } finally {
+ hookServer.setControlHandler(serverEditionControlHandler)
+ }
+ })
+})