@crouton-kit/crouter 0.3.16 → 0.3.17

package/dist/core/canvas/browse/terminal.d.ts

@@ -0,0 +1,23 @@
+export interface Key {
+    upArrow: boolean;
+    downArrow: boolean;
+    leftArrow: boolean;
+    rightArrow: boolean;
+    return: boolean;
+    escape: boolean;
+    ctrl: boolean;
+    meta: boolean;
+    tab: boolean;
+    shiftTab: boolean;
+    backspace: boolean;
+}
+export declare function parseKeypress(data: Buffer): {
+    input: string;
+    key: Key;
+};
+export declare function setupTerminal(): void;
+export declare function restoreTerminal(): void;
+export declare function getTerminalSize(): {
+    cols: number;
+    rows: number;
+};

package/dist/core/canvas/browse/terminal.js

@@ -0,0 +1,100 @@
+// terminal.ts — raw-mode helpers for the `crtr canvas browse` TUI.
+//
+// Hand-rolled (no deps), mirroring humanloop's src/tui/terminal.ts. Extends its
+// key parsing beyond up/down/return/escape/tab/backspace/ctrl + printable input:
+// adds leftArrow/rightArrow (cursor keys) and shiftTab (`\x1b[Z`) so the browser
+// can drive tree expand/collapse and tab cycling.
+function emptyKey() {
+    return {
+        upArrow: false,
+        downArrow: false,
+        leftArrow: false,
+        rightArrow: false,
+        return: false,
+        escape: false,
+        ctrl: false,
+        meta: false,
+        tab: false,
+        shiftTab: false,
+        backspace: false,
+    };
+}
+export function parseKeypress(data) {
+    const str = data.toString('utf8');
+    const key = emptyKey();
+    if (str === '\x1b[A') {
+        key.upArrow = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b[B') {
+        key.downArrow = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b[C') {
+        key.rightArrow = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b[D') {
+        key.leftArrow = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b[Z') {
+        key.shiftTab = true;
+        return { input: '', key };
+    }
+    if (str === '\r' || str === '\n') {
+        key.return = true;
+        return { input: '', key };
+    }
+    // Alt+Backspace: terminals send ESC followed by DEL/BS. Must precede the
+    // bare-ESC check so the two-byte sequence isn't swallowed as plain escape.
+    if (str === '\x1b\x7f' || str === '\x1b\b') {
+        key.meta = true;
+        key.backspace = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b') {
+        key.escape = true;
+        return { input: '', key };
+    }
+    if (str === '\t') {
+        key.tab = true;
+        return { input: '', key };
+    }
+    if (str === '\x7f' || str === '\b') {
+        key.backspace = true;
+        return { input: '', key };
+    }
+    if (str.length === 1 && str.charCodeAt(0) < 32) {
+        key.ctrl = true;
+        const ch = String.fromCharCode(str.charCodeAt(0) + 64).toLowerCase();
+        return { input: ch, key };
+    }
+    // Multi-byte chunks (paste, multi-byte UTF-8, unknown escape sequences) are
+    // returned as-is in `input`; the input-mode handler sanitises them before
+    // appending to its buffer. Top-level handlers ignore strings of length > 1.
+    return { input: str, key };
+}
+export function setupTerminal() {
+    if (!process.stdin.isTTY) {
+        throw new Error('crtr canvas browse requires an interactive terminal (TTY)');
+    }
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    process.stdout.write('\x1b[?25l'); // hide cursor
+    process.stdout.write('\x1b[?1049h'); // alt screen
+    process.stdout.write('\x1b[2J\x1b[H'); // clear
+}
+export function restoreTerminal() {
+    process.stdout.write('\x1b[?25h'); // show cursor
+    process.stdout.write('\x1b[?1049l'); // restore screen
+    process.stdin.setRawMode(false);
+    process.stdin.pause();
+}
+export function getTerminalSize() {
+    return {
+        cols: process.stdout.columns || 80,
+        rows: process.stdout.rows || 24,
+    };
+}

package/dist/core/canvas/canvas.d.ts

@@ -86,8 +86,14 @@ export interface PruneResult {
  *  `created` is older than `ttlDays`, bounding the otherwise-unbounded growth of
  *  node rows + dirs. The edges→nodes FK (`ON DELETE CASCADE`, migration v4) GCs
  *  each pruned node's edges automatically; the on-disk `nodes/<id>/` dir is
- *  removed too. Live nodes are NEVER touched: active | idle are the daemon's
- *  domain, a DISJOINT status set, so prune and supervision can't interfere.
+ *  removed too.
+ *
+ *  With `includeStale`, ALSO prunes nominally-live (active | idle) nodes past the
+ *  TTL whose process is provably gone — `pi_pid` is NULL or no longer alive. This
+ *  reaps stale roots (a bare `crtr` whose pi died without the row transitioning),
+ *  which the daemon's supervision never reconciled. A genuinely-running node keeps
+ *  a live `pi_pid`, so it is protected, as is the CALLER ($CRTR_NODE_ID). Without
+ *  the flag, active | idle are NEVER touched (the daemon's domain).
  *
  *  The row deletes run in ONE transaction (so the sweep is all-or-nothing); the
  *  dir removals follow after COMMIT — the fs isn't transactional, and by then the
@@ -96,4 +102,5 @@ export interface PruneResult {
 export declare function pruneNodes(opts: {
     ttlDays: number;
     dryRun?: boolean;
+    includeStale?: boolean;
 }): PruneResult;

package/dist/core/canvas/canvas.js

@@ -352,12 +352,29 @@ export function rebuildIndex() {
             recordSpawn(meta.node_id, prov);
     }
 }
+/** Is `pid` a live process? `kill(pid, 0)` sends no signal — it only probes
+ *  existence/permission. ESRCH ⇒ gone; EPERM ⇒ alive but not ours (still alive). */
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
 /** Retention sweep: remove TERMINAL nodes (status dead | done | canceled) whose
  *  `created` is older than `ttlDays`, bounding the otherwise-unbounded growth of
  *  node rows + dirs. The edges→nodes FK (`ON DELETE CASCADE`, migration v4) GCs
  *  each pruned node's edges automatically; the on-disk `nodes/<id>/` dir is
- *  removed too. Live nodes are NEVER touched: active | idle are the daemon's
- *  domain, a DISJOINT status set, so prune and supervision can't interfere.
+ *  removed too.
+ *
+ *  With `includeStale`, ALSO prunes nominally-live (active | idle) nodes past the
+ *  TTL whose process is provably gone — `pi_pid` is NULL or no longer alive. This
+ *  reaps stale roots (a bare `crtr` whose pi died without the row transitioning),
+ *  which the daemon's supervision never reconciled. A genuinely-running node keeps
+ *  a live `pi_pid`, so it is protected, as is the CALLER ($CRTR_NODE_ID). Without
+ *  the flag, active | idle are NEVER touched (the daemon's domain).
  *
  *  The row deletes run in ONE transaction (so the sweep is all-or-nothing); the
  *  dir removals follow after COMMIT — the fs isn't transactional, and by then the
@@ -365,9 +382,11 @@ export function rebuildIndex() {
  *  reports the candidate set and deletes NOTHING. */
 export function pruneNodes(opts) {
     const dryRun = opts.dryRun ?? false;
+    const includeStale = opts.includeStale ?? false;
     const cutoff = new Date(Date.now() - opts.ttlDays * 86_400_000).toISOString();
+    const selfId = process.env['CRTR_NODE_ID'] ?? '';
     const db = openDb();
-    const candidates = db
+    const terminal = db
         .prepare(`SELECT node_id, status, created FROM nodes
          WHERE status IN ('dead', 'done', 'canceled') AND created < ?
          ORDER BY created`)
@@ -376,6 +395,25 @@ export function pruneNodes(opts) {
         status: r['status'],
         created: r['created'],
     }));
+    // Stale non-terminal sweep (opt-in): active | idle past the TTL whose process
+    // is provably gone (pi_pid NULL or not alive). Never the caller itself.
+    const stale = !includeStale ? [] : db
+        .prepare(`SELECT node_id, status, created, pi_pid FROM nodes
+         WHERE status IN ('active', 'idle') AND created < ?
+         ORDER BY created`)
+        .all(cutoff)
+        .filter((r) => {
+        if (r['node_id'] === selfId)
+            return false;
+        const pid = r['pi_pid'];
+        return pid === null || !pidAlive(pid);
+    })
+        .map((r) => ({
+        node_id: r['node_id'],
+        status: r['status'],
+        created: r['created'],
+    }));
+    const candidates = [...terminal, ...stale];
     if (dryRun || candidates.length === 0)
         return { pruned: candidates, dryRun };
     // One transactioned sweep — delete the rows; the FK cascades their edges.

package/dist/core/canvas/render.d.ts

@@ -23,6 +23,16 @@ export interface DashboardRow {
     mode: string;
     ctx_tokens: number;
     asks: number;
+    /** The dir the node is pinned to (its cwd). Drives the browser's cwd-scope
+     *  filter + the All-dirs basename cue. */
+    cwd: string;
+    /** ISO 8601 birth timestamp — drives the recency sort + the relative-age cue. */
+    created: string;
+    /** The node's spawn prompt (context/initial-prompt.md), trimmed + capped. Only
+     *  populated by dashboardRowsAll (the browser snapshot) — the dashboard leaf
+     *  leaves it undefined to avoid a file read per node. Indexed by super-search
+     *  and shown in the preview panel. */
+    goal?: string;
 }
 /** One row per node visible in the sub-DAG of `rootId` (including root). */
 export declare function dashboardRows(rootId: string): DashboardRow[];

package/dist/core/canvas/render.js

@@ -16,7 +16,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { getNode, listNodes, subscriptionsOf, view } from './canvas.js';
 import { fullName } from './labels.js';
-import { jobDir } from './paths.js';
+import { jobDir, contextDir } from './paths.js';
 import { countAsks } from './attention.js';
 // ---------------------------------------------------------------------------
 // Glyphs
@@ -162,6 +162,25 @@ export function renderForest() {
     }
     return parts.join('\n\n');
 }
+/** The spawn prompt, read straight off disk (canvas-home state) and capped so a
+ *  giant initial-prompt.md can't bloat the snapshot. Mirrors how telemetry is
+ *  read here directly rather than via the runtime layer (which would invert the
+ *  canvas→runtime dependency). Never throws. */
+const GOAL_CAP = 4096;
+function readGoalText(nodeId) {
+    try {
+        const p = join(contextDir(nodeId), 'initial-prompt.md');
+        if (!existsSync(p))
+            return undefined;
+        const body = readFileSync(p, 'utf8').trim();
+        if (body === '')
+            return undefined;
+        return body.length > GOAL_CAP ? body.slice(0, GOAL_CAP) : body;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** One row per node visible in the sub-DAG of `rootId` (including root). */
 export function dashboardRows(rootId) {
     const ids = [rootId, ...view(rootId)];
@@ -178,6 +197,8 @@ export function dashboardRows(rootId) {
                 mode: node.mode,
                 ctx_tokens: tel.tokens_in ?? 0,
                 asks: countAsks(id),
+                cwd: node.cwd,
+                created: node.created,
             }];
     });
 }
@@ -196,6 +217,9 @@ export function dashboardRowsAll() {
                 mode: row.mode,
                 ctx_tokens: tel.tokens_in ?? 0,
                 asks: countAsks(row.node_id),
+                cwd: row.cwd,
+                created: row.created,
+                goal: readGoalText(row.node_id),
             }];
     });
 }

