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(canvas): a `--after` node released offscreen still fires its launch
enesdd1193e1efea
diff --git a/CLAUDE.md b/CLAUDE.mdindex d812b106b..310a07478 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -495,6 +495,14 @@ Lifecycle, by intent:landed. The predicate is deliberately the narrowest one that closes it — a tmux-backed session isnever protected (the kill costs a redraw), and neither is a plain terminal, a finished agent oran unknown state (nothing is running to lose). **A fifth lever owes the same gate.**+ The fifth is the offscreen release of an ARMED node (`--after`, `shouldDeferReleaseForHeldLaunch`,+ 2026-09-02): the held launch is delivered by session NAME, so with tmux underneath the release is+ harmless and the node stays `sessionReady` (the teardown keeps the flag for an offscreen release+ of a tmux-backed session); on the plain-shell fallback the release would destroy the very pane+ the launch is typed into, so it is deferred while armed. MEASURED before the fix: a released+ QUEUED node held its launch through its dependency going `done`, the badge claimed the terminal+ "has not started yet", and only a camera travel (revive) ever fired it — "the chain works when I+ look at it" was this.- **Node unmount (project switch)** → the RENDERER **parks** the terminal (`TerminalNode.tsx``parkedTerminals`): the xterm instance + its attached PTY stay alive with the `.xterm` elementdetached from the DOM, so a remount within `TERM_PARK_MS` (5 min) re-adopts them — instant, anddiff --git a/src/renderer/lib/pendingLaunch.test.ts b/src/renderer/lib/pendingLaunch.test.tsindex 57a20f249..a4524e15e 100644--- a/src/renderer/lib/pendingLaunch.test.ts+++ b/src/renderer/lib/pendingLaunch.test.ts@@ -58,6 +58,37 @@ describe('launchesToFire', () => {it('fires immediately when there are no deps left to wait on', () => {expect(launchesToFire([armed('c', [])], {}, live)).toEqual([{ id: 'c', command: 'echo c' }])})++ it('walks a chain A → B → C one station at a time', () => {+ const chain = [armed('b', ['a']), armed('c', ['b'])]+ // Nothing has reported: nothing fires.+ expect(launchesToFire(chain, {}, live)).toEqual([])+ // A done releases B only — C waits on B, which has not even started.+ expect(launchesToFire(chain, { a: { state: 'done' } }, live)).toEqual([{ id: 'b', command: 'echo b' }])+ // B running is still not B done.+ expect(launchesToFire(chain, { a: { state: 'done' }, b: { state: 'working' } }, live)).toEqual([+ { id: 'b', command: 'echo b' }+ ])+ // B done releases C. (B is still listed here because the caller, not this function, retires a+ // delivered launch by clearing its pendingLaunch — exactly-once lives in `launchInFlight`.)+ expect(launchesToFire(chain, { a: { state: 'done' }, b: { state: 'done' } }, live)).toEqual([+ { id: 'b', command: 'echo b' },+ { id: 'c', command: 'echo c' }+ ])+ })++ it('after a restart (empty status map) a persisted arming holds — nothing will report, ▶ is the escape', () => {+ // Agent state is transient; a live dep that reported `done` before the restart is unknown now,+ // and unknown is NOT satisfied. The manual run-now on the badge exists for exactly this.+ expect(launchesToFire([armed('c', ['a'])], {}, live)).toEqual([])+ expect(unmetDeps(armed('c', ['a']), {}, live)).toEqual(['a'])+ })++ it('a dep deleted mid-chain releases what waited on it, but not what waits further down', () => {+ const chain = [armed('b', ['a']), armed('c', ['b'])]+ const liveWithoutA = new Set(['b', 'c'])+ expect(launchesToFire(chain, {}, liveWithoutA)).toEqual([{ id: 'b', command: 'echo b' }])+ })})describe('launchesToFire — awaitSetupGroup (a worktree whose setup script must land first)', () => {diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsxindex 4fe4e151c..6f24ca6af 100644--- a/src/renderer/nodes/TerminalNode.tsx+++ b/src/renderer/nodes/TerminalNode.tsx@@ -82,6 +82,7 @@ import {planOffscreenVisibility,releaseStillEnabled,shouldDeferReleaseForEco,+ shouldDeferReleaseForHeldLaunch,shouldDeferReleaseForLiveWork,OFFSCREEN_DEFER_RETRY_MS,OFFSCREEN_DISPOSE_MS_DEFAULT@@ -855,9 +856,10 @@ const restartSubs = new Map<string, () => void>()** ABSENT = not ready, which is the safe direction: it holds the launch (visibly — see* `useLaunchDelivery`) instead of burning it against a session that is not there. Published by the- * node itself, since nothing else can see the spawn resolve. A PARKED session stays ready — it is- * still a live tmux session addressable by name — and only a real teardown (respawn, offscreen- * dispose, delete) clears it.+ * node itself, since nothing else can see the spawn resolve. A PARKED session stays ready, and so+ * does one whose viewer was RELEASED offscreen while tmux is underneath — both are still a live+ * tmux session addressable by name; only a teardown that ends the session (respawn, delete, or the+ * release of a plain-shell session) clears it.*/const sessionReadyNodes = new Set<string>()const sessionReadySubs = new Set<(nodeId: string) => void>()@@ -1351,6 +1353,10 @@ export function TerminalNode({// with — it can be off-screen mid-drag or right after a ⌘K jump — so it is never taken down.const selectedRef = useRef(selected)selectedRef.current = selected+ // Is this node holding a `--after` launch? Read at release FIRE time (see `fireRelease`) — the+ // hold ends when the launch fires, and a plan made at arm time would not know.+ const armedRef = useRef(!!data.pendingLaunch)+ armedRef.current = !!data.pendingLaunch// --- glyphgrid (experimental shared renderer) ---// This node's registered grid, published by the lifecycle effect so the position effect can push// an origin without re-running (and therefore respawning) the terminal. Null for every terminal@@ -3957,10 +3963,17 @@ export function TerminalNode({// EARLIER effect (this terminal may have been adopted from a park) sees the session die here// and tears down instead of wiring listeners onto it; `killSession` keeps the kill single.life.dead = true- // A real teardown (respawn, offscreen dispose, delete) ends the session this node published- // as ready. A PARK does not, and returns above without reaching here — a parked session is- // still a live tmux session addressable by name, so it stays typeable.- setSessionReady(id, false)+ // A real teardown (respawn, delete) ends the session this node published as ready. A PARK+ // does not, and returns above without reaching here — a parked session is still a live tmux+ // session addressable by name, so it stays typeable. An OFFSCREEN RELEASE of a tmux-backed+ // session is the same fact from the other side: only the viewer goes, the session keeps+ // running and `sendText` reaches it by name — so readiness is kept. MEASURED (2026-09-02):+ // clearing it here held a released `--after` node's launch through its dependency going+ // `done`, with the badge claiming the terminal "has not started yet", until a camera travel+ // revived the node and it fired at once. The plain-shell fallback never reaches this branch+ // armed — `shouldDeferReleaseForHeldLaunch` holds the release there — and a respawn while+ // down is not a release (the effect early-returned, so there is no session to keep).+ if (!(offscreenDownRef.current && sessionPersistent)) setSessionReady(id, false)cleanups.forEach((fn) => fn())if (sessionId) killSession(sessionId)term.dispose()@@ -4099,6 +4112,22 @@ export function TerminalNode({offscreenTimerRef.current = setTimeout(fireRelease, OFFSCREEN_DEFER_RETRY_MS)return}+ // A HELD LAUNCH ON A PLAIN SHELL (the fifth lever): the `--after` launch this node holds+ // is typed into the pane by session name, and without tmux the release destroys that+ // pane. Nothing brings a released node back but the camera, so the launch would sit+ // QUEUED until the user happened to pan over it. Same cadence, same drain: the hold+ // ends when the launch fires. (Tmux-backed: released as normal — see the teardown,+ // which keeps such a session READY because it stays typeable by name.)+ if (+ shouldDeferReleaseForHeldLaunch({+ tmuxBacked: sessionPersistentRef.current,+ armed: armedRef.current+ })+ ) {+ offscreenSinceRef.current = Date.now()+ offscreenTimerRef.current = setTimeout(fireRelease, OFFSCREEN_DEFER_RETRY_MS)+ return+ }// ECO ORDERING (see `shouldDeferReleaseForEco`): hibernate first, release second. This// release would UNWIRE the node — the lifecycle effect tears down, the hibernate pair// unregisters, and `planHibernation` then reads the node as unwired — and at thediff --git a/src/renderer/nodes/session-ready-signal.test.ts b/src/renderer/nodes/session-ready-signal.test.tsindex 84afa1abb..aa4947365 100644--- a/src/renderer/nodes/session-ready-signal.test.ts+++ b/src/renderer/nodes/session-ready-signal.test.ts@@ -47,13 +47,34 @@ describe('where readiness is published (source pins)', () => {it('only a REAL teardown clears it — a park keeps the session typeable by name', () => {// The park branch returns before this line; a parked tmux session is still addressable by// `sendText`, so clearing there would strand a launch that could have been delivered.- expect(src).toMatch(/life\.dead = true[\s\S]{0,600}?setSessionReady\(id, false\)/)+ expect(src).toMatch(/life\.dead = true[\s\S]{0,1800}?setSessionReady\(id, false\)/)// Exactly three publish sites: mount (adopt-or-not), settle, teardown. A fourth means// somebody has taught another path to claim readiness it cannot vouch for.expect(src.match(/setSessionReady\(/g)?.length).toBe(4) // 3 call sites + the definition})})+describe('an offscreen release keeps a tmux-backed session READY (source pins)', () => {+ it('the teardown clears readiness only when the session itself is going away', () => {+ // MEASURED (2026-09-02, scratch Server Edition, hook POSTs): an armed node released offscreen+ // — PTY client detached, tmux session alive and typeable by name — reported not-ready, so its+ // dependency going `done` delivered nothing, the badge claimed the terminal "has not started+ // yet", and only a camera travel (revive) ever fired the launch. The release is a viewer+ // teardown, not a session teardown, so it must not withdraw the fact the gate asks about.+ expect(src).toMatch(+ /life\.dead = true[\s\S]{0,1800}?if \(!\(offscreenDownRef\.current && sessionPersistent\)\) setSessionReady\(id, false\)/+ )+ })++ it('a PLAIN-SHELL armed node is not released at all — there the release kills the shell', () => {+ // Fifth lever behind issue #126's rule: the pure predicate decides, the node only asks it, on+ // the same retry cadence the live-work deferral uses.+ expect(src).toMatch(+ /shouldDeferReleaseForHeldLaunch\(\{[\s\S]{0,200}?tmuxBacked: sessionPersistentRef\.current,[\s\S]{0,120}?armed: armedRef\.current/+ )+ })+})+describe('an ARMED node does not cold-start its agent under the hold (source pins)', () => {it('the cold-restore relaunch is gated on there being no pendingLaunch', () => {// A first open is `fresh` by definition, so without this every `--after` / `verify` nodediff --git a/src/renderer/terminal/offscreen-policy.test.ts b/src/renderer/terminal/offscreen-policy.test.tsindex 602ef1741..f4a3aa71f 100644--- a/src/renderer/terminal/offscreen-policy.test.ts+++ b/src/renderer/terminal/offscreen-policy.test.ts@@ -9,6 +9,7 @@ import {offscreenCoreIsRemote,planOffscreenVisibility,shouldDeferReleaseForEco,+ shouldDeferReleaseForHeldLaunch,shouldDeferReleaseForLiveWork} from './offscreen-policy'@@ -219,3 +220,18 @@ describe('releaseStillEnabled — the fire-time re-ask of the setting itself', (expect(releaseStillEnabled(-5)).toBe(false)})})++describe('shouldDeferReleaseForHeldLaunch — the fifth kill lever: an armed node holds a launch', () => {+ it('defers a PLAIN-SHELL node that is still armed — the release would kill the shell the launch needs', () => {+ expect(shouldDeferReleaseForHeldLaunch({ tmuxBacked: false, armed: true })).toBe(true)+ })++ it('never defers a TMUX-BACKED armed node — its session stays typeable by name through a release', () => {+ expect(shouldDeferReleaseForHeldLaunch({ tmuxBacked: true, armed: true })).toBe(false)+ })++ it('never defers a node that is not armed, on either backend', () => {+ expect(shouldDeferReleaseForHeldLaunch({ tmuxBacked: false, armed: false })).toBe(false)+ expect(shouldDeferReleaseForHeldLaunch({ tmuxBacked: true, armed: false })).toBe(false)+ })+})diff --git a/src/renderer/terminal/offscreen-policy.ts b/src/renderer/terminal/offscreen-policy.tsindex 4ed36f555..276666bbd 100644--- a/src/renderer/terminal/offscreen-policy.ts+++ b/src/renderer/terminal/offscreen-policy.ts@@ -107,6 +107,21 @@ export function shouldDeferReleaseForLiveWork(i: LiveWorkInput): boolean {return wouldKillLiveWork(i)}+/**+ * THE FIFTH LEVER (CLAUDE.md: "a fifth lever owes the same gate"): an ARMED node — one holding a+ * `pendingLaunch` for the canvas-control `--after` edge — has work a kill would strand, even though+ * nothing is running in it yet. The launch is delivered by session NAME (`sendText` → tmux+ * paste-buffer), so with tmux underneath a release is harmless: the client detaches, the session+ * stays typeable, and the launch still lands. On the plain-shell fallback the pty IS the shell, so+ * the same release destroys the pane the launch was going to be typed into, and nothing revives a+ * released node except the camera coming back — the launch is held until someone happens to look.+ * Same shape as `shouldDeferReleaseForLiveWork`, and uncapped for the same reason: what this waits+ * for (the launch firing, or the user disarming it) always ends the hold.+ */+export function shouldDeferReleaseForHeldLaunch(i: { tmuxBacked: boolean; armed: boolean }): boolean {+ return !i.tmuxBacked && i.armed+}+/*** PHASE 5 ORDERING: with Eco on, releasing an offscreen terminal's viewer WAITS for its agent to* hibernate first.