@crouton-kit/crouter 0.3.16 → 0.3.18

package/dist/core/personas/loader.js

@@ -5,9 +5,10 @@
  * Resolution order (highest → lowest precedence): project > user > builtin.
  *
  * Layout on disk:
- *   <root>/personas/<kind>/base.md
+ *   <root>/personas/<kind>/PERSONA.md
  *   <root>/personas/<kind>/orchestrator.md
  *   <root>/personas/orchestration-kernel.md
+ *   <root>/personas/<kind>/<...>/PERSONA.md   (nested sub-personas)
  *
  * The builtin root is src/builtin-personas (or dist/builtin-personas in the
  * compiled build), resolved relative to this module — mirrors the pattern used
@@ -59,7 +60,7 @@ function personaSearchRoots() {
 // ---------------------------------------------------------------------------
 /**
  * Find the first existing file across the scope roots.
- * `relativePath` is relative to each root (e.g. 'general/base.md').
+ * `relativePath` is relative to each root (e.g. 'general/PERSONA.md').
  */
 function resolveFile(relativePath) {
     for (const root of personaSearchRoots()) {
@@ -92,6 +93,11 @@ function inlineIncludes(body) {
         return kernelBody.trim();
     });
 }
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** The role-body filename for every kind/sub-persona (replaces legacy base.md). */
+const PERSONA_FILE = 'PERSONA.md';
 /**
  * Load and parse a persona file for the given `kind` and `mode`.
  *
@@ -99,7 +105,8 @@ function inlineIncludes(body) {
  * On success, `@include` directives in the body are resolved and inlined.
  */
 export function loadPersona(kind, mode) {
-    const relativePath = `${kind}/${mode}.md`;
+    // base → PERSONA.md (the role body); orchestrator → its sibling orchestrator.md.
+    const relativePath = mode === 'orchestrator' ? `${kind}/orchestrator.md` : `${kind}/PERSONA.md`;
     const filePath = resolveFile(relativePath);
     if (!filePath)
         return null;
@@ -165,9 +172,11 @@ export function loadSpineFragment(hasManager) {
     return body.trim();
 }
 /**
- * Enumerate the kinds with at least one persona file (base.md or
+ * Enumerate the kinds with at least one persona file (PERSONA.md or
  * orchestrator.md) across all scope roots (project/user/builtin). Used to
- * validate a requested `--kind` and to list the valid choices.
+ * validate a requested `--kind` and to list the valid choices. Only the
+ * IMMEDIATE children of each root count — nested sub-personas never pollute
+ * the global kind list (see subPersonasFor).
  */
 export function availableKinds() {
     const kinds = new Set();
@@ -178,42 +187,106 @@ export function availableKinds() {
             if (!entry.isDirectory())
                 continue;
             const dir = join(root, entry.name);
-            if (existsSync(join(dir, 'base.md')) || existsSync(join(dir, 'orchestrator.md'))) {
+            if (existsSync(join(dir, PERSONA_FILE)) || existsSync(join(dir, 'orchestrator.md'))) {
                 kinds.add(entry.name);
             }
         }
     }
     return [...kinds].sort();
 }
-const REVIEWERS_SUBDIR = 'reviewers';
 /**
- * Enumerate the reviewer sub-kinds owned by `parentKind` — the specialist
- * personas at `<root>/<parentKind>/reviewers/<name>/base.md`, scanned across all
- * scope roots (project > user > builtin; highest precedence wins per name).
+ * The one-line "when to use this node type" gloss for `kind`, read from its
+ * `<kind>/PERSONA.md` `whenToUse` frontmatter (resolved project > user >
+ * builtin). Returns '' when the kind has no PERSONA.md or no `whenToUse`.
+ * Drives the dynamic kind list in `node new -h` / `node promote -h`.
+ */
+export function kindWhenToUse(kind) {
+    const filePath = resolveFile(`${kind}/${PERSONA_FILE}`);
+    if (!filePath)
+        return '';
+    const { data } = parseFrontmatterGeneric(readFileSync(filePath, 'utf8'));
+    return data && typeof data['whenToUse'] === 'string' ? data['whenToUse'] : '';
+}
+/** Recursively yield every dir under `dir` (inclusive) that holds a PERSONA.md,
+ *  with `relKind` = the dir's path relative to the scope root (slash-joined).
+ *  Dirs WITHOUT a PERSONA.md (e.g. a `reviewers/` grouping namespace) are
+ *  transparent — they yield nothing themselves but are still descended into,
+ *  so `plan/reviewers/security` keeps that exact kind string. */
+function* walkPersonaDirs(dir, relParts) {
+    const file = join(dir, PERSONA_FILE);
+    if (existsSync(file))
+        yield { relKind: relParts.join('/'), file };
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory())
+            yield* walkPersonaDirs(join(dir, entry.name), [...relParts, entry.name]);
+    }
+}
+/** Parse a sub-persona's `availableTo` frontmatter into its availability set.
+ *  Returns the wildcard sentinel `'*'` for `"*"`/`"all"` (scalar or in an
+ *  array), an explicit list of kind strings when present, else the default
+ *  `[topKind]` (the top-level ancestor kind). */
+function parseAvailableTo(data, topKind) {
+    const isWild = (s) => {
+        const t = s.trim().toLowerCase();
+        return t === '*' || t === 'all';
+    };
+    const v = data ? data['availableTo'] : undefined;
+    if (v === undefined)
+        return [topKind];
+    if (typeof v === 'string')
+        return isWild(v) ? '*' : [v];
+    if (Array.isArray(v)) {
+        const arr = v.filter((x) => typeof x === 'string');
+        if (arr.some(isWild))
+            return '*';
+        return arr.length > 0 ? arr : [topKind];
+    }
+    return [topKind];
+}
+/**
+ * Enumerate the sub-personas AVAILABLE TO `kind` — the nested specialist
+ * personas (e.g. `plan/reviewers/security`) a `kind` node may spawn, surfaced
+ * in its composed prompt (resolve.ts) and nowhere else.
  *
- * Sub-kinds are intentionally NOT global kinds: `availableKinds()` scans only the
- * immediate children of each persona root, so `<parentKind>/reviewers/*` never
- * leaks into the global list. A sub-kind is reachable only by its full kind
- * string and is surfaced only in its parent kind's composed prompt (resolve.ts).
- * Kind-parametric: any kind owns a roster simply by adding
- * `<kind>/reviewers/<name>/base.md` — no code change.
+ * A sub-persona is any descendant dir (ANY depth) under a top-level kind dir
+ * that holds a PERSONA.md, EXCLUDING the top-level PERSONA.md itself. Its
+ * availability is its `availableTo` frontmatter: an explicit list of kind
+ * strings, or the wildcard `"*"`/`"all"` (visible to every kind); absent, it
+ * defaults to its own top-level ancestor kind. So the five `plan/reviewers/*`
+ * (no `availableTo`) are visible only to `plan`, while a sub-persona under
+ * `developer/` can declare `availableTo: [plan]` to surface in plan's menu —
+ * which is why ALL top-level kinds' descendants are scanned, not just `<kind>/`.
+ *
+ * Sub-personas are intentionally NOT global kinds: `availableKinds()` scans only
+ * the immediate children of each root, so a nested sub-persona never leaks into
+ * the global list; it is reachable only by its full kind string. Precedence is
+ * project > user > builtin keyed on the FULL kind string — the highest root that
+ * defines a given kind string wins (and owns its `availableTo`).
  */