package/dist/core/feed/inbox.d.ts

@@ -45,8 +45,5 @@ export declare function writeCursor(nodeId: string, iso: string): void;
  *     [<kind>]                                ← ref-less msg: full body inlined
  *       <body line>
  *     …
- *
- * A header line announces the total count and instructs the receiver to
- * dereference only what matters.
  */
 export declare function coalesce(entries: InboxEntry[]): string;

package/dist/core/feed/inbox.js

@@ -139,14 +139,10 @@ function renderEntry(e) {
  *     [<kind>]                                ← ref-less msg: full body inlined
  *       <body line>
  *     …
- *
- * A header line announces the total count and instructs the receiver to
- * dereference only what matters.
  */
 export function coalesce(entries) {
     if (entries.length === 0)
         return '(inbox empty)';
-    const header = `${entries.length} update${entries.length === 1 ? '' : 's'} since last read — dereference what matters.\n`;
     // Group by `from` (null → 'system').
     const groups = new Map();
     for (const e of entries) {
@@ -160,5 +156,5 @@ export function coalesce(entries) {
         const lines = items.map(renderEntry);
         sections.push(`From ${sender} — ${items.length} update${items.length === 1 ? '' : 's'}:\n${lines.join('\n')}`);
     }
-    return header + sections.join('\n\n');
+    return sections.join('\n\n');
 }

package/dist/core/runtime/busy.d.ts

@@ -0,0 +1,8 @@
+/** Mark a node mid-turn (pi entered a turn). Best-effort. */
+export declare function markBusy(nodeId: string): void;
+/** Clear the mid-turn marker (the turn ended, however it routed). Best-effort. */
+export declare function clearBusy(nodeId: string): void;
+/** Is the node currently inside a turn? AND this with `pidAlive` at the call
+ *  site — a stale marker from a crashed pi is harmless because the dead pid
+ *  fails the AND. */
+export declare function isBusy(nodeId: string): boolean;

package/dist/core/runtime/busy.js

@@ -0,0 +1,46 @@
+// busy.ts — the "is pi actually mid-turn" signal (a marker file, no db column).
+//
+// The disposition of a focus's OUTGOING node on a hot-swap (placement.ts
+// `outgoingDisposition`) must distinguish a terminal worker that is GENUINELY
+// mid-turn (keep it running off-screen, Invariant F2) from one merely PARKED at
+// its prompt with a live pi (a viewer revived for inspection — despawn it back to
+// dormant on focus-away). A live pid is NOT that signal: a parked node has a live
+// pid too. This marker is.
+//
+// `<jobDir>/busy` exists for exactly the span pi is inside a turn: the stophook
+// touches it on `agent_start` and unlinks it at the top of `agent_end` (and
+// defensively on `session_shutdown`). It is always AND-ed with `pidAlive` at the
+// read site, so a stale marker (process crashed mid-turn without firing
+// agent_end) is harmless — the dead pid fails the AND and the node is reaped.
+// No db migration, atomic touch/unlink, best-effort (never throws).
+import { existsSync, writeFileSync, rmSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { jobDir } from '../canvas/index.js';
+function busyPath(nodeId) {
+    return join(jobDir(nodeId), 'busy');
+}
+/** Mark a node mid-turn (pi entered a turn). Best-effort. */
+export function markBusy(nodeId) {
+    try {
+        mkdirSync(jobDir(nodeId), { recursive: true });
+        writeFileSync(busyPath(nodeId), '');
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Clear the mid-turn marker (the turn ended, however it routed). Best-effort. */
+export function clearBusy(nodeId) {
+    try {
+        rmSync(busyPath(nodeId), { force: true });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Is the node currently inside a turn? AND this with `pidAlive` at the call
+ *  site — a stale marker from a crashed pi is harmless because the dead pid
+ *  fails the AND. */
+export function isBusy(nodeId) {
+    return existsSync(busyPath(nodeId));
+}

package/dist/core/runtime/lifecycle.d.ts

@@ -2,7 +2,7 @@ import type { NodeMeta } from '../canvas/types.js';
 /** The lifecycle events — the only vocabulary for moving a node's status/intent.
  *  Each maps (in the table below) to a target status and/or intent plus the set
  *  of from-statuses it is legal from. */
-export type LifecycleEvent = 'finalize' | 'reap' | 'cancel' | 'crash' | 'yield' | 'release' | 'revive' | 'boot';
+export type LifecycleEvent = 'finalize' | 'cancel' | 'crash' | 'yield' | 'release' | 'revive' | 'boot';
 /** Enact a lifecycle event on a node: validate the from-status against the
  *  table, then write status+intent in ONE atomic statement (so they can never
  *  disagree). Returns the hydrated node view after the write.

package/dist/core/runtime/lifecycle.js

@@ -17,9 +17,17 @@
 // "flip status to a non-supervised value + clear intent BEFORE killing the
 // window" — the daemon only ever revives active|idle nodes, so a teardown must
 // leave the node done/canceled first to close the revive race. That invariant is
-// now the DEFINITION of the `reap`/`cancel` events: callers flip via transition()
+// now the DEFINITION of the `cancel` event: callers flip via transition()
 // and only THEN kill the window.
 //
+// Unification (A5, human-confirmed 2026-06-06): an externally-reaped node — torn
+// down because the user moved on (close cascade) OR because a root reset/relaunch
+// superseded it — ends `canceled`, NOT `done`. `done` is reserved for a node that
+// finished its OWN work (finalize). The old `reap` event (→ done) was identical to
+// `cancel` in every field and side effect once unified on status, so it was
+// COLLAPSED into `cancel`; reset.ts's reapDescendants + relaunchRoot park-old now
+// route through `cancel`.
+//
 // Layering note: lifecycle.ts is runtime, but it is the canvas write surface's
 // `transition` verb (the only writer of status+intent), so it owns its atomic
 // row UPDATE directly via openDb — the one sanctioned exception to "only
@@ -35,9 +43,9 @@ const LIVE = ['active', 'idle'];
 const TRANSITIONS = {
     // feed.push(final) · queue.cancelJob · markCleanExitDone (clean quit).
     finalize: { status: 'done', intent: 'done', from: LIVE },
-    // reapDescendants · relaunchRoot park-old. Forced teardown → done, intent cleared.
-    reap: { status: 'done', intent: null, from: ANY },
-    // closeNode cascade. Forced teardown → canceled, intent cleared.
+    // closeNode cascade · reapDescendants · relaunchRoot park-old. Forced teardown
+    // of a node that did NOT finish its own work → canceled, intent cleared. (A5:
+    // done is reserved for finalize; every external reap unifies on canceled.)
     cancel: { status: 'canceled', intent: null, from: ANY },
     // daemon superviseTick: window gone with no yield/release intent. Intent KEPT
     // (the dead log line still reports it).

package/dist/core/runtime/naming.d.ts

@@ -1,12 +1,12 @@
 import type { NodeMeta } from '../canvas/index.js';
-/** Coerce arbitrary text into a 3-5 word kebab-case name, or '' if nothing
+/** Coerce arbitrary text into a 3-8 word kebab-case name, or '' if nothing
  *  usable survives. Lowercases, keeps [a-z0-9], collapses everything else to a
- *  single hyphen, and clamps to the first 5 words. */
+ *  single hyphen, and clamps to the first 8 words. */
 export declare function sanitizeSessionName(raw: string): string;
 /** Local fallback: derive a name straight from the prompt (no pi call). Drops
  *  stop-words, takes the first few content words. */
 export declare function slugFromPrompt(prompt: string): string;
-/** Synchronously ask pi for a 2-4 word kebab name for `prompt`. Blocks up to
+/** Synchronously ask pi for a 3-8 word kebab name for `prompt`. Blocks up to
  *  NAME_TIMEOUT_MS; on any failure (non-zero exit, timeout, empty/garbled
  *  output) falls back to a local slug. Returns '' only for an empty prompt. */
 export declare function generateSessionName(prompt: string): string;

package/dist/core/runtime/naming.js

@@ -2,7 +2,7 @@
 // handle for the editor label.
 //
 // A node's editor label is `<kind> (<mode>) <name> <cycle>` (see editorLabel in
-// launch.ts). The `<name>` is a 3-5 word kebab-case "description" derived from
+// launch.ts). The `<name>` is a 3-8 word kebab-case "description" derived from
 // the first prompt by asking pi headlessly (`pi -p`), persisted on the node's
 // meta so it survives revives and shows in every cycle.
 //
@@ -26,7 +26,7 @@ const PROMPT_CAP = 2000;
 const NAME_TIMEOUT_MS = 20_000;
 const NAME_SYSTEM_PROMPT = 'You name coding-agent work sessions. This name is a label used to identify the ' +
     'session at a glance among many other concurrent programming sessions, so it must ' +
-    'describe what the task is about. Reply with ONLY a concise 3-5 word name in ' +
+    'describe what the task is about. Reply with ONLY a concise 3-8 word name in ' +
     'kebab-case: lowercase words joined by single hyphens (e.g. `refactor-auth-token-flow`, ' +
     '`add-csv-export-endpoint`). No punctuation, quotes, prose, or trailing text. ' +
     'Output JUST the name, nothing else.';
@@ -43,9 +43,9 @@ const STOPWORDS = new Set([
     'is', 'are', 'be', 'this', 'that', 'it', 'as', 'at', 'by', 'from', 'into',
     'please', 'can', 'you', 'i', 'we', 'my', 'our', 'me', 'so', 'then',
 ]);
-/** Coerce arbitrary text into a 3-5 word kebab-case name, or '' if nothing
+/** Coerce arbitrary text into a 3-8 word kebab-case name, or '' if nothing
  *  usable survives. Lowercases, keeps [a-z0-9], collapses everything else to a
- *  single hyphen, and clamps to the first 5 words. */
+ *  single hyphen, and clamps to the first 8 words. */
 export function sanitizeSessionName(raw) {
     const firstLine = (raw ?? '').split('\n').map((l) => l.trim()).find((l) => l !== '') ?? '';
     const words = firstLine
@@ -53,7 +53,7 @@ export function sanitizeSessionName(raw) {
         .replace(/[^a-z0-9]+/g, '-')
         .split('-')
         .filter((w) => w !== '');
-    return words.slice(0, 5).join('-');
+    return words.slice(0, 8).join('-');
 }
 /** Local fallback: derive a name straight from the prompt (no pi call). Drops
  *  stop-words, takes the first few content words. */
@@ -97,7 +97,7 @@ function nameArgs(prompt) {
     argv.push(nameUserPrompt(prompt));
     return argv;
 }
-/** Synchronously ask pi for a 2-4 word kebab name for `prompt`. Blocks up to
+/** Synchronously ask pi for a 3-8 word kebab name for `prompt`. Blocks up to
  *  NAME_TIMEOUT_MS; on any failure (non-zero exit, timeout, empty/garbled
  *  output) falls back to a local slug. Returns '' only for an empty prompt. */
 export function generateSessionName(prompt) {

package/dist/core/runtime/placement.d.ts

@@ -171,16 +171,32 @@ export interface FocusResult {
     revived: boolean;
 }
 /** PURE disposition of a focus's outgoing occupant after a retarget swap (§2.5/
- *  §1.3): a still-generating node moves to backstage (F2); a holder pane or a
- *  done/dormant node has its (now-backstage) pane reaped (Invariant P: a
- *  not-focused + not-generating node has NO pane). Unit-testable in isolation. */
+ *  §1.3). Four signals decide one of three fates; unit-testable in isolation:
+ *    - `kill`     — a holder pane (no row) or a done/dead/canceled node: reap the
+ *                   (now-backstage) pane (Invariant P: not-focused + not-live ⇒
+ *                   no pane).
+ *    - `backstage`— a human-driven RESIDENT node (editor/root/orchestrator — NEVER
+ *                   despawned on focus-away), or a terminal worker that is
+ *                   genuinely MID-TURN (Invariant F2 — keeps running off-screen).
+ *    - `release`  — a PARKED terminal viewer (live but not mid-turn): a node
+ *                   revived only for inspection. Despawn it back to dormant
+ *                   (transition `release` → idle/idle-release) and reap its pane;
+ *                   the daemon revives it on its inbox, or the user re-focuses.
+ *                   This is the bug fix: such a node was misclassified as
+ *                   generating and left stuck active forever.
+ *  Order matters: `resident` is checked BEFORE `generating` so a resident node is
+ *  always kept warm regardless of whether it happens to be mid-turn. */
 export type OutgoingAction = {
     kind: 'backstage';
 } | {
     kind: 'kill';
+} | {
+    kind: 'release';
 };
 export declare function outgoingDisposition(o: {
     exists: boolean;
+    live: boolean;
+    resident: boolean;
     generating: boolean;
 }): OutgoingAction;
 /** Open a NEW viewport (§2.3, F4) — the ONLY path a new pane appears in a user
@@ -210,8 +226,9 @@ export declare function registerRootFocus(nodeId: string, pane: string, session:
  *    - `swapPaneInPlace(pin, focusPane)`: incoming → the viewport slot; the
  *      outgoing occupant → incoming's old (backstage) slot, %ids preserved
  *      (cross-session swap confirmed by the spike).
- *    - outgoing still generating → backstage (F2); else reap its now-backstage
- *      pane (Invariant P). A holder occupant (no node row) is always reaped.
+ *    - outgoing resident OR still mid-turn → backstage (kept warm / F2); a parked
+ *      terminal viewer → RELEASE (status → idle, pane reaped); a holder or
+ *      done/dormant occupant → reap its now-backstage pane (Invariant P).
  *  Arms remain-on-exit on the viewport (F3); the focus row is the record. */
 export declare function retargetFocus(focusId: string, incoming: string, revive: Reviver): FocusResult;
 /** The front door for `node focus` / `node cycle` (§2.3): resolve which focus the

package/dist/core/runtime/placement.js

@@ -28,6 +28,8 @@
 import { getRow, getRowByPane, getNode, setPresence, openDb, openFocusRow, setFocusOccupant, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, setFocusPane, listFocuses as listFocusRows, } from '../canvas/index.js';
 import { paneExists, paneLocation, paneOfWindow, windowAlive, windowOfPane, ensureSession, openNodeWindow, respawnPaneSync, respawnPaneDetached, breakPaneToSession, splitWindow, swapPaneInPlace, setRemainOnExit, closePane, currentTmux, joinPane, selectLayout, setWindowOption, switchClient, selectWindow, } from './tmux.js';
 import { homeSessionOf, nodeSession, newNodeId } from './nodes.js';
+import { isBusy } from './busy.js';
+import { transition } from './lifecycle.js';
 // Re-export the durable REVIVE-HOME read so placement is the one front door for
 // "where does this node live."
 export { homeSessionOf };
@@ -314,22 +316,37 @@ function pidAlive(pid) {
         return e.code === 'EPERM';
     }
 }
-/** Is a focus's OUTGOING occupant still GENERATING (a live pi doing work)? A
- *  still-generating node is moved to backstage by a retarget (F2 — it keeps
- *  running off-screen); a holder / done / dormant node has its pane reaped
- *  (Invariant P). A holder or vanished node (row null) is never generating. */
+/** Is a focus's OUTGOING occupant still GENERATING (a live pi actually MID-TURN)?
+ *  A still-generating node is moved to backstage by a retarget (F2 — it keeps
+ *  running off-screen); a holder / done / dormant / merely-parked node has its
+ *  pane reaped or released (Invariant P). A holder or vanished node (row null) is
+ *  never generating.
+ *
+ *  The signal is the mid-turn `busy` marker AND a live pid — NOT pid-alive
+ *  alone. A node revived only for VIEWING is parked at its prompt with a live
+ *  pid between turns; pid-alive would misclassify it as "doing work" and leave
+ *  it stuck backstaged-active forever. `isBusy` is true only inside a turn, so a
+ *  parked viewer reads as not-generating and is released to dormant on
+ *  focus-away. The AND with `pidAlive` makes a stale marker (a pi that crashed
+ *  mid-turn) harmless. */
 function isGenerating(nodeId) {
     const row = getRow(nodeId);
     if (row === null)
         return false;
     if (row.status !== 'active' && row.status !== 'idle')
         return false;
-    return pidAlive(row.pi_pid);
+    return isBusy(nodeId) && pidAlive(row.pi_pid);
 }
 export function outgoingDisposition(o) {
     if (!o.exists)
-        return { kind: 'kill' };
-    return o.generating ? { kind: 'backstage' } : { kind: 'kill' };
+        return { kind: 'kill' }; // holder pane
+    if (!o.live)
+        return { kind: 'kill' }; // done/dead/canceled — reap the pane
+    if (o.resident)
+        return { kind: 'backstage' }; // human-driven node: keep warm
+    if (o.generating)
+        return { kind: 'backstage' }; // mid-turn terminal worker (F2)
+    return { kind: 'release' }; // parked terminal viewer → dormant
 }
 /** The node's pane iff it is a LIVE pane (a generating-unfocused backstage pane,
  *  or a still-live focus pane), else null. The retarget swaps THIS pane into the
@@ -403,8 +420,9 @@ export function registerRootFocus(nodeId, pane, session, window) {
  *    - `swapPaneInPlace(pin, focusPane)`: incoming → the viewport slot; the
  *      outgoing occupant → incoming's old (backstage) slot, %ids preserved
  *      (cross-session swap confirmed by the spike).
- *    - outgoing still generating → backstage (F2); else reap its now-backstage
- *      pane (Invariant P). A holder occupant (no node row) is always reaped.
+ *    - outgoing resident OR still mid-turn → backstage (kept warm / F2); a parked
+ *      terminal viewer → RELEASE (status → idle, pane reaped); a holder or
+ *      done/dormant occupant → reap its now-backstage pane (Invariant P).
  *  Arms remain-on-exit on the viewport (F3); the focus row is the record. */
 export function retargetFocus(focusId, incoming, revive) {
     let f = getFocusById(focusId);
@@ -455,11 +473,23 @@ export function retargetFocus(focusId, incoming, revive) {
     }
     const pinLoc = paneLocation(pin); // now the viewport
     const outLoc = paneLocation(focusPane); // now backstage (outgoing's new home)
-    const action = outgoingDisposition({ exists: getRow(outgoing) !== null, generating: isGenerating(outgoing) });
+    const oRow = getRow(outgoing);
+    const action = outgoingDisposition({
+        exists: oRow !== null,
+        live: oRow?.status === 'active' || oRow?.status === 'idle',
+        resident: oRow?.lifecycle === 'resident',
+        generating: isGenerating(outgoing),
+    });
     commitFocusTxn(f.focus_id, incoming, pin, pinLoc, outgoing, action, outLoc, focusPane);
-    // Reap the outgoing/holder pane (now backstage) when not generating — AFTER
-    // commit (a tmux side effect, outside the txn).
-    if (action.kind === 'kill')
+    // Crash-safety: flip a released (parked terminal viewer) node to dormant
+    // (idle + intent='idle-release') BEFORE reaping its pane, so the daemon never
+    // sees a window-gone live node and races to revive it. Then reap the
+    // outgoing/holder pane (now backstage) for both kill (done/dormant/holder) and
+    // release (parked viewer) — AFTER commit (a tmux side effect, outside the txn).
+    // A still-generating worker or a resident node is backstaged, untouched here.
+    if (action.kind === 'release')
+        transition(outgoing, 'release');
+    if (action.kind === 'kill' || action.kind === 'release')
         closePane(focusPane);
     armRemainOnExit(pinLoc?.window);
     return { focused: true, session: pinLoc?.session ?? f.session, inPlace: true, revived };
@@ -481,6 +511,7 @@ function commitFocusTxn(focusId, incoming, pin, pinLoc, outgoing, action, outLoc
                 setPresence(outgoing, { pane: outgoingPane, tmux_session: outLoc?.session ?? null, window: outLoc?.window ?? null });
             }
             else {
+                // kill | release — the pane is reaped by the caller; null the LOCATION.
                 setPresence(outgoing, { pane: null, tmux_session: null, window: null });
             }
         }