@crouton-kit/crouter 0.3.16 → 0.3.17

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

@@ -1,16 +1,19 @@
-/** Reap the descendant sub-DAG of `rootId`: mark each **done** (the user moved
- *  on — a clean teardown, NOT a fault) + clear intent FIRST, then kill its
+/** Reap the descendant sub-DAG of `rootId`: mark each **canceled** (the user
+ *  moved on — a clean teardown, NOT a fault) + clear intent FIRST, then kill its
  *  window (closes the daemon revive race). Edges are LEFT INTACT — descendants
  *  keep parent=rootId. No wipe. Returns the reaped ids.
  *
- *  Why `done`, and why marking is STILL explicit: a `closeWindow`/`respawn-pane
- *  -k` kill is abrupt and fires NO clean `session_shutdown`, so the general
- *  quit→done rule does NOT auto-resolve a force-killed descendant — we mark it
- *  `done` here. Shared by relaunchRoot (option C) and resetRoot's in-place
- *  fallback, so both leave their descendants `done`. */
+ *  Why `canceled` (A5, human-confirmed 2026-06-06): an externally-reaped node —
+ *  whether via `node close` OR a root reset/relaunch — did not finish its OWN
+ *  work, so it unifies on `canceled`; `done` is reserved for finalize. Why
+ *  marking is STILL explicit: a `closeWindow`/`respawn-pane -k` kill is abrupt
+ *  and fires NO clean `session_shutdown`, so the general quit→done rule does NOT
+ *  auto-resolve a force-killed descendant — we mark it `canceled` here via the
+ *  same `cancel` event the close cascade uses. Shared by relaunchRoot (option C)
+ *  and resetRoot's in-place fallback, so both leave their descendants `canceled`. */
 export declare function reapDescendants(rootId: string): string[];
 export interface ResetRootResult {
-    /** Descendant node ids torn down (window killed + marked done). */
+    /** Descendant node ids torn down (window killed + marked canceled). */
     reaped: string[];
     /** Direct subscriptions dropped off the root. */
     detached: string[];

package/dist/core/runtime/reset.js

@@ -6,7 +6,7 @@
 // behave like re-running `crtr` we have two strategies:
 //
 //   • relaunchRoot (option C) — for a ROOT in a tmux pane: PARK the old root
-//     (mark done, keep its id/edges/pi_session_id intact as history), mint a
+//     (mark canceled, keep its id/edges/pi_session_id intact as history), mint a
 //     FRESH node id, and re-exec pi in the current pane bound to the new id.
 //     The old id never changes meaning; external refs stay valid.
 //   • resetRoot (fallback) — for a non-root child (session-id refresh only) or
@@ -15,7 +15,8 @@
 // Termination semantics: a pi that ends cleanly resolves its node to `done`
 // (markCleanExitDone); only a true crash leaves it `dead`. A force-kill
 // (closeWindow / respawn-pane -k) fires NO clean session_shutdown, so reaped
-// descendants are marked `done` explicitly here.
+// descendants are marked `canceled` explicitly here (A5: an externally-reaped
+// node did not finish its own work — done is reserved for finalize).
 //
 // Best-effort throughout: a tmux/fs failure on one node never aborts the reset.
 import { existsSync, rmSync } from 'node:fs';
@@ -29,26 +30,29 @@ import { relaunchRootInPane } from './revive.js';
 // ---------------------------------------------------------------------------
 // reapDescendants — tear down a root's descendant sub-DAG (shared helper)
 // ---------------------------------------------------------------------------
-/** Reap the descendant sub-DAG of `rootId`: mark each **done** (the user moved
- *  on — a clean teardown, NOT a fault) + clear intent FIRST, then kill its
+/** Reap the descendant sub-DAG of `rootId`: mark each **canceled** (the user
+ *  moved on — a clean teardown, NOT a fault) + clear intent FIRST, then kill its
  *  window (closes the daemon revive race). Edges are LEFT INTACT — descendants
  *  keep parent=rootId. No wipe. Returns the reaped ids.
  *
- *  Why `done`, and why marking is STILL explicit: a `closeWindow`/`respawn-pane
- *  -k` kill is abrupt and fires NO clean `session_shutdown`, so the general
- *  quit→done rule does NOT auto-resolve a force-killed descendant — we mark it
- *  `done` here. Shared by relaunchRoot (option C) and resetRoot's in-place
- *  fallback, so both leave their descendants `done`. */
+ *  Why `canceled` (A5, human-confirmed 2026-06-06): an externally-reaped node —
+ *  whether via `node close` OR a root reset/relaunch — did not finish its OWN
+ *  work, so it unifies on `canceled`; `done` is reserved for finalize. Why
+ *  marking is STILL explicit: a `closeWindow`/`respawn-pane -k` kill is abrupt
+ *  and fires NO clean `session_shutdown`, so the general quit→done rule does NOT
+ *  auto-resolve a force-killed descendant — we mark it `canceled` here via the
+ *  same `cancel` event the close cascade uses. Shared by relaunchRoot (option C)
+ *  and resetRoot's in-place fallback, so both leave their descendants `canceled`. */
 export function reapDescendants(rootId) {
     const reaped = [];
     for (const id of view(rootId)) {
         try {
             // Reap BEFORE tearing down the placement (the crash-safety invariant the
-            // `reap` event encodes): a non-supervised status + cleared intent first, so
+            // `cancel` event encodes): a non-supervised status + cleared intent first, so
             // the daemon can't revive a descendant mid-teardown. tearDownNode then
             // closes any focus row it held, kills its pane (pane-keyed), and nulls its
             // LOCATION.
-            transition(id, 'reap');
+            transition(id, 'cancel');
             tearDownNode(id);
             reaped.push(id);
         }
@@ -77,7 +81,7 @@ export function resetRoot(nodeId, newSessionId, newSessionFile) {
         }
         return { reaped: [], detached: [], reset: false };
     }
-    // 1) Reap the descendant sub-DAG (mark done + kill windows; shared helper).
+    // 1) Reap the descendant sub-DAG (mark canceled + kill windows; shared helper).
     const reaped = reapDescendants(nodeId);
     // 2) Detach the root's own subscriptions so its view is empty.
     const detached = [];
@@ -164,7 +168,7 @@ export function relaunchRoot(oldId, pane, deps = {}) {
     const oldMeta = getNode(oldId);
     if (oldMeta === null || oldMeta.parent != null)
         return null; // defensive: not a root
-    if (oldMeta.status === 'done')
+    if (oldMeta.status === 'canceled')
         return null; // defensive: already parked (rapid double /new)
     const respawn = deps.relaunchRootInPane ?? relaunchRootInPane;
     // Resolve where the new pi will live (pane authoritative; fall back to old
@@ -186,7 +190,7 @@ export function relaunchRoot(oldId, pane, deps = {}) {
     const db = openDb();
     db.exec('BEGIN');
     try {
-        // 1) Reap descendants (mark done + kill windows, keep edges, no wipe).
+        // 1) Reap descendants (mark canceled + kill windows, keep edges, no wipe).
         reapDescendants(oldId);
         // 2) Create the fresh root node (new id, empty context dir via
         //    ensureNodeDirs) seeded active; `yield` adds the refresh safety net so
@@ -208,10 +212,11 @@ export function relaunchRoot(oldId, pane, deps = {}) {
         // of the pane it is respawned into (same pane-recycle rule as demote).
         updateNode(newId, { home_session: loc.session ?? nodeSession() });
         clearPid(newId); // no pi yet → daemon 'leave' until boot records the pid
-        // 3) Park the old root: reap (done + intent cleared) and detach its window so
-        //    it never claims the pane, but KEEP pi_session_id (resumable),
-        //    parent=null, and all edges.
-        transition(oldId, 'reap');
+        // 3) Park the old root: cancel (canceled + intent cleared) and detach its
+        //    window so it never claims the pane, but KEEP pi_session_id (resumable),
+        //    parent=null, and all edges. A5: a superseded old root did not finish its
+        //    own work — it unifies on `canceled` like every other external reap.
+        transition(oldId, 'cancel');
         setPresence(oldId, { window: null, tmux_session: null });
         // 4) Focus follows content: repoint the old root's focus row to the new root
         //    (same pane — respawn-pane -k below keeps the %id). Inside the txn → the

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);

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