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(core): launchHeadless trusts a fresh shell the way the mounted writer does (#925)
review4e33ff7d7f40
diff --git a/src/core/headless-launch.test.ts b/src/core/headless-launch.test.tsindex 4216e8250..260c235ca 100644--- a/src/core/headless-launch.test.ts+++ b/src/core/headless-launch.test.ts@@ -77,13 +77,38 @@ describe('launchHeadless (#925)', () => {expect(deps.releaseHeadless).toHaveBeenCalledWith('n1')})- it('delivers into a non-persistent spawn when the caller does not require persistence', async () => {- const { deps, writes } = harness()+ // The pty IS the shell just spawned, and a plain shell has no tmux pane to ask: the real probe+ // answers null. Like the mounted writer (`trustsFreshShell`), a fresh one is trusted unprobed.+ it('delivers into a fresh non-persistent spawn without probing, when persistence is not required', async () => {+ const { deps, writes } = harness({ pane: null });(deps.createHeadless as ReturnType<typeof vi.fn>).mockResolvedValue({ sessionId: 's1', fresh: true, persistent: false })const p = launchHeadless(deps, req({ requirePersistent: false }))await vi.advanceTimersByTimeAsync(SETTLE_CAP_MS)expect(await p).toEqual({ outcome: 'delivered', fresh: true })expect(writes).toEqual([CMD, '\r'])+ expect(deps.paneCommand).not.toHaveBeenCalled()+ })++ // #916: the session host's probe walks the process tree and reads a prompt helper as "not a+ // shell", so a fresh session-host shell is trusted after the settle, as the mounted writer does.+ it('trusts a fresh session-host shell after the settle, without probing', async () => {+ const { deps, writes } = harness({ pane: 'git' })+ ;(deps.createHeadless as ReturnType<typeof vi.fn>).mockResolvedValue({ sessionId: 's1', fresh: true, persistent: true, sessionHost: true })+ const p = launchHeadless(deps, req())+ await vi.advanceTimersByTimeAsync(SETTLE_CAP_MS - 1)+ expect(writes).toEqual([])+ await vi.advanceTimersByTimeAsync(1)+ expect(await p).toEqual({ outcome: 'delivered', fresh: true })+ expect(writes).toEqual([CMD, '\r'])+ expect(deps.paneCommand).not.toHaveBeenCalled()+ })++ it('still probes a session-host session that already existed', async () => {+ const { deps, writes } = harness({ pane: 'git' })+ ;(deps.createHeadless as ReturnType<typeof vi.fn>).mockResolvedValue({ sessionId: 's1', fresh: false, persistent: true, sessionHost: true })+ expect(await launchHeadless(deps, req())).toEqual({ outcome: 'failed', reason: 'no-shell', fresh: false })+ expect(deps.paneCommand).toHaveBeenCalledWith('n1')+ expect(writes).toEqual([])})it('an older core that omits `persistent` counts as persistent', async () => {@@ -103,6 +128,8 @@ describe('launchHeadless (#925)', () => {await vi.advanceTimersByTimeAsync(1)expect(await p).toEqual({ outcome: 'delivered', fresh: true })expect(writes).toEqual([CMD, '\r'])+ // A fresh TMUX pane is still probed (it answers exactly, and covers the new-session -A race).+ expect(deps.paneCommand).toHaveBeenCalledWith('n1')expect(deps.releaseHeadless).toHaveBeenCalledWith('n1')// Both output taps (the settle's and the delivery's) are gone once the launch is over.expect(listeners.size).toBe(0)diff --git a/src/core/headless-launch.ts b/src/core/headless-launch.tsindex 49362148d..1d5986a1a 100644--- a/src/core/headless-launch.ts+++ b/src/core/headless-launch.ts@@ -1,7 +1,9 @@// The headless launcher (#925): start a node's session with no viewer and deliver its launch-// command exactly the way a mounted terminal does — settle, prove a shell owns the pane, then the-// echo-verified writer (@shared/command-delivery). The desktop runs it for canvas-control-// `--run-now` / `run`; the Server Edition runs it for every immediate open.+// command by the rule a mounted terminal's automatic launch writer applies — settle a fresh shell,+// then either trust it (`trustsFreshShell`: a fresh plain shell or session-host session, whose+// probe is useless or unreliable) or prove a shell owns the pane, then the echo-verified writer+// (@shared/command-delivery). The desktop runs it for canvas-control `--run-now` / `run`; the+// Server Edition runs it for every immediate open.//// Never a blind paste: zsh's rc/ZLE setup FLUSHES the tty (#556) and a canonical-mode line is cut// at the tty's cap (#706). A tmux paste is not immune to either, which is why the desktop rule@@ -9,6 +11,7 @@import { deliverCommand, type DeliveryIo, type DeliveryOutcome } from '../shared/command-delivery'import { isLaunchShell } from '../shared/agents/pane'import type { HeadlessLaunchRequest, HeadlessLaunchResult } from '../shared/headless-launch'+import { trustsFreshShell } from '../shared/launch-trust'import { shellKillLineSequence } from '../shared/shell-kill-line'import type { PtyCreateOptions, PtyCreateResult } from '../shared/types'@@ -50,19 +53,30 @@ export async function launchHeadless(// The probe above can be stale by the time the spawn lands (tmux switched off in between), and// a plain shell dies with the client this launcher is about to release — typing a launch into// it would start an agent only to kill it. `persistent` absent = an older core, persistent by- // the field's own contract (`PtyCreateResult.persistent`, and `trustsFreshShell` reads it so).+ // the field's own contract (`PtyCreateResult.persistent`; `trustsFreshShell` reads it so too).if (req.requirePersistent && created.persistent === false) {return { outcome: 'failed', reason: 'not-persistent', fresh }}if (fresh) await settle(deps, key)- let pane: string | null- try {- pane = await deps.paneCommand(key)- } catch {- pane = null+ // The mounted writer's rule, not a stricter one: a fresh plain shell has no pane to ask (the+ // probe answers null) and a fresh session-host probe misreads a prompt helper (#916). Every+ // other session — a fresh tmux pane included — must prove a shell owns it.+ const trusted = trustsFreshShell({+ manual: false,+ fresh,+ persistent: created.persistent,+ sessionHost: created.sessionHost+ })+ if (!trusted) {+ let pane: string | null+ try {+ pane = await deps.paneCommand(key)+ } catch {+ pane = null+ }+ // Unknown is not a shell: an un-typed launch is recoverable (Run now), a spliced one is not.+ if (!isLaunchShell(pane)) return { outcome: 'failed', reason: 'no-shell', fresh }}- // Unknown is not a shell: an un-typed launch is recoverable (Run now), a spliced one is not.- if (!isLaunchShell(pane)) return { outcome: 'failed', reason: 'no-shell', fresh }const killLine = shellKillLineSequence(undefined, req.ptyOptions.shell)const outcome = await deliver(deps, key, req.command, killLine, !fresh)return outcome === 'submitted'diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsxindex c70dccb2e..129d72f46 100644--- a/src/renderer/nodes/TerminalNode.tsx+++ b/src/renderer/nodes/TerminalNode.tsx@@ -9,7 +9,8 @@ import { installGlassCellBackgrounds, scheduleGlassCellAlpha, setGlassCellAlphaimport { deliverRelayInitialLaunch } from '../terminal/relay-initial-launch'import { commitLaunch } from '../terminal/launch-attempt'import { isLaunchShell } from '@shared/agents/pane'-import { createLaunchWriter, deliverInitialLaunch, launchCommand, registerLaunchWriter, trustsFreshShell } from '../terminal/launch-command'+import { createLaunchWriter, deliverInitialLaunch, launchCommand, registerLaunchWriter } from '../terminal/launch-command'+import { trustsFreshShell } from '@shared/launch-trust'import { Suspense, lazy, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'import { NODE_MIN_SIZES } from '../lib/nodeSizing'import {diff --git a/src/renderer/terminal/launch-command.test.ts b/src/renderer/terminal/launch-command.test.tsindex 661a159b1..3a689e946 100644--- a/src/renderer/terminal/launch-command.test.ts+++ b/src/renderer/terminal/launch-command.test.ts@@ -1,7 +1,8 @@import { commitLaunchAttempt } from './launch-attempt'import type { PendingLaunch } from '@shared/types'import { afterEach, describe, expect, it, vi } from 'vitest'-import { createLaunchWriter, deliverInitialLaunch, launchCommand, registerLaunchWriter, trustsFreshShell } from './launch-command'+import { createLaunchWriter, deliverInitialLaunch, launchCommand, registerLaunchWriter } from './launch-command'+import { trustsFreshShell } from '@shared/launch-trust'import { KILL_LINE, WINDOWS_KILL_LINE, VERIFY_TIMEOUT_MS, DELIVERY_ATTEMPTS } from '@shared/command-delivery'function fixture(attempted = false, killLine = KILL_LINE) {diff --git a/src/renderer/terminal/launch-command.ts b/src/renderer/terminal/launch-command.tsindex 55e4956b8..ff17c5203 100644--- a/src/renderer/terminal/launch-command.ts+++ b/src/renderer/terminal/launch-command.ts@@ -14,25 +14,6 @@ function writersFor(scope: object): Map<string, Writer> {if (!writers) { writers = new Map(); scopedWriters.set(scope, writers) }return writers}-/**- * May an AUTOMATIC launch skip the pane probe and trust that a shell owns the pane? Only for a- * fresh session whose probe is either unneeded or unreliable:- * - a plain shell (`persistent:false`) — the pty IS the shell we just spawned;- * - a session-host session — its probe is a process-tree walk that reads a prompt helper (a `git`- * or `starship` child) as "not a shell", which stalled every fresh Windows launch (#916).- * A fresh TMUX pane is still probed: tmux answers exactly, and the probe covers the- * `new-session -A` race where another client created (and may already be running in) the session.- * `persistent` absent = an older core, treated as tmux, like everywhere else.- */-export function trustsFreshShell(opts: {- manual: boolean- fresh: boolean- persistent?: boolean- sessionHost?: boolean-}): boolean {- if (opts.manual || !opts.fresh) return false- return opts.persistent === false || opts.sessionHost === true-}export function registerLaunchWriter(id: string, writer: Writer, scope: object = defaultScope): () => void {const writers = writersFor(scope)diff --git a/src/shared/launch-trust.ts b/src/shared/launch-trust.tsnew file mode 100644index 000000000..b37580c4e--- /dev/null+++ b/src/shared/launch-trust.ts@@ -0,0 +1,22 @@+// When an automatic launch may skip the pane probe. Shared because the renderer's mounted launch+// writer (terminal/launch-command.ts) and core's headless launcher (#925) must apply ONE rule.++/**+ * May an AUTOMATIC launch skip the pane probe and trust that a shell owns the pane? Only for a+ * fresh session whose probe is either unneeded or unreliable:+ * - a plain shell (`persistent:false`) — the pty IS the shell we just spawned;+ * - a session-host session — its probe is a process-tree walk that reads a prompt helper (a `git`+ * or `starship` child) as "not a shell", which stalled every fresh Windows launch (#916).+ * A fresh TMUX pane is still probed: tmux answers exactly, and the probe covers the+ * `new-session -A` race where another client created (and may already be running in) the session.+ * `persistent` absent = an older core, treated as tmux, like everywhere else.+ */+export function trustsFreshShell(opts: {+ manual: boolean+ fresh: boolean+ persistent?: boolean+ sessionHost?: boolean+}): boolean {+ if (opts.manual || !opts.fresh) return false+ return opts.persistent === false || opts.sessionHost === true+}