-export function subKindsFor(parentKind) {
-    const byName = new Map();
+export function subPersonasFor(kind) {
+    const seen = new Set(); // full kind strings already resolved (higher root won)
+    const out = [];
     for (const root of personaSearchRoots()) {
-        const dir = join(root, parentKind, REVIEWERS_SUBDIR);
-        if (!existsSync(dir))
+        if (!existsSync(root))
             continue;
-        for (const entry of readdirSync(dir, { withFileTypes: true })) {
-            if (!entry.isDirectory() || byName.has(entry.name))
-                continue; // higher root already won
-            const baseFile = join(dir, entry.name, 'base.md');
-            if (!existsSync(baseFile))
+        for (const top of readdirSync(root, { withFileTypes: true })) {
+            if (!top.isDirectory())
                 continue;
-            const { data } = parseFrontmatterGeneric(readFileSync(baseFile, 'utf8'));
-            const summary = data && typeof data['summary'] === 'string' ? data['summary'] : '';
-            byName.set(entry.name, { kind: `${parentKind}/${REVIEWERS_SUBDIR}/${entry.name}`, name: entry.name, summary });
+            const topKind = top.name;
+            for (const { relKind, file } of walkPersonaDirs(join(root, topKind), [topKind])) {
+                if (relKind === topKind)
+                    continue; // the top-level PERSONA.md is the kind itself, not a sub-persona
+                if (seen.has(relKind))
+                    continue; // a higher root already resolved this kind string
+                seen.add(relKind);
+                const { data } = parseFrontmatterGeneric(readFileSync(file, 'utf8'));
+                const availableTo = parseAvailableTo(data, topKind);
+                if (availableTo !== '*' && !availableTo.includes(kind))
+                    continue;
+                const whenToUse = data && typeof data['whenToUse'] === 'string' ? data['whenToUse'] : '';
+                out.push({ kind: relKind, name: relKind.split('/').pop(), whenToUse });
+            }
         }
     }
-    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+    return out.sort((a, b) => a.kind.localeCompare(b.kind));
 }

package/dist/core/personas/resolve.d.ts

@@ -4,17 +4,17 @@
  *
  * Composition rules:
  *   mode==='base'
- *     → load <kind>/base.md; if missing fall back to general defaults.
+ *     → load <kind>/PERSONA.md; if missing fall back to general defaults.
  *
  *   mode==='orchestrator'
  *     → prefer <kind>/orchestrator.md (which must embed the kernel via
  *       @include orchestration-kernel.md — inlined by the loader).
  *       If no orchestrator.md exists for this kind, compose:
- *         <kind>/base.md body  +  '\n\n'  +  kernel body
- *       If even the base is missing, fall back to general defaults + kernel.
+ *         <kind>/PERSONA.md body  +  '\n\n'  +  kernel body
+ *       If even the PERSONA.md is missing, fall back to general defaults + kernel.
  *
  * Frontmatter from whichever file is the primary source (orchestrator.md >
- * base.md) supplies model/skills/extensions/tools. Lifecycle and spine position
+ * PERSONA.md) supplies model/skills/extensions/tools. Lifecycle and spine position
  * are INPUTS (the caller decides them — root/child, terminal/resident), not
  * derived here; they select the lifecycle/spine protocol fragments spliced
  * ahead of the persona body.

package/dist/core/personas/resolve.js

@@ -4,22 +4,22 @@
  *
  * Composition rules:
  *   mode==='base'
- *     → load <kind>/base.md; if missing fall back to general defaults.
+ *     → load <kind>/PERSONA.md; if missing fall back to general defaults.
  *
  *   mode==='orchestrator'
  *     → prefer <kind>/orchestrator.md (which must embed the kernel via
  *       @include orchestration-kernel.md — inlined by the loader).
  *       If no orchestrator.md exists for this kind, compose:
- *         <kind>/base.md body  +  '\n\n'  +  kernel body
- *       If even the base is missing, fall back to general defaults + kernel.
+ *         <kind>/PERSONA.md body  +  '\n\n'  +  kernel body
+ *       If even the PERSONA.md is missing, fall back to general defaults + kernel.
  *
  * Frontmatter from whichever file is the primary source (orchestrator.md >
- * base.md) supplies model/skills/extensions/tools. Lifecycle and spine position
+ * PERSONA.md) supplies model/skills/extensions/tools. Lifecycle and spine position
  * are INPUTS (the caller decides them — root/child, terminal/resident), not
  * derived here; they select the lifecycle/spine protocol fragments spliced
  * ahead of the persona body.
  */
