Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
feat(control): a retried open does not open a second node (--request-id)
review1dc5b3d5202e
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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 ontoan SSH host only inside `RemoteHooks.setup()` (on connect), so an already-connected project keepsthe 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 otheropen project's tmux sessions keep running, so a control call routinely arrives from a node thediff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex a32e55b4d..ac6c85258 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -335,6 +335,17 @@ anything else. Board-level fields survive every transform — `pullLinks` is oneagainst 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, theagent that opened it is told (`src/core/agents/station-notice.ts`) — and a rope alone cannot saywho that is, because an `--after` node is roped to the stations it waited on too, with the same iddiff --git a/src/core/agents/agent-message-flow.ts b/src/core/agents/agent-message-flow.tsindex 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.tsnew file mode 100644index 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.tsindex 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 maydiff --git a/src/core/agents/hook-server.ts b/src/core/agents/hook-server.tsindex 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: booleanmessage?: stringresult?: unknownerror?: 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.tsindex 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" ]; thennt_had_transport=1nt_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 acaller may mutate or message only nodes it opened during the current server run. Restartingthe 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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 thediff --git a/src/main/canvas-control-shim.request-id.test.ts b/src/main/canvas-control-shim.request-id.test.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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/controlimport { 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 itdiff --git a/src/server/control-unsupported.test.ts b/src/server/control-unsupported.test.tsindex 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)+ }+ })+})