@crouton-kit/crouter 0.3.15 → 0.3.17

package/dist/core/runtime/spawn.js

@@ -10,15 +10,15 @@
 //                provenance via spawned_by) brought forefront for direct driving.
 import { spawnSync } from 'node:child_process';
 import { FRONT_DOOR_ENV } from './front-door.js';
-import { spawnNode, currentNodeContext, resolveBirthSession } from './nodes.js';
+import { spawnNode, currentNodeContext, resolveBirthSession, nodeSession } from './nodes.js';
 import { buildLaunchSpec, buildPiArgv } from './launch.js';
 import { writeGoal } from './kickoff.js';
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
 import { seedMemory, seedUserMemory, seedProjectMemory } from './memory.js';
 import { generateSessionName } from './naming.js';
-import { ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, nodeSession, focusWindow, installMenuBinding, installNavBindings, } from './tmux.js';
+import { installMenuBinding, installNavBindings } from './tmux-chrome.js';
 import { setPresence, updateNode, getNode, fullName } from '../canvas/index.js';
-import { registerRootFocus } from './placement.js';
+import { registerRootFocus, ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, focusWindow, } from './placement.js';
 import { transition } from './lifecycle.js';
 import { ensureDaemon } from '../../daemon/manage.js';
 /** Create a root node and bring up its pi. Returns the node; for 'inline' this

package/dist/core/runtime/tmux-chrome.d.ts

@@ -0,0 +1 @@
+export { installMenuBinding, installNavBindings, sendKeysEnter } from './tmux.js';

package/dist/core/runtime/tmux-chrome.js

@@ -0,0 +1,4 @@
+// tmux-chrome.ts — chrome seam (§2.1): stateless keybind/input verbs.
+// The ONLY non-placement module allowed to import the tmux driver, per the
+// §5.1 lint. Re-exports the menu/nav/send-keys verbs callers (spawn, chord) need.
+export { installMenuBinding, installNavBindings, sendKeysEnter } from './tmux.js';

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

@@ -1,11 +1,6 @@
 /** POSIX single-quote escaping for one shell word. */
 export declare function shellQuote(s: string): string;
 export declare function inTmux(): boolean;
