Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
fix(canvas): headless start sets requireRemote for SSH-project nodes; docs state both fences (#925)
review52862cf12be6
diff --git a/CLAUDE.md b/CLAUDE.mdindex 3c55bf0aa..a5d90c3ec 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -3165,8 +3165,8 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile`queued:false` is NOT proof of a running CLI: Server's `deliveredIds` acknowledges terminaldelivery only. Its initial commands are persisted before attach/send and retained on failure;only acknowledged sends clear them. Boot ownership remains fail-closed. Desktop `list` (live- and stored projects) names QUEUED / LAUNCH FAILED / DROPPED / AGENT STATUS UNCONFIRMED rather- than treating absence of a hook as success. Server v1 still explicitly refuses `list`.+ and stored projects) names QUEUED / STARTING / LAUNCH FAILED / DROPPED / AGENT STATUS UNCONFIRMED+ rather than treating absence of a hook as success. Server v1 still explicitly refuses `list`.**(8) An armed node must not cold-start its own agent** (found while fixing (7)). The mount-timecold-restore relaunch (`fresh && agentId && canResume(...)`) carries a second, independentrefusal beside the `paused` one (`shouldColdResume`): `!data.pendingLaunch`. A first open is@@ -3203,11 +3203,14 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile*failed-to-start* watchdog (a station that never emits ANY hook event — the opposite failure,which hangs dependents honestly rather than firing them wrongly), stay open.**Headless start (`--run-now`, `run`, #925):** `open-*` with `--run-now` into a project that is- not on screen starts the node at once instead of "when next viewed", and `run --node <id>- [--project <id>]` is the CLI twin of the QUEUED badge's Run now (like ▶, a `run` that starts the- node overrides its `--after` wait). Into a project that IS on screen `--run-now` changes nothing:- the mount path already starts the node.- - **Flow.** The renderer builds the node as a cold open, then writes an+ not on screen starts the new node's held launch at once instead of "when next viewed". A node+ with nothing held (an `open-terminal` without `--cmd`) has nothing to start, and gets the plain+ cold-open reply. `run --node <id> [--project <id>]` builds nothing: it claims and starts the held+ launch of a node that already exists, the CLI twin of the QUEUED badge's Run now (like ▶, a `run`+ that starts the node overrides its `--after` wait). Into a project that IS on screen `--run-now`+ changes nothing: the mount path already starts the node.+ - **Flow.** For `--run-now` the renderer first builds the node as a cold open; `run` starts from+ the node as stored. Either way it then writes an`executor:'core', attempted:true, manualOnly:true` claim to disk BEFORE any spawn (neverspawn on an unsaved claim: a failed save restores the original launch and starts nothing,`claim-not-saved`). Desktop main's `pty.launchHeadless` runs core `launchHeadless` on@@ -3221,26 +3224,35 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile- **The IPC is desktop-only and host-only.** It is registered in `src/main`, not in core`registerIpc`, so a Server Edition browser cannot reach it (ws-bridge declares it`unsupported`), and `IPC.ptyLaunchHeadless` is in `HOST_ONLY_CHANNELS`, so a relay peer that- sends the raw request is refused host-side. `desktopHeadlessRequest` strips `sshRemote` but- KEEPS `requireRemote`: a remote node that got this far fails closed in `spawnNew` instead of- starting a LOCAL `nt-<id>`. The renderer refuses it earlier still: `startHeadless` answers- `remote-unsupported` for a node carrying `ssh` / `sshRemoteTmux` before any claim, and leaves- its launch exactly as it was.+ sends the raw request is refused host-side.+ - **Remote nodes are fenced twice.** The primary fence is the renderer's: `startHeadless`+ answers `remote-unsupported` for a node carrying `ssh` / `sshRemoteTmux` before any claim, and+ leaves its launch exactly as it was. Behind it is core's belt: `headlessPtyOptions` sets+ `requireRemote` for an SSH-project (`sshRemoteTmux`) node, and `desktopHeadlessRequest` keeps+ it while stripping `sshRemote`. So if such a node ever got past the fence, core's `spawnNew`+ would refuse it (`spawn-failed`) instead of starting a LOCAL `nt-<id>` wearing its identity.- **Why release the client.** An invisible client would fight the viewer's window size andkeep the session "attached" for the reaper forever.- - **No persistent backend** (tmux or session-host): the start is refused before any spawn- (`not-persistent`) and the node is handed back exactly as it was, so a cold open degrades to- an ordinary queued node. Releasing a plain shell would kill it.+ - **No persistent backend** (tmux or session-host): releasing a plain shell would kill it, so the+ start fails `not-persistent`. In the normal case that happens before any spawn+ (`persistentSpawnAvailable`). In the race where the backend goes away between that probe and+ the spawn (tmux switched off in between), the spawn yields a plain shell; the launcher refuses+ it the same way, before typing anything, and its release kills that shell. Either way the node+ is handed back exactly as it was, so a cold open degrades to an ordinary queued node.- **Outcome patch.** It lands wherever the node lives at that moment (`savePendingAnywhere`):the live canvas if the user switched there mid-start, otherwise the store copy plus a disk- write. `delivered` clears the launch; any other failure keeps the claim and marks the node- failed (amber ⚠ QUEUED, recovered by Run now).+ write. `delivered` clears the launch; `not-persistent` restores the original (above); every+ other launch failure keeps the claim and marks the node failed (amber ⚠ QUEUED, recovered by+ Run now).- **While starting.** `launchDelivery` holds `starting`: the badge reads STARTING, ▶ is disabled(a click would splice a second copy into the pane), `launchesToFire` skips the node, and`list` names it. Canvas's delivery sweep spares it (`deliveriesToRetire`): the node lives inANOTHER project by design, so "not armed on this canvas" does not mean "delivered".- **Notice.** A batch that started at least one session raises ONE sticky "Go there" notice- (`headlessStartNoticeText`). A failure shows on the badge and in the reply instead.+ (`headlessStartNoticeText`). A launch failure after the claim (`spawn-failed`, `no-shell`,+ `line-too-long`, `cancelled`) shows on the badge (amber ⚠ QUEUED) and in the reply.+ `not-persistent`, `claim-not-saved` and `remote-unsupported` show only in the reply: the node+ reads as it did before the attempt.- **`--run-now` with `--after` is refused on both editions**, before any node is built, with theshared `RUN_NOW_AFTER_REFUSAL` (`@shared/control-verbs`): "start now" and "start when X isdone" contradict each other.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 5df47503a..7a4211dc8 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -799,10 +799,13 @@ memory). Server deferred delivery is one-shot: a failed probe/send needs expliciA headless start (`--run-now` / `run`, #925) follows the same contract: the claim is saved beforeany spawn, and "started" means the echo-verified writer submitted the line (never that the agent ishealthy). The desktop releases its headless client, so there a start without a persistent terminal-backend is refused before any spawn and hands the node back unchanged (a cold open stays an-ordinary queued node) rather than spawning a shell that the next mount would orphan. A remote (SSH)-node is refused before the claim; the desktop request keeps `requireRemote`, so core can never-start one as a local session.+backend fails `not-persistent` and hands the node back unchanged (a cold open stays an ordinary+queued node) rather than leaving a shell that the next mount would orphan. Normally that refusal+comes before any spawn; if the backend vanishes between the probe and the spawn, the plain shell it+got is refused before anything is typed, and releasing it kills it. A remote (SSH) node is refused+in the renderer before the claim (`remote-unsupported`), which is the primary fence. As a belt+behind it, an SSH-project node's request carries `requireRemote`, which `desktopHeadlessRequest`+keeps, so core's `spawnNew` refuses rather than spawning it locally. Keep both fences.## Testingdiff --git a/src/core/headless-launch.ts b/src/core/headless-launch.tsindex d633d0030..659012587 100644--- a/src/core/headless-launch.ts+++ b/src/core/headless-launch.ts@@ -41,10 +41,12 @@ export interface HeadlessLaunchDeps {* requires a persistent backend. Whatever else the wire carries is overwritten here.** `sshRemote` is stripped: this path never spawns over a ControlMaster. `requireRemote` is KEPT as- * sent. It is core's own refusal to spawn a remote node locally (`spawnNew` → `unavailable:'ssh'`- * → `spawn-failed`), and clearing it with `sshRemote` would start a LOCAL `nt-<id>` wearing the- * remote node's identity and type its launch there (CLAUDE.md, "A remote node is NEVER spawned- * locally").+ * sent. The primary fence is the renderer's: `startHeadless` refuses an SSH node before any claim+ * (`remote-unsupported`), so none should arrive here. `requireRemote` — which the renderer's+ * `headlessPtyOptions` sets for an SSH-project node — is core's belt behind that fence: it makes+ * `spawnNew` refuse (`unavailable:'ssh'` → `spawn-failed`), where clearing it with `sshRemote`+ * would start a LOCAL `nt-<id>` wearing the remote node's identity and type its launch there+ * (CLAUDE.md, "A remote node is NEVER spawned locally").*/export function desktopHeadlessRequest(req: {ptyOptions: PtyCreateOptionsdiff --git a/src/main/index.ts b/src/main/index.tsindex c0cd91cbb..75b63d34e 100644--- a/src/main/index.ts+++ b/src/main/index.ts@@ -1502,8 +1502,10 @@ app.whenReady().then(async () => {// shared `registerIpc`, so a Server Edition browser cannot reach it (the server starts nodes// through its own HeadlessNodeFactory). A relay peer does reach this table, and is refused// host-side because the channel is in `HOST_ONLY_CHANNELS` (shared/host-control). All logic lives- // in core/headless-launch: `desktopHeadlessRequest` strips `sshRemote`, keeps `requireRemote` so- // core still refuses to spawn a remote node locally, and forces release + requirePersistent.+ // in core/headless-launch: `desktopHeadlessRequest` strips `sshRemote` and forces release ++ // requirePersistent. The renderer refuses an SSH node before any claim (the primary fence); the+ // `requireRemote` it sets for an SSH-project node is kept here, so core's `spawnNew` refusal+ // stands behind that fence as a belt.corePlatform.handle(IPC.ptyLaunchHeadless,(req: { ptyOptions: PtyCreateOptions; command: string }) =>diff --git a/src/renderer/lib/headlessRun.test.ts b/src/renderer/lib/headlessRun.test.tsindex e4d792d02..a5f47e568 100644--- a/src/renderer/lib/headlessRun.test.ts+++ b/src/renderer/lib/headlessRun.test.ts@@ -4,6 +4,7 @@ import type { HeadlessLaunchResult } from '@shared/headless-launch'import { coldOpenMessage } from './coldOpen'import {claimForHeadless,+ headlessPtyOptions,headlessStartNoticeText,mergeRunNow,planRunVerb,@@ -69,6 +70,29 @@ describe('claimForHeadless', () => {})})+describe('headlessPtyOptions', () => {+ // The belt behind startHeadless's `remote-unsupported` refusal, which returns first — so the+ // belt is only reachable, and only testable, through the builder itself.+ it('an SSH-project node carries requireRemote, so core refuses to spawn it locally', () => {+ const opts = headlessPtyOptions(project, node({ sshRemoteTmux: true }))+ expect(opts.requireRemote).toBe(true)+ expect(opts).toMatchObject({ persistKey: 'n1', cwd: '/repo', ownerProjectId: 'p2', cols: 120, rows: 36 })+ expect(opts.sshRemote).toBeUndefined()+ })++ it('a plain local node gets no requireRemote key at all', () => {+ const opts = headlessPtyOptions(project, node())+ expect('requireRemote' in opts).toBe(false)+ expect(opts).toMatchObject({ persistKey: 'n1', cwd: '/repo', ownerProjectId: 'p2', agentId: 'claude' })+ })++ it('is what startHeadless sends', async () => {+ const { d } = deps({ outcome: 'delivered', fresh: true })+ await startHeadless(d, { project, node: node() })+ expect(d.launch).toHaveBeenCalledWith({ ptyOptions: headlessPtyOptions(project, node()), command: "claude 'go'" })+ })+})+describe('startHeadless', () => {it('delivered: claim saved BEFORE the launch, cleared after, notice-worthy', async () => {const order: string[] = []diff --git a/src/renderer/lib/headlessRun.ts b/src/renderer/lib/headlessRun.tsindex 42952e9a7..997571d35 100644--- a/src/renderer/lib/headlessRun.ts+++ b/src/renderer/lib/headlessRun.ts@@ -1,7 +1,9 @@// Canvas-control headless start (#925): `open-* --run-now` and `run --node`. Pure planners plus// one orchestrator with injected effects, so Canvas.tsx only wires. See the spec (§4) for the flow:// write-ahead claim → launch through main → patch the node wherever it lives NOW.-// Headless starts are local-only: a remote (SSH) node is refused here, before any claim.+// Headless starts are local-only: a remote (SSH) node is refused here, before any claim+// (`remote-unsupported`, the primary fence), and `headlessPtyOptions` sets `requireRemote` for an+// SSH-project node as core's belt behind it.import type { CanvasNodeState, PendingLaunch, Project, PtyCreateOptions } from '@shared/types'import type { HeadlessLaunchFailure, HeadlessLaunchResult } from '@shared/headless-launch'import { HEADLESS_COLS, HEADLESS_ROWS, localNodePtyOptions } from '@shared/node-pty-options'@@ -48,6 +50,25 @@ export function headlessStartNoticeText(projectName: string, count: number): strreturn `An agent started ${what} in "${projectName}". That project is not on screen.`}+/**+ * The PtyCreateOptions of a headless start: the shared local builder at the headless size, plus+ * `requireRemote` for an SSH-project node. `startHeadless` refuses such a node before any claim+ * (`remote-unsupported`) — that is the primary fence. This is core's belt behind it: if a remote+ * node ever reached the launcher, core's `spawnNew` refuses it (`unavailable:'ssh'`) instead of+ * starting a LOCAL `nt-<id>` wearing the remote node's identity. `desktopHeadlessRequest` keeps+ * the flag. Set here and not in `localNodePtyOptions`, whose key set is pinned and which the+ * Server Edition shares.+ */+export function headlessPtyOptions(+ project: Pick<Project, 'id' | 'cwd'>,+ node: CanvasNodeState+): PtyCreateOptions {+ return {+ ...localNodePtyOptions(project, node, { cols: HEADLESS_COLS, rows: HEADLESS_ROWS }),+ ...(node.sshRemoteTmux ? { requireRemote: true } : {})+ }+}+export type HeadlessStartOutcome =| { id: string; started: true }| {@@ -80,8 +101,9 @@ export async function startHeadless(const id = node.idconst original = node.pendingLaunchif (!original?.command) return { id, started: false, reason: 'nothing-queued' }- // A remote node is NEVER spawned locally. The options below are LOCAL (no requireRemote), so- // refuse before touching anything: the untouched pending launch starts on view, over SSH.+ // A remote node is NEVER spawned locally. The launcher only spawns locally, so refuse before+ // touching anything (the primary fence): the untouched pending launch starts on view, over SSH.+ // `headlessPtyOptions` also sets `requireRemote` for an SSH-project node, core's belt behind this.if (node.ssh || node.sshRemoteTmux) return { id, started: false, reason: 'remote-unsupported' }if (deps.inFlight.has(id)) return { id, started: false, reason: 'already-starting' }deps.inFlight.add(id)@@ -95,7 +117,7 @@ export async function startHeadless(let result: HeadlessLaunchResulttry {result = await deps.launch({- ptyOptions: localNodePtyOptions(project, node, { cols: HEADLESS_COLS, rows: HEADLESS_ROWS }),+ ptyOptions: headlessPtyOptions(project, node),command: original.command})} catch {@@ -107,8 +129,10 @@ export async function startHeadless(return { id, started: true }}if (result.reason === 'not-persistent') {- // Nothing was spawned. Hand the node back exactly as it was, so a cold open starts on view- // and an already-attempted node keeps its manual Run now.+ // Nothing was typed and no session survives. Normally nothing was spawned at all (refused+ // before the spawn); in the race where the backend went away between core's probe and the+ // spawn, the plain shell it got was released, which kills it. Hand the node back exactly as+ // it was, so a cold open starts on view and an already-attempted node keeps its manual Run now.deps.clearDelivery(id)await deps.savePending(id, original)} else {