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): an absolute ceiling on the headless settle; docs name only what PR 1 wires
review332d07c62913
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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 mobilegraphs through project switches/park expiry. Attempted/legacy-unknown intent stays manual: itsclearing autosave may have been lost after Enter. Explicit Run now rechecks the foreground shell andclears 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 intentinto a never-attempted `pendingLaunch`, including a project switch during shell settle. A liveinitialCommand alias on remount cannot reset an attempted marker. Server savesdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 comuntil delivery is acknowledged, and report `queued` while it is held. A successful terminal sendproves 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 mayproceed after shell verification; attempted/legacy-unknown intent requires Run now. Only confirmeddiff --git a/src/core/headless-launch.test.ts b/src/core/headless-launch.test.tsindex 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.tsindex 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 = 200export 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 = 5000export interface HeadlessLaunchDeps {persistentSpawnAvailable(): boolean@@ -27,8 +31,8 @@ export interface HeadlessLaunchDeps {writeHeadless(persistKey: string, data: string): booleanonOutput(persistKey: string, cb: (chunk: string) => void): () => voidreleaseHeadless(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_MSconst capMs = deps.timing?.capMs ?? SETTLE_CAP_MS+ const maxMs = deps.timing?.maxMs ?? SETTLE_MAX_MSreturn new Promise((resolve) => {let done = falselet unsub: (() => void) | undefined@@ -97,15 +111,24 @@ function settle(deps: HeadlessLaunchDeps, key: string): Promise<void> {if (done) returndone = trueclearTimeout(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()+ }})}