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(canvas): a `--after` node released offscreen still fires its launch

enesdd1193e1efea
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 is
never protected (the kill costs a redraw), and neither is a plain terminal, a finished agent or
an 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` element
detached from the DOM, so a remount within `TERM_PARK_MS` (5 min) re-adopts them — instant, and
diff --git a/src/renderer/lib/pendingLaunch.test.ts b/src/renderer/lib/pendingLaunch.test.ts
index 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.tsx
index 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 the
diff --git a/src/renderer/nodes/session-ready-signal.test.ts b/src/renderer/nodes/session-ready-signal.test.ts
index 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` node
diff --git a/src/renderer/terminal/offscreen-policy.test.ts b/src/renderer/terminal/offscreen-policy.test.ts
index 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.ts
index 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.