Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(canvas): headless start sets requireRemote for SSH-project nodes; docs state both fences (#925)

review52862cf12be6
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 terminal
delivery 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-time
cold-restore relaunch (`fresh && agentId && canResume(...)`) carries a second, independent
refusal 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 (never
spawn 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 and
keep 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 in
ANOTHER 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 the
shared `RUN_NOW_AFTER_REFUSAL` (`@shared/control-verbs`): "start now" and "start when X is
done" contradict each other.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 explici
A headless start (`--run-now` / `run`, #925) follows the same contract: the claim is saved before
any spawn, and "started" means the echo-verified writer submitted the line (never that the agent is
healthy). 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.
## Testing
diff --git a/src/core/headless-launch.ts b/src/core/headless-launch.ts
index 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: PtyCreateOptions
diff --git a/src/main/index.ts b/src/main/index.ts
index 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.ts
index 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.ts
index 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): str
return `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.id
const original = node.pendingLaunch
if (!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: HeadlessLaunchResult
try {
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 {