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(pty): keep requireRemote on the headless path; relay peers refused host-side (#925)

review7a730a0c013c
diff --git a/src/core/headless-launch.test.ts b/src/core/headless-launch.test.ts
index d51a5ad98..af2f5ea6a 100644
--- a/src/core/headless-launch.test.ts
+++ b/src/core/headless-launch.test.ts
@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { DELIVERY_ATTEMPTS, KILL_LINE, VERIFY_TIMEOUT_MS } from '@shared/command-delivery'
import type { HeadlessLaunchRequest } from '@shared/headless-launch'
import {
+ desktopHeadlessRequest,
launchHeadless,
SETTLE_CAP_MS,
SETTLE_MAX_MS,
@@ -305,3 +306,60 @@ describe('launchHeadless (#925)', () => {
expect(writes[0]).toBe('\x1b')
})
})
+
+describe('desktopHeadlessRequest (#925)', () => {
+ const opts = { cols: 120, rows: 36, persistKey: 'n1', cwd: '/repo' }
+ const ssh = { controlPath: '/tmp/cm', conn: { host: 'h', user: 'u' } } as never
+
+ it('forces release and requirePersistent true, whatever the wire claims', () => {
+ const out = desktopHeadlessRequest({
+ ptyOptions: opts,
+ command: CMD,
+ release: false,
+ requirePersistent: false
+ } as never)
+ expect(out.release).toBe(true)
+ expect(out.requirePersistent).toBe(true)
+ expect(out.command).toBe(CMD)
+ })
+
+ it('removes sshRemote: this path never spawns over a ControlMaster', () => {
+ const out = desktopHeadlessRequest({ ptyOptions: { ...opts, sshRemote: ssh }, command: CMD })
+ expect(out.ptyOptions.sshRemote).toBeUndefined()
+ expect(out.ptyOptions).toMatchObject(opts)
+ })
+
+ it('keeps requireRemote, so core still refuses to spawn a remote node locally', () => {
+ const out = desktopHeadlessRequest({
+ ptyOptions: { ...opts, sshRemote: ssh, requireRemote: true },
+ command: CMD
+ })
+ expect(out.ptyOptions.requireRemote).toBe(true)
+ })
+
+ it('coerces a non-string command', () => {
+ expect(desktopHeadlessRequest({ ptyOptions: opts, command: 42 as never }).command).toBe('42')
+ expect(desktopHeadlessRequest({ ptyOptions: opts, command: undefined as never }).command).toBe('')
+ expect(desktopHeadlessRequest({ ptyOptions: opts, command: null as never }).command).toBe('')
+ })
+
+ it("a remote node's options end as spawn-failed with nothing typed (core's unavailable:'ssh')", async () => {
+ const { deps, writes } = harness()
+ ;(deps.createHeadless as ReturnType<typeof vi.fn>).mockImplementation(async () => ({
+ sessionId: 's',
+ fresh: true,
+ unavailable: 'ssh' as const
+ }))
+ const r = desktopHeadlessRequest({
+ ptyOptions: { ...opts, sshRemote: ssh, requireRemote: true },
+ command: CMD
+ })
+ expect(await launchHeadless(deps, r)).toMatchObject({ outcome: 'failed', reason: 'spawn-failed' })
+ // What reached core carried the refusal flag, and no ControlMaster.
+ expect(deps.createHeadless).toHaveBeenCalledWith(
+ expect.objectContaining({ requireRemote: true, sshRemote: undefined })
+ )
+ expect(writes).toEqual([])
+ expect(deps.writeHeadless).not.toHaveBeenCalled()
+ })
+})
diff --git a/src/core/headless-launch.ts b/src/core/headless-launch.ts
index 250a8fa2d..d633d0030 100644
--- a/src/core/headless-launch.ts
+++ b/src/core/headless-launch.ts
@@ -35,6 +35,29 @@ export interface HeadlessLaunchDeps {
timing?: { quietMs: number; capMs: number; maxMs?: number }
}
+/**
+ * The desktop's `pty.launchHeadless` request, as main runs it: the renderer sends only
+ * `{ ptyOptions, command }`, and the desktop always releases its synthetic client, so it always
+ * 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").
+ */
+export function desktopHeadlessRequest(req: {
+ ptyOptions: PtyCreateOptions
+ command: string
+}): HeadlessLaunchRequest {
+ return {
+ ptyOptions: { ...req.ptyOptions, sshRemote: undefined },
+ command: String(req.command ?? ''),
+ release: true,
+ requirePersistent: true
+ }
+}
+
export async function launchHeadless(
deps: HeadlessLaunchDeps,
req: HeadlessLaunchRequest
diff --git a/src/main/index.ts b/src/main/index.ts
index 266e9cde5..c0cd91cbb 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -81,7 +81,7 @@ import type { RemoteLogExec } from '../core/board-log'
import type { PtyCreateOptions, TranscriptPresence } from '../shared/types'
import { boardLogRemotePath } from '../core/board-log'
import { PtyManager } from '../core/pty-manager'
-import { launchHeadless } from '../core/headless-launch'
+import { desktopHeadlessRequest, launchHeadless } from '../core/headless-launch'
import { WorkspaceStore } from '../core/workspace-store'
import type { CardLabelEdit } from '../core/project-kanban-write'
import { WorkspaceWatcher } from '../core/workspace-watcher'
@@ -1498,19 +1498,16 @@ app.whenReady().then(async () => {
// block below on the server side too — this one is here beside its sibling.
corePlatform.handle(IPC.ptySessionAge, (persistKey: string) => ptyManager.sessionAgeSeconds(persistKey))
- // #925: canvas-control `--run-now` / `run`. Registered here rather than in core's shared
- // `registerIpc` so no browser client can reach it: the Server Edition starts nodes through its
- // own factory. All logic lives in core/headless-launch. Local-only by construction: the
- // renderer never sends SSH fields for this, and this strips them anyway.
+ // #925: canvas-control `--run-now` / `run`, desktop only. Registered here rather than in core's
+ // 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.
corePlatform.handle(
IPC.ptyLaunchHeadless,
(req: { ptyOptions: PtyCreateOptions; command: string }) =>
- launchHeadless(ptyManager, {
- ptyOptions: { ...req.ptyOptions, sshRemote: undefined, requireRemote: undefined },
- command: String(req.command ?? ''),
- release: true,
- requirePersistent: true
- })
+ launchHeadless(ptyManager, desktopHeadlessRequest(req))
)
// Gemini's title read needs the transcript path its own context tail already tracks (nothing
diff --git a/src/shared/host-control.test.ts b/src/shared/host-control.test.ts
index d3f437287..d7d7a5798 100644
--- a/src/shared/host-control.test.ts
+++ b/src/shared/host-control.test.ts
@@ -28,6 +28,12 @@ describe('isHostOnlyChannel', () => {
expect(isHostOnlyChannel(IPC.projectSetupRequestTrust)).toBe(true)
})
+ it('covers pty:launch-headless — the desktop-only headless start is refused to relay peers (#925)', () => {
+ // A relay tab's own bridge already rejects it E_UNSUPPORTED, but that only stops a well-behaved
+ // guest. The host must refuse a peer that sends the raw request too (spec §6: Relay tab refuses).
+ expect(isHostOnlyChannel(IPC.ptyLaunchHeadless)).toBe(true)
+ })
+
it('leaves the read-only/lifecycle channels alone — the gate is on ACTION, not on the namespace', () => {
// Subscribing and receiving events costs a guest nothing the canvas does not already show;
// running host code, and answering the host's own trust prompt, are the two acts being gated.
diff --git a/src/shared/host-control.ts b/src/shared/host-control.ts
index bd3800392..a0c973d5c 100644
--- a/src/shared/host-control.ts
+++ b/src/shared/host-control.ts
@@ -21,6 +21,11 @@ import { IPC } from './ipc'
* consent-submit it is the same self-approval loop as run+consent-submit, ending in a shared
* `launchCmd`/`env` (or shell) approved for the host's own agent launches.
*
+ * - `pty:launch-headless` (#925) — the desktop's canvas-control `--run-now` / `run`: it starts a
+ * node's session with no viewer and types its launch on the host. The relay guest's own bridge
+ * already refuses it (a relay tab inherits ws-bridge's `pty`), and this makes the refusal hold
+ * host-side for a peer that sends the raw request (spec §6: "Relay tab | Refuses").
+ *
* DELIBERATELY NOT LISTED: `project-setup:subscribe`/`unsubscribe` and the `project-setup:event:*`
* push. They neither start nor authorize anything, and a peer that can see the canvas can already
* see that a setup is running. The gate is on ACTION, not on the namespace — which is also why
@@ -35,7 +40,8 @@ export const HOST_ONLY_CHANNELS: ReadonlySet<string> = new Set([
IPC.projectSetupRun,
IPC.projectSetupCancel,
IPC.projectSetupConsentSubmit,
- IPC.projectSetupRequestTrust
+ IPC.projectSetupRequestTrust,
+ IPC.ptyLaunchHeadless
])
/** What a refused peer is told. One wording, so the two shells answer identically. */