@crouton-kit/crouter 0.3.16 → 0.3.18

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

@@ -18,9 +18,15 @@
 // alt+c is a tmux display-menu (not a pi key), so prefix chords (m/e/1-9/custom)
 // are tmux menu items that route through `crtr canvas chord`.
 //
-// Two selection signals, both NO_COLOR-safe:
-//   SELF row = reverse video (ESC[7m), full width — an attribute, not a color.
-//   CURSOR   = ▸ + bold on the row. Status stays on the colored dot.
+// Selection / liveness signals:
+//   CURSOR (selected) = reverse-video bar (ESC[7m), full width — an attribute,
+//                       not a colour, so it reads under NO_COLOR. Plus a ▸ caret.
+//   ACTIVE (running)  = a coloured background bar (status 'active'); the dot
+//                       glyph still carries the signal where colour is stripped.
+//   SELF              = bold name — a quiet "you are here" marker.
+//
+// Folding is auto by default: a branch stays COLLAPSED unless its subtree holds
+// a running ('active') agent or self. h/l override that per-node and persist.
 //
 // ⚑K pending-asks is PER-NODE, inline on each waiting node's own row (manager,
 // reports, tree rows; self shows a trailing ⚑ line in BASE). ⤳M direct-children
@@ -45,10 +51,13 @@ let liveTimer;
  *  exactly one key tap exists (mirrors the liveTimer double-guard). */
 let liveUnsub;
 let view = 'base';
-/** Fold state — node ids whose children are hidden in GRAPH. Survives renders
- *  AND BASE↔GRAPH toggles. Keyed by id so a topology change never corrupts it;
- *  stale ids are harmless (ignored when absent). */
-const collapsed = new Set();
+/** Manual fold OVERRIDES in GRAPH, keyed by id (so a topology change can't
+ *  corrupt them; stale ids are ignored). They override the default policy —
+ *  collapsed UNLESS the subtree holds a running ('active') agent or self (see
+ *  computeDefaultExpanded). `h` collapses → userCollapsed; `l` expands →
+ *  userExpanded. Both survive renders AND BASE↔GRAPH toggles. */
+const userCollapsed = new Set();
+const userExpanded = new Set();
 /** GRAPH cursor (a node id, not an index — indices shift as topology changes). */
 let cursorId;
 /** GRAPH viewport scroll offset (row index of the top visible row). */
@@ -69,16 +78,19 @@ const PI_MAX_WIDGET_LINES = 10;
 const VIEWPORT_FALLBACK_ROWS = 30;
 // ---------------------------------------------------------------------------
 // ANSI styling. pi renders embedded escapes in widget lines and measures width
-// ANSI-aware, so raw escapes are safe and need no pi-tui dependency. Selection
-// uses theme-agnostic ATTRIBUTES (reverse / bold), never colour alone, so it
-// reads under NO_COLOR and on any background; status uses the standard 8 colors
-// on the dot only.
+// ANSI-aware, so raw escapes are safe and need no pi-tui dependency. The cursor
+// (selected row) uses a theme-agnostic ATTRIBUTE (reverse), so it reads under
+// NO_COLOR; the active-row tint is a background COLOUR, but the differing dot
+// glyph (●/○/✓/✗) keeps the running signal even where colour is stripped.
 // ---------------------------------------------------------------------------
 const ESC = '\x1b[';
 const RESET = `${ESC}0m`;
 const BOLD = `${ESC}1m`;
 const DIM = `${ESC}2m`;
 const REVERSE = `${ESC}7m`;
+/** Dark-green background bar marking a running ('active') node — distinct from
+ *  the cursor's reverse-video bar; chosen so default-fg text stays readable. */
+const BG_ACTIVE = `${ESC}48;5;22m`;
 const GREEN = `${ESC}32m`;
 const RED = `${ESC}31m`;
 const YELLOW = `${ESC}33m`;