-/** The single, shared tmux session that ALL canvas node windows live in.
- *  Overridable with CRTR_NODE_SESSION (default `crtr`). Every root and every
- *  child opens a window here rather than cluttering the user's own working
- *  session — switch to it to browse the whole live graph, ignore it otherwise. */
-export declare function nodeSession(): string;
 export interface TmuxLocation {
     session: string;
     window: string;
@@ -139,7 +134,19 @@ export declare function respawnPaneSync(opts: RespawnPaneOpts): boolean;
  *  callers stay green while the placement layer migrates onto the explicit
  *  sync/detached split. */
 export declare function respawnPane(opts: RespawnPaneOpts): boolean;
-/** Turn a pi argv array into a single shell command string. */
+/** Turn a pi argv array into a single shell command string.
+ *
+ *  The binary defaults to `CRTR_PI_BINARY` when that env var is set, else the
+ *  literal `pi`. This is a TEST-ONLY substitution seam: when CRTR_PI_BINARY is
+ *  unset (every production path) the behavior is byte-identical to exec'ing
+ *  `pi`. The integration-test harness points it at a deterministic fake-pi
+ *  vehicle so a real `crtr node new` reaches the fake instead of the LLM `pi`,
+ *  without any dependence on tmux/shell PATH inheritance — the substitution is
+ *  baked into the command string at build time, in the process that calls
+ *  piCommand. An explicit `binary` arg still overrides the env (no caller passes
+ *  one today). The value may be a multi-word launcher (e.g. `node --import
+ *  tsx/esm host.ts`); only the argv entries are shell-quoted, so a multi-word
+ *  binary is spliced verbatim ahead of them. */
 export declare function piCommand(argv: string[], binary?: string): string;
 /** List all window ids present in `session`. Returns [] if the session does
  *  not exist or tmux fails for any reason. Each entry is the raw window id

package/dist/core/runtime/tmux.js

@@ -9,6 +9,7 @@
 // their window; reviving opens a fresh one.
 import { spawn, spawnSync } from 'node:child_process';
 import { readConfig } from '../config.js';
+import { nodeSession } from './nodes.js';
 // ---------------------------------------------------------------------------
 // Shell quoting + tmux invocation
 // ---------------------------------------------------------------------------
@@ -27,14 +28,6 @@ function tmux(args) {
 export function inTmux() {
     return process.env['TMUX'] !== undefined && process.env['TMUX'] !== '';
 }
-/** The single, shared tmux session that ALL canvas node windows live in.
- *  Overridable with CRTR_NODE_SESSION (default `crtr`). Every root and every
- *  child opens a window here rather than cluttering the user's own working
- *  session — switch to it to browse the whole live graph, ignore it otherwise. */
-export function nodeSession() {
-    const v = process.env['CRTR_NODE_SESSION'];
-    return v !== undefined && v !== '' ? v : 'crtr';
-}
 /** Where the caller currently is, or null if not inside tmux. */
 export function currentTmux() {
     if (!inTmux())
@@ -270,8 +263,20 @@ export function respawnPane(opts) {
 // ---------------------------------------------------------------------------
 // pi command assembly
 // ---------------------------------------------------------------------------
-/** Turn a pi argv array into a single shell command string. */
-export function piCommand(argv, binary = 'pi') {
+/** Turn a pi argv array into a single shell command string.
+ *
+ *  The binary defaults to `CRTR_PI_BINARY` when that env var is set, else the
+ *  literal `pi`. This is a TEST-ONLY substitution seam: when CRTR_PI_BINARY is
+ *  unset (every production path) the behavior is byte-identical to exec'ing
+ *  `pi`. The integration-test harness points it at a deterministic fake-pi
+ *  vehicle so a real `crtr node new` reaches the fake instead of the LLM `pi`,
+ *  without any dependence on tmux/shell PATH inheritance — the substitution is
+ *  baked into the command string at build time, in the process that calls
+ *  piCommand. An explicit `binary` arg still overrides the env (no caller passes
+ *  one today). The value may be a multi-word launcher (e.g. `node --import
+ *  tsx/esm host.ts`); only the argv entries are shell-quoted, so a multi-word
+ *  binary is spliced verbatim ahead of them. */
+export function piCommand(argv, binary = process.env['CRTR_PI_BINARY'] ?? 'pi') {
     return [binary, ...argv.map(shellQuote)].join(' ');
 }
 // ---------------------------------------------------------------------------
@@ -295,7 +300,7 @@ export function windowAlive(session, window) {
     return listWindowIds(session).includes(window);
 }
 // ---------------------------------------------------------------------------
-// Focus helpers (used by the presence layer)
+// Focus helpers (used by the placement layer)
 // ---------------------------------------------------------------------------
 /** Activate a window within its session (same-session navigation). Equivalent
  *  to `tmux select-window -t <session>:<window>`. Best-effort; never throws. */
@@ -351,7 +356,7 @@ export function sendKeysEnter(pane, text) {
 // ---------------------------------------------------------------------------
 /** Reserved mnemonic keys owned by the built-in menu items below — a custom
  *  `prefixBind` may not claim these (the built-in item wins). */
-const RESERVED_MENU_KEYS = new Set(['o', 'd', 'D', 'x', 'b']);
+const RESERVED_MENU_KEYS = new Set(['o', 'r', 'd', 'D', 'x', 'b']);
 /** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails.
  *  The built-in items (promote/demote/detach/close/browse) are static; the canvas-nav
  *  chords (graph/manager/expand/report-N + any custom prefixBind) are appended
@@ -366,6 +371,10 @@ export function installMenuBinding() {
         // the slash command delivers the orchestration guidance into the node's
         // context, which a bare `run-shell` (output discarded) could not.
         { name: 'promote to orchestrator', key: 'o', cmd: `send-keys -t '#{pane_id}' '/promote' Enter` },
+        // Resume types `/resume-node` into the agent's pane: the slash command opens
+        // a whole-canvas picker (incl. dormant nodes) and revives the choice via
+        // `crtr node focus` — the only sync-safe open (routes through reviveNode).
+        { name: 'resume node', key: 'r', cmd: `send-keys -t '#{pane_id}' '/resume-node' Enter` },
         // `d` demotes the agent to TERMINAL in place: no finalize, no kill — it keeps
         // running where it is, and because it is now terminal it is forced to push a
         // final up the spine when it finishes. `D` ALSO detaches it to the background

package/dist/daemon/crtrd.js

@@ -14,7 +14,11 @@
 //   • Pane gone + intent==='idle-release' → node freed its own pane while
 //     dormant; clear the stale window ref and revive (resume) when its inbox
 //     gains an unseen entry.
-//   • Pane gone + any other intent → crash: mark 'dead'.
+//   • Pane gone + any other intent → route on what the node was doing:
+//       - never-booted (pi_session_id null) → crash ('dead') + surface boot fail
+//       - mid-generation (busy marker present) → crash ('dead')
+//       - finished its turn, still awaiting a live child → crash ('dead'), for now
+//       - finished its turn, awaiting nothing live → finalize ('done')
 //   • Nodes with no tmux placement (inline roots) are skipped.
 //
 // Single-instance guarantee
@@ -24,8 +28,9 @@
 import { writeFileSync, readFileSync, rmSync, existsSync, mkdirSync, } from 'node:fs';
 import { join } from 'node:path';
 import { crtrHome } from '../core/canvas/paths.js';
-import { listNodes, getRow, setPresence, getNode, } from '../core/canvas/index.js';
+import { listNodes, getRow, setPresence, getNode, hasActiveLiveSubscription, } from '../core/canvas/index.js';
 import { transition } from '../core/runtime/lifecycle.js';
+import { isBusy } from '../core/runtime/busy.js';
 import { isNodePaneAlive, reconcile } from '../core/runtime/placement.js';
 import { reviveNode } from '../core/runtime/revive.js';
 import { pushUrgent } from '../core/feed/feed.js';
@@ -201,28 +206,45 @@ export async function superviseTick(now = Date.now()) {
                 setPresence(row.node_id, { tmux_session: row.tmux_session, window: null });
             }
             else {
-                // The pane vanished without the node completing or refreshing. Split the
-                // two ways that happens: a vehicle that NEVER BOOTED (pi exited before
-                // its first session_start, so pi_session_id is still null) versus a
-                // genuine mid-run CRASH (it had booted, so pi_session_id is set). Both
-                // are dead, but a never-booted node is a spawn failure the parent was
-                // never told about — surface it up the spine instead of dying quietly.
-                transition(row.node_id, 'crash');
-                // Boot-failed vs crashed turns on pi_session_id, an IDENTITY field — the
-                // one place this pass still reads meta. surfaceBootFailure also wants the
-                // full meta (name/kind) for its message.
+                // The pane vanished without the node yielding or releasing. Route on what
+                // the node was DOING at pane-kill time — not every gone pane is a death:
+                //   • never-booted (pi_session_id null) → crash + surface boot failure.
+                //     A spawn failure the parent was never told about — it had no turn to
+                //     finish, so it can never be a finalize. (Boot-failed vs crashed turns
+                //     on pi_session_id, an IDENTITY field — the one place this pass still
+                //     reads meta; surfaceBootFailure also wants name/kind for its message.)
+                //   • MID-GENERATION (busy marker present) → crash (→dead). agent_start
+                //     touched the marker and agent_end never cleared it ⇒ the pane was
+                //     killed inside a turn: a genuine mid-run death. (The pane is gone, so
+                //     pi is dead; we read isBusy WITHOUT the usual AND-pidAlive guard on
+                //     purpose — here a stale marker IS the proof it died mid-turn.)
+                //   • finished its turn (busy ABSENT) but still awaiting a LIVE child →
+                //     crash (→dead) for now. (This waiting-on-a-live-child case may later
+                //     route to a revivable-idle instead of a hard death.)
+                //   • finished its turn AND awaiting nothing live → finalize (→done): it
+                //     did its own work and the pane was closed to dismiss it.
                 const meta = getNode(row.node_id);
-                if (meta !== null && meta.pi_session_id == null) {
-                    process.stderr.write(`[crtrd] boot-failed ${row.node_id} (pane gone before pi ever started)\n`);
-                    try {
-                        await surfaceBootFailure(meta);
-                    }
-                    catch (err) {
-                        process.stderr.write(`[crtrd] surfaceBootFailure ${row.node_id} error: ${err.message}\n`);
-                    }
+                const neverBooted = meta !== null && meta.pi_session_id == null;
+                if (!neverBooted &&
+                    !isBusy(row.node_id) &&
+                    !hasActiveLiveSubscription(row.node_id)) {
+                    transition(row.node_id, 'finalize');
+                    process.stderr.write(`[crtrd] done ${row.node_id} (pane gone after turn end, no live child)\n`);
                 }
                 else {
-                    process.stderr.write(`[crtrd] dead ${row.node_id} (pane gone, intent=${String(row.intent)})\n`);
+                    transition(row.node_id, 'crash');
+                    if (neverBooted) {
+                        process.stderr.write(`[crtrd] boot-failed ${row.node_id} (pane gone before pi ever started)\n`);
+                        try {
+                            await surfaceBootFailure(meta);
+                        }
+                        catch (err) {
+                            process.stderr.write(`[crtrd] surfaceBootFailure ${row.node_id} error: ${err.message}\n`);
+                        }
+                    }
+                    else {
+                        process.stderr.write(`[crtrd] dead ${row.node_id} (pane gone, intent=${String(row.intent)})\n`);
+                    }
                 }
             }
         }

package/dist/pi-extensions/canvas-nav.js

@@ -198,28 +198,37 @@ function managerOf(id) {
         return undefined;
     }
 }
-/** Live reports (active|idle) of a node — the DOWN set in BASE. */
-function liveReports(id) {
+/** A kind:'human' node is a control-plane ASK (a humanloop deck on the human's
+ *  screen), NOT a pi conversation — it has no session, so focusing/reviving it
+ *  boots a confused blank "you have been revived" pi. Its pending-ask signal
+ *  already rides the ⚑ badge on the ASKING node (attention.ts attributes asks by
+ *  source.nodeId, never to the human node), so the row carries no signal of its
+ *  own. Drop it from every navigable list (the tree, BASE reports, child counts,
+ *  subtree expansion) so it can never be selected. */
+function isHumanAsk(id) {
+    return getNode(id)?.kind === 'human';
+}
+/** A node's direct children that are navigable conversations — human-ask nodes
+ *  dropped. The one place the nav chrome enumerates children. */
+function convoChildIds(id) {
     try {
-        return subscriptionsOf(id)
-            .map((s) => s.node_id)
-            .filter((cid) => {
-            const st = getNode(cid)?.status;
-            return st === 'active' || st === 'idle';
-        });
+        return subscriptionsOf(id).map((s) => s.node_id).filter((cid) => !isHumanAsk(cid));
     }
     catch {
         return [];
     }
 }
-/** All direct children (edges) — used for the ⤳ badge and fold counts. */
+/** Live reports (active|idle) of a node — the DOWN set in BASE. */
+function liveReports(id) {
+    return convoChildIds(id).filter((cid) => {
+        const st = getNode(cid)?.status;
+        return st === 'active' || st === 'idle';
+    });
+}
+/** Direct navigable children — used for the ⤳ badge and fold counts (human-ask
+ *  nodes excluded, so the count matches what the tree actually shows). */
 function childCount(id) {
-    try {
-        return subscriptionsOf(id).length;
-    }
-    catch {
-        return 0;
-    }
+    return convoChildIds(id).length;
 }
 /** Climb first-manager edges from `self` to the ancestry root (cycle-guarded). */
 function climbRoot(self) {
@@ -238,16 +247,16 @@ function climbRoot(self) {
 function subtreeIds(root) {
     const out = [];
     const seen = new Set([root]);
-    const q = subscriptionsOf(root).map((s) => s.node_id);
+    const q = convoChildIds(root);
     while (q.length > 0) {
         const id = q.shift();
         if (seen.has(id))
             continue;
         seen.add(id);
         out.push(id);
-        for (const s of subscriptionsOf(id))
-            if (!seen.has(s.node_id))
-                q.push(s.node_id);
+        for (const cid of convoChildIds(id))
+            if (!seen.has(cid))
+                q.push(cid);
     }
     return out;
 }
@@ -283,12 +292,7 @@ function statusRank(id) {
  *  the tree and when stepping into a subtree (`l`). Array.sort is stable, so
  *  equal-status siblings keep their creation order. */
 function sortedChildIds(id) {
-    try {
-        return subscriptionsOf(id).map((s) => s.node_id).sort((a, b) => statusRank(a) - statusRank(b));
-    }
-    catch {
-        return [];
-    }
+    return convoChildIds(id).sort((a, b) => statusRank(a) - statusRank(b));
 }
 function buildGraphModel(self) {
     const rootId = climbRoot(self);
@@ -502,11 +506,19 @@ export function registerCanvasNav(pi) {
         // Budget WITHIN pi's widget cap (see graphWidgetBudget): reserve 1 line for
         // the footer hint, up to 2 for the ↑/↓ "more" indicators, the rest for tree
         // rows. The window then tracks the cursor, so j/k scrolls through the WHOLE
-        // list rather than hitting pi's hard truncation. Two passes settle the
-        // mutual dependency between "how many rows fit" and "are indicators shown".
+        // list rather than hitting pi's hard truncation. The passes settle the
+        // mutual dependency between "how many rows fit" and "are indicators shown":
+        // each ↑/↓ indicator steals a tree row, which can push the cursor out of
+        // view, which moves the window, which changes whether an indicator shows.
+        // This needs up to 3 passes to converge (an indicator appearing shrinks the
+        // window, the smaller window re-homes scrollTop, that re-home can toggle the
+        // *other* indicator). Bailing early (the old 2-pass cap) left the cursor one
+        // row off-screen for a single keypress near the bottom — the arrow vanished
+        // and only the NEXT press scrolled. 4 passes always settles to a stable,
+        // cursor-visible window.
         const treeArea = Math.max(2, graphWidgetBudget() - 1);
         let viewportH = treeArea;
-        for (let pass = 0; pass < 2; pass++) {
+        for (let pass = 0; pass < 4; pass++) {
             if (cursorIdx < scrollTop)
                 scrollTop = cursorIdx;
             if (cursorIdx >= scrollTop + viewportH)

package/dist/pi-extensions/canvas-resume.d.ts

@@ -0,0 +1,21 @@
+interface CommandUI {
+    notify(message: string, type?: 'info' | 'warning' | 'error'): void;
+}
+interface CommandCtx {
+    mode: string;
+    ui: CommandUI;
+}
+interface PiLike {
+    registerCommand?(name: string, options: {
+        description?: string;
+        handler: (args: string, ctx: CommandCtx) => void | Promise<void>;
+    }): void;
+}
+/**
+ * Register the /resume-node command on `pi`.
+ *
+ * Returns immediately when CRTR_NODE_ID is absent — the extension is fully
+ * inert in a non-canvas pi session.
+ */
+export declare function registerCanvasResume(pi: PiLike): void;
+export default registerCanvasResume;

package/dist/pi-extensions/canvas-resume.js

@@ -0,0 +1,82 @@
+// canvas-resume.ts — pi extension registering the /resume-node canvas command.
+//
+//   /resume-node  — open the full-screen canvas navigator (`crtr canvas browse`)
+//     as a tmux popup. The navigator owns the screen (tabs / auto-collapsed tree
+//     / `/` super-search / cwd scope / sort / preview) and, on Enter, focuses the
+//     chosen node back INTO this pane via `crtr node focus --pane`. The popup is
+//     scoped to THIS node's cwd by default (pass --cwd) so you see the nodes from
+//     the dir you're working in first; toggle to All dirs inside with `c`.
+//
+//   The name is literally `resume-node`, NOT `resume`, to avoid clashing with
+//   pi's built-in /resume.
+//
+// crtr ONLY runs inside tmux (see crouter/CLAUDE.md) — there is no non-tmux
+// fallback picker. Outside tmux the command notifies and no-ops.
+//
+// ⚠ DESYNC — why `crtr node focus` is the ONLY sanctioned open
+//   `crtr node focus <id>` (which `canvas browse` shells on Enter) routes through
+//   reviveNode() (src/core/runtime/revive.ts), the ONLY sanctioned launcher of
+//   `pi --session <file>`: it sets CRTR_NODE_ID + the `-e` canvas extensions and
+//   runs transition('revive'). A RAW `pi --session <file>` has NEITHER → every
+//   canvas hook is inert and the daemon can DOUBLE-SPAWN onto the same .jsonl.
+//   A UI must therefore NEVER spawn `pi --session` directly.
+//
+// INERT when CRTR_NODE_ID is absent (a plain pi session, not a canvas node).
+//
+// Plain TS-with-types — no imports from @earendil-works/* so this compiles
+// inside crouter's own tsc build without a dep on the pi packages (mirrors
+// canvas-nav.ts / canvas-commands.ts).
+import { execFile } from 'node:child_process';
+/** Single-quote a string for safe interpolation into a `sh -c` command line —
+ *  tmux runs the display-popup trailing string through the shell, so a cwd with
+ *  spaces or quotes must be escaped. */
+function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Register the /resume-node command on `pi`.
+ *
+ * Returns immediately when CRTR_NODE_ID is absent — the extension is fully
+ * inert in a non-canvas pi session.
+ */
+export function registerCanvasResume(pi) {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId.trim() === '')
+        return; // not a canvas node
+    if (typeof pi.registerCommand !== 'function')
+        return;
+    pi.registerCommand('resume-node', {
+        description: 'Open the canvas navigator (search/scope/sort/tree) and resume the chosen node',
+        handler: async (_args, ctx) => {
+            // The popup is terminal-only — guard the run mode before opening it.
+            if (ctx.mode !== 'tui') {
+                try {
+                    ctx.ui.notify('/resume-node needs the interactive TUI', 'warning');
+                }
+                catch { /* best-effort */ }
+                return;
+            }
+            const origPane = process.env['TMUX_PANE'];
+            // crtr only runs in tmux: open the full-screen canvas navigator as a popup.
+            // It owns the screen and, on Enter, focuses the chosen node back INTO this
+            // pane via `crtr node focus --pane`. Fire-and-forget: tmux runs the trailing
+            // string through sh -c, and the popup closes itself when browse exits.
+            if (process.env['TMUX'] !== undefined && origPane !== undefined && origPane !== '') {
+                // Scope the navigator to this node's cwd by default (the dir pi runs in).
+                const cwd = shellQuote(process.cwd());
+                const cmd = `crtr canvas browse --return-pane ${origPane} --cwd ${cwd}`;
+                try {
+                    execFile('tmux', ['display-popup', '-E', '-w', '90%', '-h', '85%', cmd], () => { });
+                }
+                catch { /* best-effort */ }
+                return;
+            }
+            // Not in tmux → crtr is tmux-only, so there is nothing to fall back to.
+            try {
+                ctx.ui.notify('/resume-node needs tmux', 'warning');
+            }
+            catch { /* best-effort */ }
+        },
+    });
+}
+export default registerCanvasResume;

package/dist/pi-extensions/canvas-stophook.d.ts

@@ -1,4 +1,4 @@
-type PiEvents = 'turn_end' | 'agent_end' | 'session_shutdown' | 'session_start';
+type PiEvents = 'agent_start' | 'turn_end' | 'agent_end' | 'session_shutdown' | 'session_start';
 interface PiLike {
     on: (event: PiEvents, handler: (event: any, ctx: any) => void | Promise<void>) => void;
     sendUserMessage: (content: string, options?: {

package/dist/pi-extensions/canvas-stophook.js

@@ -28,15 +28,14 @@
 // crouter's own tsc build without a dep on the pi packages.
 import { writeFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { getNode, jobDir, updateNode, recordPid, subscribersOf, closeFocusRow, setPresence } from '../core/canvas/index.js';
+import { getNode, jobDir, updateNode, recordPid, subscribersOf, setPresence } from '../core/canvas/index.js';
 import { transition } from '../core/runtime/lifecycle.js';
+import { markBusy, clearBusy } from '../core/runtime/busy.js';
 import { evaluateStop } from '../core/runtime/stop-guard.js';
 import { personaDrift, commitPersonaAck } from '../core/runtime/persona.js';
 import { reviveInPlace } from '../core/runtime/revive.js';
 import { handleNewSession, markCleanExitDone } from '../core/runtime/reset.js';
-import { setFocus } from '../core/runtime/presence.js';
-import { focusOf, handFocusToManager, tearDownNode } from '../core/runtime/placement.js';
-import { setRemainOnExit } from '../core/runtime/tmux.js';
+import { focusOf, handFocusToManager, tearDownNode, closeFocusToShell } from '../core/runtime/placement.js';
 /**
  * Merge accumulated token counts into nodes/<nodeId>/job/telemetry.json.
  * Creates the directory when it doesn't yet exist. Best-effort; never throws.
@@ -284,6 +283,17 @@ export function registerCanvasStophook(pi) {
         }
     });
     // ---------------------------------------------------------------------------
+    // agent_start — pi entered a turn. Mark the node mid-turn (busy) so a
+    // focus-away while it is genuinely working backstages it (Invariant F2)
+    // rather than reaping it. Cleared at the top of agent_end (turn over).
+    // ---------------------------------------------------------------------------
+    pi.on('agent_start', () => {
+        try {
+            markBusy(nodeId);
+        }
+        catch { /* best-effort */ }
+    });
+    // ---------------------------------------------------------------------------
     // session_shutdown — clean exit → done.
     //
     // pi hands us a reason as a session tears down. Only 'quit' is a node-ending
@@ -298,6 +308,7 @@ export function registerCanvasStophook(pi) {
     // ---------------------------------------------------------------------------
     pi.on('session_shutdown', (event, _ctx) => {
         try {
+            clearBusy(nodeId); // turn marker is meaningless once pi is exiting
             // Clean /quit (reason='quit') resolves the node to done; if it held the
             // user's viewport, Q1-close it (tearDownNode kills the frozen focus pane +
             // closes the focus row → returns the user to a shell, §1.5/flow (e)). pi is
@@ -388,6 +399,9 @@ export function registerCanvasStophook(pi) {
         // steering). The stop/yield auto-pushes that needed `await push(...)` were
         // removed, so the handler no longer needs to be async — the node reaches its
         // subscribers ONLY through its own explicit `crtr push` calls.
+        // The turn has ended regardless of how it routes below — clear the mid-turn
+        // marker FIRST so a focus-away from this now-parked node despawns it.
+        clearBusy(nodeId);
         try {
             const messages = Array.isArray(event?.messages) ? event.messages : [];
             // Accumulate tokens from the final batch (edge case: a turn that fired
@@ -423,11 +437,9 @@ export function registerCanvasStophook(pi) {
                 if (f !== null) {
                     const managerId = node.parent ?? subscribersOf(nodeId)[0]?.node_id ?? null;
                     if (!handFocusToManager(f.focus_id, managerId)) {
-                        closeFocusRow(f.focus_id);
-                        setFocus('');
-                        const win = getNode(nodeId)?.window; // %m's window
-                        if (win)
-                            setRemainOnExit(win, false); // Q1 return-to-shell
+                        // Q1 return-to-shell, self-saw-safe: close the focus row + disarm the
+                        // pane's freeze so it reaps on exit (we can't closePane our own pane).
+                        closeFocusToShell(f.focus_id, nodeId);
                     }
                 }
                 setPresence(nodeId, { pane: null, tmux_session: null, window: null }); // M done → owns no pane

package/dist/prompts/skill.js

@@ -38,7 +38,12 @@ is still chosen by what the agent does after reading, not by the script.
   assets; nested dirs are their own skills.
 - Required frontmatter: \`name\`, \`type\`, \`description\`. \`name\` must equal the
   dir path under \`skills/\` — slashes nest (\`web/frontend/design\`).
-- \`description\`: one sentence, front-load "Use when…" — it drives discovery.
+- \`description\`: one sentence, front-load "Use when…" — it is the **only**
+  text an agent reads before choosing the skill, so every "when to reach for
+  this" / selection cue lives *here*, never in the body. By the time anyone
+  reads the body they have already picked the skill; a body line about
+  when-to-use is wasted. The body is purely the workflow or knowledge they
+  came for.
 - Budget ~150 lines per \`SKILL.md\`; spill deeper material into sibling files.
 - \`crtr skill author scaffold <n> --type <t> --scope <s> --description "<d>"\` writes correct frontmatter for you; \`crtr sys doctor\` validates.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -36,7 +36,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@crouton-kit/humanloop": "^0.3.14",
+    "@crouton-kit/humanloop": "^0.3.15",
     "commander": "^13.0.0"
   },
   "devDependencies": {