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(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.ts
index 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.ts
index 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.tsx
index c70dccb2e..129d72f46 100644
--- a/src/renderer/nodes/TerminalNode.tsx
+++ b/src/renderer/nodes/TerminalNode.tsx
@@ -9,7 +9,8 @@ import { installGlassCellBackgrounds, scheduleGlassCellAlpha, setGlassCellAlpha
import { 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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
+}