-import { loadPersona, loadKernel, loadRuntimeBase, loadSpineFragment, loadLifecycleFragment, subKindsFor } from './loader.js';
+import { loadPersona, loadKernel, loadRuntimeBase, loadSpineFragment, loadLifecycleFragment, subPersonasFor } from './loader.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -40,24 +40,26 @@ function fallbackBasePrompt(kind) {
  *  fragment (report-up vs. silent, keyed on whether the node has a manager),
  *  then the lifecycle fragment (finish-with-`push final` vs. dormant/wake). The
  *  kind×mode persona body follows after a rule. Empty fragments drop out. */
-/** Render the "sub-kinds you may spawn" menu for a kind that owns a roster.
- *  Returns '' when the kind owns none. Data-driven: one line per sub-kind, its
- *  spawn string + its `summary`. Adding a roster file makes it appear here. */
-function renderSubKindMenu(kind) {
-    const subs = subKindsFor(kind);
+/** Render the "sub-personas you may spawn" menu for a kind that has any
+ *  available to it. Returns '' when none are. Data-driven: one line per
+ *  sub-persona, its spawn string + its `whenToUse`. A sub-persona surfaces here
+ *  for a kind when its `availableTo` includes that kind (default: its own
+ *  top-level ancestor) or is the wildcard. */
+function renderSubPersonaMenu(kind) {
+    const subs = subPersonasFor(kind);
     if (subs.length === 0)
         return '';
-    const lines = subs.map((s) => `- \`${s.kind}\` — ${s.summary}`);
+    const lines = subs.map((s) => `- \`${s.kind}\` — ${s.whenToUse}`);
     return [
-        '## Reviewer sub-kinds you may spawn',
+        '## Sub-personas you may spawn',
         '',
-        `These specialist reviewers exist only in the ${kind} kind's world — no other kind sees them. Spawn one with \`crtr node new --kind <sub-kind> "<scope>"\`, giving it only its scope, never your suspicions: a reviewer handed a hint anchors on it instead of finding problems independently.`,
+        `These specialist sub-personas are available to the ${kind} kind. Spawn one with \`crtr node new --kind <sub> "<scope>"\`, giving it only its scope, never your suspicions: a reviewer handed a hint anchors on it instead of finding problems independently.`,
         '',
         ...lines,
     ].join('\n');
 }
 function composeProtocol(personaPrompt, kind, lifecycle, hasManager) {
-    const menu = renderSubKindMenu(kind);
+    const menu = renderSubPersonaMenu(kind);
     const body = menu ? `${personaPrompt}\n\n${menu}` : personaPrompt;
     const protocol = [
         loadRuntimeBase(),

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

@@ -15,6 +15,16 @@ export declare function focusByPane(pane: string): FocusRow | null;
 export declare function focusedNodes(): Set<string>;
 /** Every focus row (every live viewport). */
 export declare function listFocuses(): FocusRow[];
+/** The on-screen viewport a human-in-the-loop prompt raised by `nodeId` should
+ *  surface into: the HIGHEST FOCUSED node of nodeId's graph — the focused node
+ *  closest to the graph root, i.e. the session/window the user is actually
+ *  watching this work in. Walks nodeId's spine to its root, enumerates the whole
+ *  tree root-first (`view` is BFS ⇒ shallowest first), and returns the focus row
+ *  of the first node that occupies a viewport. null when nothing in the graph is
+ *  on screen — the caller then surfaces in the user's attached pane rather than
+ *  the backstage node session. PURE (db reads only): no tmux probe, so the pane
+ *  may be stale; the caller liveness-checks before targeting it. */
+export declare function graphSurfaceTarget(nodeId: string): FocusRow | null;
 /** The cached LOCATION as stored on a node row: the authoritative `pane` handle
  *  plus its derived window/session cache. */
 export interface CachedLocation {
@@ -171,16 +181,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 +236,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