@crouton-kit/crouter 0.3.15 → 0.3.16

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

@@ -0,0 +1,173 @@
+// 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.
+//
+//   The name is literally `resume-node`, NOT `resume`, to avoid clashing with
+//   pi's built-in /resume.
+//
+// ⚠ 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`.
+//
+// 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';
+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;
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+/**
+ * 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: 'Resume a node — pick from the whole canvas (incl. dormant) and revive it',
+        handler: async (_args, ctx) => {
+            // select() is a terminal-only dialog — guard the run mode before it.
+            if (ctx.mode !== 'tui') {
+                try {
+                    ctx.ui.notify('/resume-node needs the interactive TUI', 'warning');
+                }
+                catch { /* best-effort */ }
+                return;
+            }
+            let forest;
+            try {
+                forest = buildForest();
+            }
+            catch {
+                try {
+                    ctx.ui.notify('resume: could not read the canvas', 'error');
+                }
+                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).
+            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 */
+            }
+        },
+    });
+}
+export default registerCanvasResume;

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

@@ -28,15 +28,13 @@
 // 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 { 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.
@@ -423,11 +421,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "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": {

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

@@ -1,30 +0,0 @@
-import type { NodeMeta } from '../canvas/index.js';
-/** Persist `nodeId` as the currently focused node. Best-effort; never throws.
- *  Also maintains the transitional focus.ptr↔focuses-table dual-write bridge
- *  (see below) so Step 6 can flip reads to the table with no data gap. */
-export declare function setFocus(nodeId: string): void;
-/** Read the currently focused node id, or null if there is no active focus.
- *  Reads `focus.ptr` first; FALLS BACK to the canonical focuses row (the bridge,
- *  below) when the pointer is absent/empty — so a reader sees the same focus
- *  whichever store a writer reached. Best-effort; never throws. */
-export declare function getFocus(): string | null;
-/** True when the node's tmux window is alive.  A falsy tmux_session/window
- *  always returns false so callers don't need to null-guard. */
-export declare function nodeLive(meta: NodeMeta): boolean;
-/** Bring a node's tmux window to the foreground and record it as focused.
- *
- * Strategy:
- *   - If the node has no live window (`nodeLive` is false), still write the
- *     focus pointer — the caller (e.g. revive logic) uses `focused:false` to
- *     know it needs to open a window first.
- *   - Otherwise call `switchClient` (lands us in the right session) then
- *     `selectWindow` (picks the right window within it).  Both calls are
- *     best-effort; the focus pointer is always written regardless.
- *
- * Returns:
- *   focused — whether the tmux focus actually succeeded.
- *   session — the tmux session name if one was attempted, null otherwise. */
-export declare function focusNode(nodeId: string): {
-    focused: boolean;
-    session: string | null;
-};

package/dist/core/runtime/presence.js

@@ -1,178 +0,0 @@
-// presence.ts — focus pointer + per-node liveness helpers.
-//
-// The focus pointer (`<crtrHome>/focus.ptr`) is a plain-text file holding the
-// node id that currently "has focus" — meaning the user's terminal is showing
-// that node's tmux window. It is written on every explicit `focusNode()` call
-// and read by the dashboard / status-line to highlight the active node.
-//
-// This is intentionally a simple file-based pointer rather than a database
-// column: focus is transient UI state, not durable business data. A crash
-// leaves a stale pointer that the next focusNode() clobbers — harmless.
-//
-// focusNode() does two things:
-//   1. Ensures the user's terminal lands on the right tmux window by calling
-//      switchClient (cross-session) then selectWindow (in-session). Both are
-//      best-effort; we set the pointer regardless so the dashboard stays in sync.
-//   2. Persists the node id to focus.ptr so any process can quickly read "what
-//      is the user looking at?".
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
-import { join } from 'node:path';
-import { crtrHome, getNode, getRow, openFocusRow, closeFocusRow, getFocusById, getFocusByNode, } from '../canvas/index.js';
-import { selectWindow, switchClient, windowAlive, currentTmux, inTmux } from './tmux.js';
-// ---------------------------------------------------------------------------
-// Focus pointer
-// ---------------------------------------------------------------------------
-/** Absolute path to the focus pointer file. */
-function focusPtrPath() {
-    return join(crtrHome(), 'focus.ptr');
-}
-/** Persist `nodeId` as the currently focused node. Best-effort; never throws.
- *  Also maintains the transitional focus.ptr↔focuses-table dual-write bridge
- *  (see below) so Step 6 can flip reads to the table with no data gap. */
-export function setFocus(nodeId) {
-    try {
-        const p = focusPtrPath();
-        mkdirSync(dirname(p), { recursive: true });
-        writeFileSync(p, nodeId, 'utf8');
-    }
-    catch {
-        /* focus pointer is best-effort; never surface */
-    }
-    syncBridgeFocusRow(nodeId); // Step-4 dual-write bridge (REMOVED in Step 8)
-}
-/** Read the currently focused node id, or null if there is no active focus.
- *  Reads `focus.ptr` first; FALLS BACK to the canonical focuses row (the bridge,
- *  below) when the pointer is absent/empty — so a reader sees the same focus
- *  whichever store a writer reached. Best-effort; never throws. */
-export function getFocus() {
-    try {
-        const raw = readFileSync(focusPtrPath(), 'utf8').trim();
-        if (raw !== '')
-            return raw;
-    }
-    catch {
-        /* pointer absent — fall through to the table */
-    }
-    // Bridge fallback: the canonical focus row's occupant (Step-8 removal).
-    try {
-        return getFocusById(BRIDGE_FOCUS_ID)?.node_id ?? null;
-    }
-    catch {
-        return null;
-    }
-}
-// ---------------------------------------------------------------------------
-// Transitional focus.ptr ↔ focuses-table dual-write bridge.
-//
-// THROWAWAY — DELETED IN STEP 8. Today `focus.ptr` owns the single "current"
-// focus. Step 4 stands up the plural `focuses` table but nothing reads it as
-// authority yet (that switch is Step 6). To populate it in lockstep WITHOUT a
-// behavior change, every `setFocus` ALSO writes one canonical focus row that
-// mirrors `focus.ptr`, and `getFocus` falls back to it. Step 6 replaces
-// focusNodeInPlace with retargetFocus/openFocus, which write pane-correct focus
-// rows directly — then this bridge (and focus.ptr) is removed.
-// ---------------------------------------------------------------------------
-/** The fixed focus_id of the one canonical row that mirrors `focus.ptr`. */
-const BRIDGE_FOCUS_ID = '__focus_ptr__';
-/** Best-effort pane/session for the canonical focus row. A bare `setFocus(id)`
- *  only carries a node id, but a focus row wants pane+session. Resolve them
- *  READ-ONLY from the node's already-stored LOCATION (`row.pane`/`tmux_session`),
- *  else from the caller's current tmux pane (`currentTmux`).
- *
- *  DELIBERATE DEVIATION from the design's "run reconcile(nodeId) first": reconcile
- *  WRITES node presence via setPresence, and `setFocus` has many non-focus callers
- *  (reset/close/demote/tmux-spread). Reconciling on every setFocus would mutate
- *  their nodes' LOCATION as an invisible side-effect of a dual-write that is
- *  supposed to change NOTHING this step. So the bridge reads, never reconciles;
- *  best-effort is fine THIS step (nothing reads the row as authority until Step 6,
- *  which replaces these writers with pane-correct retargetFocus/openFocus). */
-function resolveBridgePaneSession(nodeId) {
-    try {
-        const row = getRow(nodeId);
-        if (row?.pane != null && row.pane !== '') {
-            return { pane: row.pane, session: row.tmux_session ?? null };
-        }
-        if (inTmux()) {
-            const cur = currentTmux();
-            if (cur)
-                return { pane: cur.pane, session: cur.session };
-        }
-    }
-    catch {
-        /* best-effort */
-    }
-    return { pane: null, session: null };
-}
-/** Mirror the current focus into the single canonical focuses row. `''` closes
- *  it (focus cleared). Otherwise re-point the row at `nodeId`: drop the prior
- *  canonical row and any row already holding `nodeId` (UNIQUE(node_id) safety)
- *  before re-inserting. All best-effort — a failure here must never break a
- *  setFocus caller or the build. */
-function syncBridgeFocusRow(nodeId) {
-    try {
-        if (nodeId === '') {
-            closeFocusRow(BRIDGE_FOCUS_ID);
-            return;
-        }
-        // Step 6: retargetFocus/openFocus now write REAL (pane-correct) focus rows.
-        // If one already shows this node, the table is already authoritative —
-        // focus.ptr (the file, written above) names the node and getFocus's fallback
-        // reads the real row. Drop any stale bridge row and PIGGYBACK on the real
-        // one; never duplicate-insert (UNIQUE node_id) or clobber it.
-        const real = getFocusByNode(nodeId);
-        if (real !== null && real.focus_id !== BRIDGE_FOCUS_ID) {
-            closeFocusRow(BRIDGE_FOCUS_ID);
-            return;
-        }
-        const { pane, session } = resolveBridgePaneSession(nodeId);
-        closeFocusRow(BRIDGE_FOCUS_ID);
-        openFocusRow(BRIDGE_FOCUS_ID, pane, session, nodeId);
-    }
-    catch {
-        /* dual-write is best-effort; never surface */
-    }
-}
-// ---------------------------------------------------------------------------
-// Liveness
-// ---------------------------------------------------------------------------
-/** True when the node's tmux window is alive.  A falsy tmux_session/window
- *  always returns false so callers don't need to null-guard. */
-export function nodeLive(meta) {
-    return windowAlive(meta.tmux_session, meta.window);
-}
-// ---------------------------------------------------------------------------
-// Focus
-// ---------------------------------------------------------------------------
-/** Bring a node's tmux window to the foreground and record it as focused.
- *
- * Strategy:
- *   - If the node has no live window (`nodeLive` is false), still write the
- *     focus pointer — the caller (e.g. revive logic) uses `focused:false` to
- *     know it needs to open a window first.
- *   - Otherwise call `switchClient` (lands us in the right session) then
- *     `selectWindow` (picks the right window within it).  Both calls are
- *     best-effort; the focus pointer is always written regardless.
- *
- * Returns:
- *   focused — whether the tmux focus actually succeeded.
- *   session — the tmux session name if one was attempted, null otherwise. */
-export function focusNode(nodeId) {
-    const meta = getNode(nodeId);
-    // Always write the pointer so the dashboard reflects intent even when focus
-    // fails (e.g. we're not currently inside tmux).
-    setFocus(nodeId);
-    if (meta === null || !nodeLive(meta)) {
-        // Node not found or window is gone — caller may need to revive.
-        return { focused: false, session: meta?.tmux_session ?? null };
-    }
-    // Both fields are non-null thanks to nodeLive() returning true.
-    const session = meta.tmux_session;
-    const window = meta.window;
-    // Cross-session hop first, then window selection within the session.
-    // switchClient may be a no-op when already in the same session but is
-    // always safe to call — tmux handles it gracefully.
-    const clientOk = switchClient(session);
-    const windowOk = selectWindow(session, window);
-    return { focused: clientOk && windowOk, session };
-}