@@ -137,15 +149,16 @@ function truncate(s, max = fillWidth()) {
 function fillWidth() {
     return Math.max(20, Math.min((process.stdout.columns ?? 80) - 2, 180));
 }
-/** Wrap `content` in a full-width reverse-video bar. REVERSE is re-asserted
- *  after every embedded RESET so a colored cell (the status dot) doesn't punch
- *  a hole in the bar; the visible width is padded out to `width`; the line
- *  closes with a real RESET. */
-function reverseFill(content, width) {
+/** Wrap `content` in a full-width background bar opened by `open` (REVERSE for
+ *  the cursor, BG_ACTIVE for a running node). `open` is re-asserted after every
+ *  embedded RESET so a coloured cell (the status dot) can't punch a hole in the
+ *  bar; the visible width is padded out to `width`; the line closes with a real
+ *  RESET so the style never bleeds into the editor below. */
+function fillBar(content, width, open) {
     const clipped = truncate(content, width);
-    const reasserted = clipped.replace(/\x1b\[0m/g, `${RESET}${REVERSE}`);
+    const reasserted = clipped.replace(/\x1b\[0m/g, `${RESET}${open}`);
     const pad = Math.max(0, width - visibleWidth(clipped));
-    return `${REVERSE}${reasserted}${' '.repeat(pad)}${RESET}`;
+    return `${open}${reasserted}${' '.repeat(pad)}${RESET}`;
 }
 function readTelemetry(nodeId) {
     try {
@@ -198,28 +211,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 +260,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,28 +305,50 @@ 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));
+}
+/** Default fold policy: which nodes auto-EXPAND. A node expands only when one
+ *  of its child subtrees holds a running ('active') agent or self — so the path
+ *  to any live agent (and to you) is revealed while quiescent branches stay
+ *  folded. One bottom-up O(N) pass from the ancestry root; cycle-guarded. */
+function computeDefaultExpanded(root, self) {
+    const expand = new Set();
+    const seen = new Set();
+    // Returns whether subtree(id), INCLUDING id, holds an active node or self.
+    const visit = (id) => {
+        if (seen.has(id))
+            return id === self || getNode(id)?.status === 'active';
+        seen.add(id);
+        let childRevealing = false;
+        for (const c of convoChildIds(id))
+            if (visit(c))
+                childRevealing = true;
+        if (childRevealing)
+            expand.add(id); // a descendant is worth revealing → unfold id
+        return childRevealing || id === self || getNode(id)?.status === 'active';
+    };
+    visit(root);
+    return expand;
 }
 function buildGraphModel(self) {
     const rootId = climbRoot(self);
+    const defaultExpanded = computeDefaultExpanded(rootId, self);
+    // userExpanded / userCollapsed override the auto policy; absent → policy decides.
+    const isFolded = (id) => userExpanded.has(id) ? false : userCollapsed.has(id) ? true : !defaultExpanded.has(id);
     const rows = [];
     const visited = new Set();
     const walk = (id, prefix, isRoot, isLast) => {
         if (visited.has(id)) {
             const connector = isRoot ? '' : isLast ? '└─ ' : '├─ ';
-            rows.push({ id, hasKids: false, isSelf: id === self, branch: prefix + connector, cycle: true });
+            rows.push({ id, hasKids: false, isSelf: id === self, branch: prefix + connector, cycle: true, collapsed: false });
             return;
         }
         visited.add(id);
         const kids = sortedChildIds(id);
+        const folded = isFolded(id);
         const connector = isRoot ? '' : isLast ? '└─ ' : '├─ ';
-        rows.push({ id, hasKids: kids.length > 0, isSelf: id === self, branch: prefix + connector, cycle: false });
-        if (collapsed.has(id))
+        rows.push({ id, hasKids: kids.length > 0, isSelf: id === self, branch: prefix + connector, cycle: false, collapsed: folded });
+        if (folded)
             return; // folded — don't descend
         const childPrefix = isRoot ? '' : prefix + (isLast ? '   ' : '│  ');
         for (let i = 0; i < kids.length; i++)
@@ -313,22 +357,27 @@ function buildGraphModel(self) {
     walk(rootId, '', true, true);
     return rows;
 }
-/** Render one GRAPH row. SELF → reverse fill; CURSOR → ▸ + bold caret/name. */
+/** Render one GRAPH row. CURSOR (selected) → reverse-video bar; an ACTIVE
+ *  (running) node → a coloured background bar; SELF → bold name. The cursor
+ *  outranks the active tint when both land on the same row. */
 function renderGraphRow(r, isCursor) {
+    const wrap = (line, active) => isCursor ? fillBar(line, fillWidth(), REVERSE)
+        : active ? fillBar(line, fillWidth(), BG_ACTIVE)
+            : truncate(line);
     if (r.cycle) {
         const line = `${r.branch}  ${DIM}↺ ${shortId(r.id)}${RESET}`;
-        return r.isSelf ? reverseFill(line, fillWidth()) : truncate(line);
+        return wrap(line, false);
     }
     const node = getNode(r.id);
     const dot = coloredGlyph(node);
     const rawName = node !== null ? fullName(node) : shortId(r.id);
-    const name = isCursor ? `${BOLD}${rawName}${RESET}` : rawName;
+    const name = r.isSelf ? `${BOLD}${rawName}${RESET}` : rawName;
     const kind = `${DIM}${node?.kind ?? ''}${RESET}`;
     const tokens = `${DIM}${tokensCell(r.id)}${RESET}`;
     const caret = isCursor ? `${BOLD}▸${RESET} ` : '  ';
-    const fold = r.hasKids && collapsed.has(r.id) ? ` ${DIM}[+${childCount(r.id)}]${RESET}` : '';
+    const fold = r.hasKids && r.collapsed ? ` ${DIM}[+${childCount(r.id)}]${RESET}` : '';
     const line = `${r.branch}${caret}${dot} ${name} ${kind} ${tokens}${childBadge(node)}${fold}${askBadge(r.id)}`;
-    return r.isSelf ? reverseFill(line, fillWidth()) : truncate(line);
+    return wrap(line, node?.status === 'active');
 }
 /** Total lines the GRAPH widget may emit. pi hard-caps extension widgets at
  *  MAX_WIDGET_LINES — anything past that pi truncates itself, eating our own
@@ -673,8 +722,9 @@ export function registerCanvasNav(pi) {
             return { consume: true };
         }
         if (isPlain(data, 'h')) {
-            if (cur !== undefined && cur.hasKids && !collapsed.has(cur.id)) {
-                collapsed.add(cur.id);
+            if (cur !== undefined && cur.hasKids && !cur.collapsed) {
+                userCollapsed.add(cur.id);
+                userExpanded.delete(cur.id);
             }
             else {
                 const p = managerOf(cursorId ?? nodeId);
@@ -685,8 +735,9 @@ export function registerCanvasNav(pi) {
             return { consume: true };
         }
         if (isPlain(data, 'l')) {
-            if (cur !== undefined && collapsed.has(cur.id)) {
-                collapsed.delete(cur.id);
+            if (cur !== undefined && cur.collapsed && cur.hasKids) {
+                userExpanded.add(cur.id);
+                userCollapsed.delete(cur.id);
             }
             else if (cur !== undefined && cur.hasKids) {
                 const c = sortedChildIds(cur.id)[0];

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

@@ -1,5 +1,4 @@
 interface CommandUI {
-    select(title: string, options: string[]): Promise<string | undefined>;
     notify(message: string, type?: 'info' | 'warning' | 'error'): void;
 }
 interface CommandCtx {

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

@@ -1,27 +1,25 @@
 // canvas-resume.ts — pi extension registering the /resume-node canvas command.
 //
-//   /resume-node  — open a TREE-SHAPED picker over the WHOLE canvas (every root,
-//     INCLUDING DORMANT nodes: done / idle / dead / canceled) rendered with tree
-//     glyphs (├─ / └─) + a status tag + name + short id, then revive the chosen
-//     node by shelling `crtr node focus <id>` (fire-and-forget). Reviving dormant
-//     nodes is the entire point, so — unlike the BASE/GRAPH chrome and
-//     renderForest()'s live-only (active|idle) filter — this walks ALL roots
-//     and ALL statuses.
+//   /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>` 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: the
-//   stophook never records pi_pid / clears intent / marks done, no inbox-watcher
-//   wakes it, and transition('revive') never runs so the row stays dormant.
-//   Worst case (idle + intent=idle-release) the daemon can't see the raw pi (no
-//   pi_pid) and DOUBLE-SPAWNS a second pi on the same .jsonl, corrupting the
-//   conversation. A UI must therefore NEVER spawn `pi --session` directly — it
-//   opens nodes via `crtr node focus` / `crtr canvas revive`.
+//   `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).
 //
@@ -29,80 +27,12 @@
 // 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';
-import { getNode, listNodes, subscriptionsOf, fullName } from '../core/canvas/index.js';
-// ---------------------------------------------------------------------------
-// Forest rendering — one line per node across the WHOLE canvas, with a parallel
-// ids[] array so the chosen line maps back to its node_id. Plain unicode glyphs
-// (no ANSI) so the line renders cleanly inside pi's select dialog.
-// ---------------------------------------------------------------------------
-const STATUS_GLYPH = {
-    active: '●',
-    idle: '○',
-    done: '✓',
-    dead: '✗',
-    canceled: '⊘',
-};
-function shortId(id) {
-    return id.slice(0, 8);
-}
-/** `<glyph> <status> <name> [<kind>/<mode>] (<shortid>)` — a status TAG + name
- *  + short id, prefixed with the tree branch. Best-effort on a missing meta. */
-function nodeLabel(nodeId, branch) {
-    const node = getNode(nodeId);
-    if (node === null)
-        return `${branch}? <missing ${shortId(nodeId)}>`;
-    const glyph = STATUS_GLYPH[node.status] ?? '?';
-    return `${branch}${glyph} ${node.status} ${fullName(node)} [${node.kind}/${node.mode}] (${shortId(nodeId)})`;
-}
-/** Sort rank for roots — live first (active, then idle), dormant after. Keeps
- *  the picker oriented while still listing every dormant root. */
-function statusRank(status) {
-    switch (status) {
-        case 'active': return 0;
-        case 'idle': return 1;
-        case 'done': return 2;
-        case 'canceled': return 3;
-        case 'dead': return 4;
-        default: return 5;
-    }
-}
-/** Recursively render the subscription subtree rooted at `nodeId` into the
- *  parallel lines/ids arrays. Mirrors render.ts walkTree but keeps lines and
- *  ids strictly 1:1 (a cycle back-ref still maps to its real node, so selecting
- *  it just focuses that node — harmless). Cycle-safe via `visited`. */
-function walkSubtree(nodeId, indent, connector, visited, out) {
-    if (visited.has(nodeId)) {
-        out.lines.push(`${indent}${connector}↺ ${shortId(nodeId)} (cycle)`);
-        out.ids.push(nodeId);
-        return;
-    }
-    visited.add(nodeId);
-    out.lines.push(nodeLabel(nodeId, `${indent}${connector}`));
-    out.ids.push(nodeId);
-    const children = subscriptionsOf(nodeId);
-    // Root rows carry no connector; children of a last-child get clear space, of a
-    // mid-child a continued spine — exactly render.ts walkTree's prefix math.
-    const childIndent = indent + (connector === '' ? '' : connector === '└─ ' ? '   ' : '│  ');
-    for (let i = 0; i < children.length; i++) {
-        const isLast = i === children.length - 1;
-        walkSubtree(children[i].node_id, childIndent, isLast ? '└─ ' : '├─ ', visited, out);
-    }
-}
-/** The whole-canvas forest: EVERY root (parent === null, ANY status) and its
- *  subtree, flattened to parallel label/id arrays. */
-function buildForest() {
-    const out = { lines: [], ids: [] };
-    const visited = new Set();
-    const roots = listNodes()
-        .filter((n) => n.parent === null)
-        .sort((a, b) => statusRank(a.status) - statusRank(b.status));
-    for (const r of roots)
-        walkSubtree(r.node_id, '', '', visited, out);
-    return out;
+/** 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, `'\\''`)}'`;
 }
-// ---------------------------------------------------------------------------
-// Extension
-// ---------------------------------------------------------------------------
 /**
  * Register the /resume-node command on `pi`.
  *
@@ -116,9 +46,9 @@ export function registerCanvasResume(pi) {
     if (typeof pi.registerCommand !== 'function')
         return;
     pi.registerCommand('resume-node', {
-        description: 'Resume a node — pick from the whole canvas (incl. dormant) and revive it',
+        description: 'Open the canvas navigator (search/scope/sort/tree) and resume the chosen node',
         handler: async (_args, ctx) => {
-            // select() is a terminal-only dialog — guard the run mode before it.
+            // 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');
@@ -126,47 +56,26 @@ export function registerCanvasResume(pi) {
                 catch { /* best-effort */ }
                 return;
             }
-            let forest;
-            try {
-                forest = buildForest();
-            }
-            catch {
+            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 {
-                    ctx.ui.notify('resume: could not read the canvas', 'error');
+                    execFile('tmux', ['display-popup', '-E', '-w', '90%', '-h', '85%', cmd], () => { });
                 }
                 catch { /* best-effort */ }
                 return;
             }
-            if (forest.lines.length === 0) {
-                try {
-                    ctx.ui.notify('No nodes on the canvas to resume.', 'info');
-                }
-                catch { /* best-effort */ }
-                return;
-            }
-            const choice = await ctx.ui.select('Resume which node?', forest.lines);
-            if (choice === undefined)
-                return; // cancelled / timed out
-            const idx = forest.lines.indexOf(choice);
-            const targetId = idx >= 0 ? forest.ids[idx] : undefined;
-            if (targetId === undefined)
-                return;
-            // The ONLY sync-safe open: route through reviveNode via `crtr node focus`.
-            // Fire-and-forget — `node focus` swaps the target into THIS pane, replacing
-            // the current pi, so the callback may never run (best-effort notify only).
+            // Not in tmux → crtr is tmux-only, so there is nothing to fall back to.
             try {
-                execFile('crtr', ['node', 'focus', targetId], (err) => {
-                    if (err != null) {
-                        try {
-                            ctx.ui.notify(`resume failed: focus ${shortId(targetId)}`, 'error');
-                        }
-                        catch { /* best-effort */ }
-                    }
-                });
-            }
-            catch {
-                /* best-effort */
+                ctx.ui.notify('/resume-node needs tmux', 'warning');
             }
+            catch { /* best-effort */ }
         },
     });
 }

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

@@ -30,6 +30,7 @@ import { writeFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 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';
@@ -282,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
@@ -296,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
@@ -386,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

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.16",
+  "version": "0.3.18",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",