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): an absolute ceiling on the headless settle; docs name only what PR 1 wires

review332d07c62913
diff --git a/CLAUDE.md b/CLAUDE.md
index d0ee087ea..ec9cf8886 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -3095,10 +3095,10 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile
graphs through project switches/park expiry. Attempted/legacy-unknown intent stays manual: its
clearing autosave may have been lost after Enter. Explicit Run now rechecks the foreground shell and
clears any incomplete line; a refused/throwing/cancelled launch stays held, `manualOnly`.
- Headless starts (`core/headless-launch.ts`, #925) and the Server Edition's immediate open deliver
- through the SAME echo-verified writer (`@shared/command-delivery`, moved out of the renderer for
- this): a tmux paste is not immune to zsh's rc-time tty flush (#556) or the canonical-line cap
- (#706).
+ The Server Edition's immediate open delivers through the SAME echo-verified writer
+ (`@shared/command-delivery`, moved out of the renderer for this), via the headless launcher
+ `core/headless-launch.ts` (#925): a tmux paste is not immune to zsh's rc-time tty flush (#556) or
+ the canonical-line cap (#706).
(5) UI `initialCommand` stays until submission; serialization converts unsubmitted UI intent
into a never-attempted `pendingLaunch`, including a project switch during shell settle. A live
initialCommand alias on remount cannot reset an attempted marker. Server saves
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 80e42cb1b..02bc4db9d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -778,9 +778,9 @@ coordinate nodeterm, not external editors, so do not claim a filesystem-wide com
until delivery is acknowledged, and report `queued` while it is held. A successful terminal send
proves delivery only; never describe it as a healthy/running agent without agent evidence.
Every launch uses the echo-verified command writer (`@shared/command-delivery`), not `sendText`:
-desktop automatic and Run now, the desktop headless start (`core/headless-launch.ts`), and the
-Server Edition's immediate open. The Server Edition's deferred `--after` release (`refreshArmed`)
-is the one remaining `sendText` launch, pending a move that must never create a session.
+desktop automatic and Run now, and the Server Edition's immediate open (through
+`core/headless-launch.ts`). The Server Edition's deferred `--after` release (`refreshArmed`) is the
+one remaining `sendText` launch, pending a move that must never create a session.
Keep unsubmitted UI intent durable through shell settle/unmount. New intent carries `attempted:false`;
Desktop and Server save `attempted:true` before input. Never-attempted warm `--after` launches may
proceed after shell verification; attempted/legacy-unknown intent requires Run now. Only confirmed
diff --git a/src/core/headless-launch.test.ts b/src/core/headless-launch.test.ts
index 260c235ca..d51a5ad98 100644
--- a/src/core/headless-launch.test.ts
+++ b/src/core/headless-launch.test.ts
@@ -1,7 +1,13 @@
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 { launchHeadless, SETTLE_CAP_MS, SETTLE_QUIET_MS, type HeadlessLaunchDeps } from './headless-launch'
+import {
+ launchHeadless,
+ SETTLE_CAP_MS,
+ SETTLE_MAX_MS,
+ SETTLE_QUIET_MS,
+ type HeadlessLaunchDeps
+} from './headless-launch'
import type { PtyManager } from './pty-manager'
const CMD = "claude 'fix the flaky test in the worker pool'"
@@ -146,6 +152,78 @@ describe('launchHeadless (#925)', () => {
expect(await p).toMatchObject({ outcome: 'delivered' })
})
+ // Review finding: the silence cap is cleared by the first chunk, so a pane that paints more often
+ // than the quiet window never settled — and the Server Edition awaits this inside its global
+ // control lock, so one such pane wedged every control verb behind it.
+ it('a pane that never stops painting still reaches the probe at SETTLE_MAX_MS, and not before', async () => {
+ const { deps, writes, emit, listeners } = harness()
+ let tapsAtProbe = -1
+ ;(deps.paneCommand as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+ tapsAtProbe = listeners.size
+ return 'zsh'
+ })
+ const p = launchHeadless(deps, req())
+ const painter = setInterval(() => emit('\x1b[2K\r⠋ loading'), 100)
+ await vi.advanceTimersByTimeAsync(SETTLE_MAX_MS - 1)
+ expect(deps.paneCommand).not.toHaveBeenCalled()
+ expect(writes).toEqual([])
+ await vi.advanceTimersByTimeAsync(1)
+ expect(deps.paneCommand).toHaveBeenCalledWith('n1')
+ // The ceiling exit unsubscribed the settle's tap before anything else ran.
+ expect(tapsAtProbe).toBe(0)
+ clearInterval(painter)
+ expect(await p).toEqual({ outcome: 'delivered', fresh: true })
+ expect(writes).toEqual([CMD, '\r'])
+ expect(listeners.size).toBe(0)
+ // No settle timer (quiet window or ceiling) outlives the launch.
+ expect(vi.getTimerCount()).toBe(0)
+ })
+
+ it('a pane that goes quiet settles on the quiet window, not the ceiling, and leaves no timer', async () => {
+ const { deps, emit } = harness()
+ const p = launchHeadless(deps, req())
+ const painter = setInterval(() => emit('rc output\r\n'), 100)
+ await vi.advanceTimersByTimeAsync(1000)
+ clearInterval(painter)
+ await vi.advanceTimersByTimeAsync(SETTLE_QUIET_MS - 1)
+ expect(deps.paneCommand).not.toHaveBeenCalled()
+ await vi.advanceTimersByTimeAsync(1)
+ expect(deps.paneCommand).toHaveBeenCalledWith('n1')
+ expect(await p).toEqual({ outcome: 'delivered', fresh: true })
+ expect(vi.getTimerCount()).toBe(0)
+ })
+
+ it('the silence cap exit disarms the ceiling too', async () => {
+ const { deps } = harness()
+ const p = launchHeadless(deps, req())
+ await vi.advanceTimersByTimeAsync(SETTLE_CAP_MS)
+ expect(await p).toEqual({ outcome: 'delivered', fresh: true })
+ expect(vi.getTimerCount()).toBe(0)
+ })
+
+ it('honours a ceiling passed through the timing seam', async () => {
+ const { deps, emit } = harness()
+ deps.timing = { quietMs: SETTLE_QUIET_MS, capMs: SETTLE_CAP_MS, maxMs: 700 }
+ const p = launchHeadless(deps, req())
+ const painter = setInterval(() => emit('.'), 100)
+ await vi.advanceTimersByTimeAsync(699)
+ expect(deps.paneCommand).not.toHaveBeenCalled()
+ await vi.advanceTimersByTimeAsync(1)
+ expect(deps.paneCommand).toHaveBeenCalledWith('n1')
+ clearInterval(painter)
+ expect(await p).toEqual({ outcome: 'delivered', fresh: true })
+ })
+
+ it('an output tap that cannot be opened ends the launch without leaving a timer armed', async () => {
+ const { deps, writes } = harness()
+ ;(deps.onOutput as ReturnType<typeof vi.fn>).mockImplementation(() => {
+ throw new Error('session gone')
+ })
+ expect(await launchHeadless(deps, req())).toEqual({ outcome: 'failed', reason: 'cancelled', fresh: true })
+ expect(writes).toEqual([])
+ expect(vi.getTimerCount()).toBe(0)
+ })
+
it('an existing session skips the settle and clears any pending input first', async () => {
const { deps, writes } = harness({ fresh: false })
expect(await launchHeadless(deps, req())).toEqual({ outcome: 'delivered', fresh: false })
diff --git a/src/core/headless-launch.ts b/src/core/headless-launch.ts
index 1d5986a1a..250a8fa2d 100644
--- a/src/core/headless-launch.ts
+++ b/src/core/headless-launch.ts
@@ -19,6 +19,10 @@ import type { PtyCreateOptions, PtyCreateResult } from '../shared/types'
* 1500 ms of total silence = write anyway. */
export const SETTLE_QUIET_MS = 200
export const SETTLE_CAP_MS = 1500
+/** Absolute ceiling on the whole settle, which output never extends. A pane that paints more often
+ * than every SETTLE_QUIET_MS (a spinner, a chatty rc file) never goes quiet, and nothing else would
+ * end the wait. */
+export const SETTLE_MAX_MS = 5000
export interface HeadlessLaunchDeps {
persistentSpawnAvailable(): boolean
@@ -27,8 +31,8 @@ export interface HeadlessLaunchDeps {
writeHeadless(persistKey: string, data: string): boolean
onOutput(persistKey: string, cb: (chunk: string) => void): () => void
releaseHeadless(persistKey: string): void
- /** Test seam; production uses SETTLE_QUIET_MS / SETTLE_CAP_MS. */
- timing?: { quietMs: number; capMs: number }
+ /** Test seam; production uses SETTLE_QUIET_MS / SETTLE_CAP_MS / SETTLE_MAX_MS. */
+ timing?: { quietMs: number; capMs: number; maxMs?: number }
}
export async function launchHeadless(
@@ -87,9 +91,19 @@ export async function launchHeadless(
}
}
+/**
+ * Wait for a fresh shell's prompt. This mirrors TerminalNode's `whenShellSettled` (SETTLE_QUIET_MS
+ * of quiet after output, SETTLE_CAP_MS when there is no output at all), plus an absolute ceiling
+ * (SETTLE_MAX_MS) that output never extends. The mounted version can do without one, because an
+ * unmount cancels it. Nothing cancels this one, and the Server Edition awaits it inside its global
+ * control lock, so a pane that paints more often than the quiet window would wedge every control
+ * verb. Reaching the ceiling proceeds exactly as a settle does. The echo-verified writer is the
+ * safety net for a line typed mid-print.
+ */
function settle(deps: HeadlessLaunchDeps, key: string): Promise<void> {
const quietMs = deps.timing?.quietMs ?? SETTLE_QUIET_MS
const capMs = deps.timing?.capMs ?? SETTLE_CAP_MS
+ const maxMs = deps.timing?.maxMs ?? SETTLE_MAX_MS
return new Promise((resolve) => {
let done = false
let unsub: (() => void) | undefined
@@ -97,15 +111,24 @@ function settle(deps: HeadlessLaunchDeps, key: string): Promise<void> {
if (done) return
done = true
clearTimeout(timer)
+ clearTimeout(ceiling)
unsub?.()
resolve()
}
+ // Armed once, never re-armed by output.
+ const ceiling = setTimeout(finish, maxMs)
let timer = setTimeout(finish, capMs)
- unsub = deps.onOutput(key, () => {
- if (done) return
- clearTimeout(timer)
- timer = setTimeout(finish, quietMs)
- })
+ try {
+ unsub = deps.onOutput(key, () => {
+ if (done) return
+ clearTimeout(timer)
+ timer = setTimeout(finish, quietMs)
+ })
+ } catch {
+ // No tap to watch. Clear the timers and move on: the delivery opens its own tap, and its
+ // failure ends the launch as `cancelled`.
+ finish()
+ }
})
}