@crouton-kit/crouter 0.3.35 → 0.3.37

package/dist/commands/push.js

@@ -1,10 +1,8 @@
-// `crtr push` + `crtr feed` — the one verb up the graph, and its read side.
+// `crtr push` — the one verb up the graph.
 //
 //   crtr push update [body]   — routine progress to subscribers
 //   crtr push urgent [body]   — force-wake subscribers
 //   crtr push final  [body]   — finish: write result, mark node done, close window
-//   crtr feed read            — drain the caller's (or a named) inbox into a digest
-//   crtr feed peek            — live state of the nodes below you, cursor untouched
 //
 // "push" is THE verb a node uses to talk to its managers; the tier is the
 // subcommand. The caller's node is resolved from CRTR_NODE_ID (injected by the
@@ -13,8 +11,7 @@
 import { defineBranch, defineLeaf } from '../core/command.js';
 import { InputError, readStdinRaw } from '../core/io.js';
 import { push } from '../core/feed/feed.js';
-import { getNode, subscribersOf, subscriptionsOf, fullName } from '../core/canvas/index.js';
-import { readInboxSince, readInboxEntryById, readCursor, writeCursor, coalesce, } from '../core/feed/inbox.js';
+import { getNode, subscribersOf } from '../core/canvas/index.js';
 function requireCallerNode() {
     const id = process.env['CRTR_NODE_ID'];
     if (id === undefined || id.trim() === '') {
@@ -142,213 +139,6 @@ function makeTierLeaf(tier) {
     });
 }
 // ---------------------------------------------------------------------------
-// feed read — drain the inbox
-// ---------------------------------------------------------------------------
-const feedReadLeaf = defineLeaf({
-    name: 'read',
-    description: 'drain unread pointers into a digest',
-    whenToUse: 'you want to PROACTIVELY poll what the nodes you subscribe to — your children and anyone you follow — have reported before the watcher wakes you, draining the unread pointers in your inbox into one coalesced digest. NOTE: when a subscriber push wakes you, that wake message already IS this digest (the watcher drains your inbox to wake you), so don\'t re-run feed read to "open" it — dereference the refs in the digest you already have. Reach for it to poll before the next wake, to inspect another node\'s inbox, or to re-read the whole history after the cursor has advanced.',
-    help: {
-        name: 'feed read',
-        summary: 'drain unread inbox pointers for the caller (or a named node) into a compact digest',
-        params: [
-            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node whose inbox to read. Defaults to CRTR_NODE_ID. Use to inspect a worker\'s inbox as an orchestrator.' },
-            { kind: 'flag', name: 'all', type: 'bool', required: false, default: false, constraint: 'Ignore the cursor and return everything from the start — use to re-read history the wake already drained.' },
-        ],
-        output: [
-            { name: 'node_id', type: 'string', required: true, constraint: 'Node whose inbox was read.' },
-            { name: 'digest', type: 'string', required: true, constraint: 'Coalesced digest — paste directly into a prompt.' },
-            { name: 'entries', type: 'object[]', required: true, constraint: 'Raw InboxEntry objects.' },
-            { name: 'cursor', type: 'string', required: true, constraint: 'New cursor ISO written after draining.' },
-            { name: 'inbox_total', type: 'number', required: true, constraint: 'Total entries in the inbox (read + unread). Distinguishes a never-used inbox from one already drained at wake.' },
-        ],
-        outputKind: 'object',
-        effects: ['Advances nodes/<nodeId>/inbox.jsonl.cursor.', 'Read-only on inbox.jsonl itself.'],
-    },
-    run: async (input) => {
-        const nodeId = typeof input['node'] === 'string' && input['node'].trim() !== ''
-            ? input['node'].trim()
-            : requireCallerNode();
-        const cursor = input['all'] === true ? undefined : readCursor(nodeId);
-        const entries = readInboxSince(nodeId, cursor);
-        const total = readInboxSince(nodeId, undefined).length;
-        const newCursor = entries.length > 0 ? entries[entries.length - 1].ts : cursor ?? new Date().toISOString();
-        writeCursor(nodeId, newCursor);
-        return {
-            node_id: nodeId,
-            digest: coalesce(entries),
-            entries: entries,
-            cursor: newCursor,
-            inbox_total: total,
-        };
-    },
-    render: (r) => {
-        const n = Array.isArray(r['entries']) ? r['entries'].length : 0;
-        const rawDigest = typeof r['digest'] === 'string' ? r['digest'] : '';
-        if (n > 0 && rawDigest.trim() !== '') {
-            return `${n} unread pointer${n === 1 ? '' : 's'} drained from ${r['node_id']}'s inbox.\n\n${rawDigest.trim()}`;
-        }
-        // Empty drain has two distinct causes — say which, honestly. An inbox that
-        // already holds entries was drained when the watcher woke you (the wake
-        // message WAS that digest); a never-used inbox simply has nothing yet.
-        const total = typeof r['inbox_total'] === 'number' ? r['inbox_total'] : 0;
-        const explanation = total > 0
-            ? 'Your inbox is not empty, though. The watcher drains your inbox to wake you, so the entries you already saw in your wake message are the same ones you would read here; that is why this is empty. Re-read the whole history (full message bodies included) with `crtr feed read --all`, or dereference the refs from the wake digest you already have.'
-            : 'Your inbox is empty — nothing has arrived from your subscriptions yet. Expected while workers run: a worker that has not pushed yet leaves no pointer, and it will wake you the moment it does. The wake is automatic — just continue your own work or end your turn. (Reach for `crtr feed peek` only if you suspect a worker died, not to confirm a live one.)';
-        return `No unread pointers for ${r['node_id']} (unread=0).\n\n${explanation}`;
-    },
-});
-// ---------------------------------------------------------------------------
-// feed message — read one inbox message's full body back from the jsonl
-// ---------------------------------------------------------------------------
-const feedMessageLeaf = defineLeaf({
-    name: 'message',
-    description: 'print one inbox entry\'s full body by id',
-    whenToUse: 'a digest line ended in `… (clipped — full message: crtr feed message <id>)` — run it to read the rest of that direct message. The full body lives in your inbox.jsonl; this prints it verbatim by the entry\'s short id. Read-only: it does NOT advance your inbox cursor.',
-    help: {
-        name: 'feed message',
-        summary: 'print the full body of one inbox entry, addressed by the short id shown in a clipped digest line',
-        params: [
-            { kind: 'positional', name: 'id', required: true, constraint: 'The short entry id from the digest\'s `… (full message: …)` pointer.' },
-            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Whose inbox to read. Defaults to CRTR_NODE_ID; pass to read another node\'s inbox as an orchestrator.' },
-        ],
-        output: [
-            { name: 'node_id', type: 'string', required: true, constraint: 'Node whose inbox was read.' },
-            { name: 'id', type: 'string', required: true, constraint: 'The requested entry id.' },
-            { name: 'found', type: 'boolean', required: true, constraint: 'True when an entry with that id exists.' },
-            { name: 'from', type: 'string', required: false, constraint: 'Sender of the message, when found.' },
-            { name: 'body', type: 'string', required: false, constraint: 'Full message body, when found.' },
-        ],
-        outputKind: 'object',
-        effects: ['Read-only: scans inbox.jsonl. Does NOT advance the cursor.'],
-    },
-    run: async (input) => {
-        const nodeId = typeof input['node'] === 'string' && input['node'].trim() !== ''
-            ? input['node'].trim()
-            : requireCallerNode();
-        const id = input['id'].trim();
-        const entry = readInboxEntryById(nodeId, id);
-        if (entry === undefined) {
-            return { node_id: nodeId, id, found: false };
-        }
-        const body = typeof entry.data?.['body'] === 'string' ? entry.data['body'] : entry.label;
-        return { node_id: nodeId, id, found: true, from: entry.from ?? 'system', body };
-    },
-    render: (r) => {
-        if (r['found'] !== true) {
-            return `No inbox entry with id ${r['id']} in ${r['node_id']}'s inbox. Re-read the digest with \`crtr feed read --all\`, or list raw entries to find the right id.`;
-        }
-        return `Full message ${r['id']} (from ${r['from']}):\n\n${r['body']}`;
-    },
-});
-// ---------------------------------------------------------------------------
-// feed peek — live state of the nodes below you, without draining anything
-// ---------------------------------------------------------------------------
-const STATUS_GLYPH = {
-    active: '●', idle: '○', done: '✓', dead: '✗', canceled: '⊘',
-};
-/** Coarse "Nm ago" age from an ISO timestamp — enough to read staleness at a glance. */
-function fmtAge(iso) {
-    const ms = Date.now() - new Date(iso).getTime();
-    if (!Number.isFinite(ms) || ms < 0)
-        return 'just now';
-    const s = Math.floor(ms / 1000);
-    if (s < 60)
-        return `${s}s ago`;
-    const m = Math.floor(s / 60);
-    if (m < 60)
-        return `${m}m ago`;
-    const h = Math.floor(m / 60);
-    if (h < 24)
-        return `${h}h ago`;
-    return `${Math.floor(h / 24)}d ago`;
-}
-const feedPeekLeaf = defineLeaf({
-    name: 'peek',
-    description: 'live state of the nodes below you, without draining anything',
-    whenToUse: 'you are about to end a turn and want to confirm your workers are running before you chill — peek shows every node you subscribe to (the workers below you) with its live status (working/idle/done/dead), how long it has run, its cycle count, and whether it has pushed yet, plus a one-line verdict on whether it is safe to yield. Non-destructive: it never advances your inbox cursor, so a later `feed read` still delivers undrained reports. Reach for it exactly when the feed reads empty but you have outstanding children — that empty feed is EXPECTED (a worker that has not pushed yet contributes no inbox pointer); peek confirms those workers are alive and running async so you can stop and wait instead of polling.',
-    help: {
-        name: 'feed peek',
-        summary: 'show the live state of every node you subscribe to (the workers below you) with a yield-or-not verdict; never drains the inbox',
-        params: [
-            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node whose subscriptions to peek. Defaults to CRTR_NODE_ID. Use to inspect a worker\'s downstream as an orchestrator.' },
-        ],
-        output: [
-            { name: 'node_id', type: 'string', required: true, constraint: 'Node that was peeked.' },
-            { name: 'unread', type: 'number', required: true, constraint: 'Inbox pointers not yet drained by `feed read`.' },
-            { name: 'children', type: 'object[]', required: true, constraint: 'One row per subscription: {node_id, kind, name, status, active, spawned, cycles, last_push}.' },
-        ],
-        outputKind: 'object',
-        effects: ['Read-only: reads canvas.db edges + node metas + inbox.jsonl.', 'Does NOT advance the inbox cursor — peek leaves the feed intact for a later `feed read`.'],
-    },
-    run: async (input) => {
-        const nodeId = typeof input['node'] === 'string' && input['node'].trim() !== ''
-            ? input['node'].trim()
-            : requireCallerNode();
-        // Read the WHOLE inbox to find each child's last push, but with no cursor
-        // write — peek is non-destructive by contract. `unread` is computed from the
-        // persisted cursor so peek can tell you a `feed read` would deliver something.
-        const all = readInboxSince(nodeId, undefined);
-        const unread = readInboxSince(nodeId, readCursor(nodeId)).length;
-        const children = subscriptionsOf(nodeId).map((s) => {
-            const n = getNode(s.node_id);
-            const fromMe = all.filter((e) => e.from === s.node_id);
-            const last = fromMe.length > 0 ? fromMe[fromMe.length - 1] : undefined;
-            return {
-                node_id: s.node_id,
-                kind: n?.kind ?? '?',
-                name: n !== null ? fullName(n) : s.node_id,
-                status: n?.status ?? 'dead',
-                active: s.active,
-                spawned: n?.created ?? s.created,
-                cycles: n?.cycles ?? 0,
-                last_push: last !== undefined
-                    ? { kind: last.kind, ts: last.ts, ref: last.ref ?? null, label: last.label }
-                    : null,
-            };
-        });
-        return { node_id: nodeId, unread, children };
-    },
-    render: (r) => {
-        const id = r['node_id'];
-        const unread = r['unread'] ?? 0;
-        const kids = r['children'] ?? [];
-        if (kids.length === 0) {
-            const tail = unread > 0
-                ? `${unread} unread report${unread === 1 ? '' : 's'} sit in your inbox — run \`crtr feed read\` to absorb ${unread === 1 ? 'it' : 'them'}.`
-                : 'If you spawned workers, they have finished and detached, or you never subscribed. Nothing will wake you.';
-            return `No nodes below you (0 subscriptions, ${unread} unread). ${tail}`;
-        }
-        const working = kids.filter((k) => k.status === 'active' || k.status === 'idle');
-        const liveWaking = working.filter((k) => k.active); // active sub to a live node = it will wake me
-        const done = kids.filter((k) => k.status === 'done' || k.status === 'canceled');
-        const dead = kids.filter((k) => k.status === 'dead');
-        let line;
-        if (dead.length > 0) {
-            line = `\u26a0 ${dead.length} below you ${dead.length === 1 ? 'is' : 'are'} dead and will NOT wake you. Inspect with \`crtr node inspect show <id>\`, then re-delegate or proceed without ${dead.length === 1 ? 'it' : 'them'}.`;
-        }
-        else if (liveWaking.length > 0) {
-            line = `Safe to yield \u2014 ${liveWaking.length} worker${liveWaking.length === 1 ? '' : 's'} running async will wake you on the next push. Nothing to do now; end your turn and chill.`;
-        }
-        else if (unread > 0) {
-            line = `Nothing still running, but ${unread} unread report${unread === 1 ? '' : 's'} \u2014 run \`crtr feed read\` to absorb ${unread === 1 ? 'it' : 'them'}, then continue or finish.`;
-        }
-        else {
-            line = 'Everything below you has finished and been drained \u2014 nothing is running. Continue your own work, or `crtr push final` to finish.';
-        }
-        const rows = kids.map((k) => {
-            const sub = k.active ? '' : ' (passive)';
-            const push = k.last_push !== null
-                ? `pushed ${fmtAge(k.last_push.ts)} [${k.last_push.kind}]${k.last_push.ref !== null ? ` ref:${k.last_push.ref}` : ''}`
-                : 'no push yet';
-            const glyph = STATUS_GLYPH[k.status] ?? '?';
-            return `- ${glyph} ${k.name}${sub} (${k.node_id}) \u00b7 ${k.kind} \u00b7 ${k.status} \u00b7 spawned ${fmtAge(k.spawned)} \u00b7 cyc ${k.cycles} \u00b7 ${push}`;
-        }).join('\n');
-        const summary = `${kids.length} node${kids.length === 1 ? '' : 's'} below you — ${working.length} working, ${done.length} done, ${dead.length} dead, ${unread} unread:`;
-        return `${line}\n\n${summary}\n${rows}`;
-    },
-});
-// ---------------------------------------------------------------------------
 // Registration
 // ---------------------------------------------------------------------------
 export function registerPush() {
@@ -367,19 +157,3 @@ export function registerPush() {
         children: [makeTierLeaf('update'), makeTierLeaf('urgent'), makeTierLeaf('final')],
     });
 }
-export function registerFeed() {
-    return defineBranch({
-        name: 'feed',
-        rootEntry: {
-            concept: 'the read side of the spine — pointers your subscriptions have pushed',
-            desc: 'drain your inbox feed into a digest',
-            useWhen: 'catching up on what the nodes you subscribe to have reported',
-        },
-        help: {
-            name: 'feed',
-            summary: 'read the per-node inbox feed',
-            model: 'Each node has an inbox.jsonl that accumulates ~30-token pointers from publishers it subscribes to. The watcher drains this inbox to wake you, so the wake message you receive ALREADY IS the coalesced digest \u2014 dereference the reports that matter by reading their ref paths (a push carries a ref; a direct message inlines a bounded body preview, and when that clips it ends in `crtr feed message <id>` to read the full text back from the jsonl). `feed read` is for PROACTIVELY polling before a wake (it advances the cursor); after a wake it reads empty because the cursor already moved \u2014 use `--all` to re-read history. An empty feed is normal while workers run \u2014 a worker that has not pushed leaves no pointer \u2014 so use `feed peek` to see the live state of the nodes below you (and whether to yield) without draining anything.',
-        },
-        children: [feedReadLeaf, feedMessageLeaf, feedPeekLeaf],
-    });
-}

package/dist/commands/revive.js

@@ -164,8 +164,8 @@ export const reviveLeaf = defineLeaf({
                     next: 'Use --now only on a node the canvas shows as hanging (⚠). For a routine relaunch, omit --now.',
                 });
             }
-            // Mirror the daemon's faultRecoveryVerdict, which never kills a BUSY engine: a
-            // node mid-turn (busy marker present) is making progress, not wedged —
+            // The daemon never kills a BUSY engine (its verdict paths all return 'leave'
+            // on a live busy marker): a node mid-turn is making progress, not wedged —
             // refuse rather than SIGTERM it mid-flight.
             if (isBusy(nodeId)) {
                 throw new InputError({

package/dist/commands/{canvas-tmux-spread.js → surface-tmux-spread.js}

@@ -1,7 +1,10 @@
-// `crtr canvas tmux-spread <node>` — explode the local subtree into a tiled grid.
+// `crtr surface tmux-spread <node>` — explode the local subtree into a tiled grid.
 //
-// Bound by the alt+c → `e` chord (config: prefixBinds['e'].run = "canvas
-// tmux-spread {self}"). It "expands" the graph you are watching: the caller's
+// A genuine viewer-placement decision (tile every live viewer in a subtree into
+// one window), so it lives under `surface` alongside view/attach/workspace/web.
+// Also bound to the `/graph` view's `e` key (src/pi-extensions/canvas-nav.ts),
+// which shells this leaf directly for the cursor node. It "expands" the graph
+// you are watching: the caller's
 // own viewer pane is broken out into a BRAND-NEW window, then a surface-attach
 // viewer pane is tiled beside it for every broker-alive node in the local
 // subtree (ancestry root → self → descendants), so the user lands on a single
@@ -48,16 +51,16 @@ function brokerAlive(meta) {
 export const tmuxSpreadLeaf = defineLeaf({
     name: 'tmux-spread',
     description: 'break the caller\'s pane into a new window and tile a viewer for every broker-alive node in the local subtree',
-    whenToUse: 'you want the whole live subtree you are watching on one tiled tmux window at once — bound to the alt+c → e chord; rarely run by hand',
+    whenToUse: 'you want the whole live subtree you are watching on one tiled tmux window at once, instead of hunting down each node\'s viewer by hand — also bound to the `/graph` view\'s `e` key',
     help: {
-        name: 'canvas tmux-spread',
+        name: 'surface tmux-spread',
         summary: 'Explode the local subtree into a tiled grid: break the caller\'s viewer pane into a brand-new window, then tile a surface-attach viewer pane beside it for every broker-alive node (status active/idle + live pi_pid) in the ancestry-root subtree, most-recently-active first, capped at 8 panes',
         params: [
             {
                 kind: 'positional',
                 name: 'node',
                 required: true,
-                constraint: 'The spread anchor (self) — its ancestry root + descendants define the subtree to tile. The alt+c chord passes {self}.',
+                constraint: 'The spread anchor (self) — its ancestry root + descendants define the subtree to tile. Passed as {self} by the `/graph` view\'s `e` key.',
             },
             {
                 kind: 'flag',

package/dist/commands/surface.js

@@ -8,6 +8,7 @@ import { registerView } from './view.js';
 import { registerWorkspace } from './workspace.js';
 import { registerWeb } from '../clients/web/web-cmd.js';
 import { registerAttach } from '../clients/attach/attach-cmd.js';
+import { tmuxSpreadLeaf } from './surface-tmux-spread.js';
 function namespaceForSurface(node) {
     node.help.name = `surface ${node.help.name}`;
     if (node.kind === 'branch') {
@@ -36,8 +37,8 @@ export function registerSurface() {
         help: {
             name: 'surface',
             summary: 'open and manage screen-facing surfaces',
-            model: 'Four entrypoints share the screen-facing space. `view` hosts a standalone raw-ANSI surface in tmux; `attach` connects this pane to a node broker; `workspace` lays out the left rail plus chat pane in one tmux window; `web` serves the browser shell and broker relay. Pick the family by host and layout, then choose the leaf that matches the action.',
+            model: 'Five entrypoints share the screen-facing space. `view` hosts a standalone raw-ANSI surface in tmux; `attach` connects this pane to a node broker; `workspace` lays out the left rail plus chat pane in one tmux window; `web` serves the browser shell and broker relay; `tmux-spread` tiles a viewer for every live node in a local subtree into one new window. Pick the family by host and layout, then choose the leaf that matches the action.',
         },
-        children: [view, attach, workspace, web],
+        children: [view, attach, workspace, web, tmuxSpreadLeaf],
     });
 }

package/dist/commands/sys/daemon.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../../core/command.js';
+export declare const daemonBranch: BranchDef;

package/dist/commands/{daemon.js → sys/daemon.js}

@@ -1,4 +1,4 @@
-// `crtr canvas daemon` — thin supervisor daemon management.
+// `crtr sys daemon` — thin supervisor daemon management.
 //
 // The daemon (crtrd) polls active+idle nodes and handles engine-container exit
 // (a tmux pane or a headless broker process):
@@ -6,10 +6,10 @@
 //   • refresh-yield (intent=refresh) → fresh respawn
 //
 // This subtree starts, checks, and stops the daemon process.
-import { defineLeaf, defineBranch } from '../core/command.js';
-import { InputError } from '../core/io.js';
-import { spawnDaemon } from '../daemon/manage.js';
-import { readPidfile, isPidAlive } from '../daemon/crtrd.js';
+import { defineLeaf, defineBranch } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { spawnDaemon } from '../../daemon/manage.js';
+import { readPidfile, isPidAlive } from '../../daemon/crtrd.js';
 // ---------------------------------------------------------------------------
 // daemon start
 // ---------------------------------------------------------------------------
@@ -18,7 +18,7 @@ const daemonStart = defineLeaf({
     description: 'start the daemon in the background',
     whenToUse: 'bringing the crtrd supervisor up for the first time in a session so node window-exits get handled (no-op if it is already running)',
     help: {
-        name: 'canvas daemon start',
+        name: 'sys daemon start',
         summary: 'start the crtrd supervisor daemon in the background (no-op if already running)',
         params: [],
         output: [
@@ -43,9 +43,9 @@ const daemonStart = defineLeaf({
 const daemonStatus = defineLeaf({
     name: 'status',
     description: 'check whether the daemon is running',
-    whenToUse: 'checking whether the crtrd supervisor is running — e.g. confirming supervision is up before relying on auto-revive',
+    whenToUse: 'operator/dev diagnostic — probing whether the crtrd supervisor process is alive while troubleshooting revive/supervision behavior',
     help: {
-        name: 'canvas daemon status',
+        name: 'sys daemon status',
         summary: 'check whether the crtrd supervisor daemon is currently running',
         params: [],
         output: [
@@ -71,7 +71,7 @@ const daemonStop = defineLeaf({
     description: 'stop the running daemon',
     whenToUse: 'shutting the crtrd supervisor down, ending auto-revival of nodes on window exit',
     help: {
-        name: 'canvas daemon stop',
+        name: 'sys daemon stop',
         summary: 'send SIGTERM to the crtrd supervisor daemon',
         params: [],
         output: [
@@ -100,16 +100,16 @@ const daemonStop = defineLeaf({
     },
 });
 // ---------------------------------------------------------------------------
-// Export — mounted under `crtr canvas`
+// Export — mounted under `crtr sys`
 // ---------------------------------------------------------------------------
 export const daemonBranch = defineBranch({
     name: 'daemon',
     description: 'manage the crtrd supervisor process',
     whenToUse: 'managing the crtrd supervisor that auto-revives nodes on window exit — start it, check its status, or stop it',
     help: {
-        name: 'canvas daemon',
+        name: 'sys daemon',
         summary: 'manage the crtrd canvas supervisor daemon',
-        model: 'crtrd is a thin background daemon that polls active+idle nodes and acts on window exit: crashed windows become dead; refresh-yield windows get a fresh respawn. It holds no orchestration logic — just process supervision.',
+        model: 'crtrd is a thin background daemon that polls active+idle nodes and acts on window exit: crashed windows become dead; refresh-yield windows get a fresh respawn. It holds no orchestration logic — just process supervision. start/stop/status are operator/dev self-management, not something a normal agent turn needs to check.',
     },
     children: [daemonStart, daemonStatus, daemonStop],
 });

package/dist/commands/sys/doctor.js

@@ -71,6 +71,7 @@ function faultRemediation(fault) {
         auth: 're-authenticate',
         protocol: 'fix the protocol mismatch',
         other: 'fix the underlying issue',
+        wedged: 'read `crtr memory read wedged-child-on-runaway-bash` and, if a runaway subprocess is to blame, kill the subprocess (not the node)',
     };
     const progress = fault.retry.disposition === 'auto'
         ? fault.retry.by === 'client'

package/dist/commands/sys.js

@@ -2,6 +2,7 @@
 // Replaces old config.ts + doctor.ts + update.ts command files.
 import { defineBranch } from '../core/command.js';
 import { configBranch } from './sys/config.js';
+import { daemonBranch } from './sys/daemon.js';
 import { sysDoctorLeaf } from './sys/doctor.js';
 import { sysFeedbackLeaf } from './sys/feedback.js';
 import { sysSettingsLeaf } from './sys/settings.js';
@@ -16,13 +17,13 @@ export function registerSys() {
         name: 'sys',
         rootEntry: {
             concept: 'crtr configuration, diagnostics, and self-management',
-            desc: 'config, settings, setup, doctor, sysprompt, prompt-review, promptstudio, sync, update, version, feedback',
-            useWhen: 'managing the crtr installation or opening built-in system views',
+            desc: 'config, settings, setup, doctor, sysprompt, prompt-review, promptstudio, sync, update, version, feedback, daemon',
+            useWhen: 'managing the crtr installation, the crtrd supervisor process, or opening built-in system views',
         },
         help: {
             name: 'sys',
             summary: 'crtr system configuration, settings, diagnostics, and self-management',
         },
-        children: [configBranch, sysSettingsLeaf, sysSetupLeaf, sysDoctorLeaf, sysSyspromptLeaf, promptReviewLeaf, sysPromptStudioLeaf, sysFeedbackLeaf, sysUpdateLeaf, sysVersionLeaf, sysSyncLeaf],
+        children: [configBranch, sysSettingsLeaf, sysSetupLeaf, sysDoctorLeaf, sysSyspromptLeaf, promptReviewLeaf, sysPromptStudioLeaf, sysFeedbackLeaf, sysUpdateLeaf, sysVersionLeaf, sysSyncLeaf, daemonBranch],
     });
 }

package/dist/core/__tests__/daemon-boot.test.js

@@ -262,7 +262,7 @@ test('the daemon honours an explicit CRTR_PIDFILE override', () => {
 // REGRESSION (bug #102 follow-up): with NO exit promise, the readiness loop must
 // still observe a real `connect`. A buggy `?? Promise.resolve('retry')` race lost
 // to the probe instantly, so live-broker callers (focus on an already-alive node,
-// canvas-tmux-spread) could never return true and stalled the full 30s deadline.
+// surface tmux-spread) could never return true and stalled the full 30s deadline.
 test('waitForBrokerViewSocket returns true on a live socket when given no exit promise', async () => {
     // CRTR_SOCK_DIR override keeps the AF_UNIX path short — the temp CRTR_HOME path
     // would blow past macOS's 104-byte sun_path limit (listen EINVAL).

package/dist/core/__tests__/daemon-wedge.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/daemon-wedge.test.js

@@ -0,0 +1,87 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/daemon-wedge.test.ts
+//
+// Issue #110 — pid-alive WEDGED node detection. The pure decision core:
+// wedgeVerdict(busy, quietForMs, cpuPercent). No wall-clock sleeps, no ps
+// shell-outs, no fake pids — every input is injected directly, mirroring the
+// existing livenessVerdict/yieldStallVerdict suites in daemon-liveness.test.ts.
+//
+// LOCKS: (1) a routine long-running BUT ACTIVE turn (heartbeat recent, or CPU
+// non-trivial) must never verdict 'wedged' — false positives are the failure
+// mode this feature exists to avoid. (2) only busy+quiet+near-zero-CPU, all at
+// once, past the generous grace, fires. (3) a null/failed CPU sample never
+// fires on its own (fails toward 'pending', not 'wedged').
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { wedgeVerdict, WEDGE_QUIET_MS, WEDGE_CPU_MAX_PERCENT, sumTreeCpu } from '../../daemon/crtrd.js';
+test('wedgeVerdict: a node whose turn already ended is never wedged, regardless of the other signals', () => {
+    assert.equal(wedgeVerdict({ busy: false, quietForMs: null, cpuPercent: null }), 'leave');
+    assert.equal(wedgeVerdict({ busy: false, quietForMs: 10 * 60 * 60_000, cpuPercent: 0 }), 'leave');
+});
+test('wedgeVerdict: a busy node with an unreadable heartbeat is left alone (not enough evidence)', () => {
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: null, cpuPercent: null }), 'leave');
+});
+test('wedgeVerdict: routine turns — even long ones — never trip before the grace elapses', () => {
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: 0, cpuPercent: 0 }), 'leave', 'just started');
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: 5 * 60_000, cpuPercent: 0 }), 'leave', 'a routine multi-minute tool call');
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS - 1, cpuPercent: 0 }), 'leave', 'just under the grace, even with 0% cpu');
+});
+test('wedgeVerdict: past the grace with NO cpu corroboration only pends — never fires on time alone', () => {
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS, cpuPercent: null }), 'pending', 'cpu sample failed/unavailable — never treated as confirmation');
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS * 10, cpuPercent: null }), 'pending', 'no amount of extra quiet time substitutes for the corroborating signal');
+});
+test('wedgeVerdict: a long-quiet turn that is STILL VISIBLY WORKING (real cpu) is exonerated, not wedged', () => {
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS * 3, cpuPercent: WEDGE_CPU_MAX_PERCENT + 0.1 }), 'pending', 'cpu just above the ceiling — a genuinely churning long build — must not fire');
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS * 3, cpuPercent: 40 }), 'pending', 'clearly-active cpu never fires regardless of how quiet the heartbeat looks');
+});
+test('wedgeVerdict: fires ONLY when busy + quiet-past-grace + near-zero cpu all corroborate', () => {
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS, cpuPercent: 0 }), 'wedged');
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS + 60_000, cpuPercent: WEDGE_CPU_MAX_PERCENT }), 'wedged', 'at the cpu ceiling (inclusive)');
+});
+// ---------------------------------------------------------------------------
+// sumTreeCpu (pure) — process-tree CPU sampling. Review fix for issue #110:
+// sampling only the broker pid false-fired on a broker awaiting a busy CHILD
+// subprocess. These lock the tree-sum behavior directly, independent of any
+// `ps` shell-out.
+// ---------------------------------------------------------------------------
+test('sumTreeCpu: a busy CHILD subprocess exonerates an idle broker (the false-positive this fixes)', () => {
+    const ps = [
+        '  100     1  0.0', // broker, idle
+        '  200   100 85.0', // child of the broker, busy
+    ].join('\n');
+    assert.equal(sumTreeCpu(ps, 100), 85.0);
+});
+test('sumTreeCpu: broker + all descendants idle sums to ~0 (the real wedge is still detected)', () => {
+    const ps = [
+        '  100     1  0.0',
+        '  200   100  0.0',
+        '  201   100  0.0',
+    ].join('\n');
+    assert.equal(sumTreeCpu(ps, 100), 0);
+});
+test('sumTreeCpu: sums across multiple generations (grandchild busy)', () => {
+    const ps = [
+        '  100     1  0.0', // broker
+        '  200   100  0.0', // child, idle
+        '  300   200 40.0', // grandchild, busy
+    ].join('\n');
+    assert.equal(sumTreeCpu(ps, 100), 40.0);
+});
+test('sumTreeCpu: root pid absent from the ps output returns null (can\'t measure)', () => {
+    const ps = [
+        '  200     1  0.0',
+        '  300   200 10.0',
+    ].join('\n');
+    assert.equal(sumTreeCpu(ps, 100), null);
+});
+test('sumTreeCpu: malformed/blank lines are skipped; empty output returns null', () => {
+    const ps = [
+        '',
+        '   ',
+        'garbage line not ps shaped',
+        '  100     1  5.0',
+        '  bad   100  1.0',
+    ].join('\n');
+    assert.equal(sumTreeCpu(ps, 100), 5.0);
+    assert.equal(sumTreeCpu('', 100), null);
+    assert.equal(sumTreeCpu('   \n  \n', 100), null);
+});

package/dist/core/__tests__/hearth-bootstrap.test.js

@@ -91,7 +91,7 @@ test('every crtr invocation targets the baked binary by absolute path, never a b
         assert.match(script, /'\/usr\/local\/bin\/crtr' --json sys version/);
         assert.match(script, /'\/usr\/local\/bin\/crtr' surface web -h/);
         assert.match(script, /'\/usr\/local\/bin\/crtr' surface web serve -h/);
-        assert.match(script, /'\/usr\/local\/bin\/crtr' canvas daemon start/);
+        assert.match(script, /'\/usr\/local\/bin\/crtr' sys daemon start/);
         assert.match(script, /'\/usr\/local\/bin\/crtr' surface web serve --host 0\.0\.0\.0/);
         // No bare `crtr <subcommand>` invocation anywhere — only the `command -v
         // crtr` shadow-detection probe and human-readable error-message text are
@@ -123,7 +123,7 @@ test('mkdirs the tmpfs CRTR_SOCK_DIR/CRTR_PIDFILE dirs strictly before the daemo
     assert.doesNotMatch(script, /CRTR_CANVAS_DB=/);
     assert.match(script, /unset CRTR_CANVAS_DB/);
     const mkdirIdx = indexOf(script, '/run/crtr/socks');
-    const daemonStartIdx = indexOf(script, "'/usr/local/bin/crtr' canvas daemon start");
+    const daemonStartIdx = indexOf(script, "'/usr/local/bin/crtr' sys daemon start");
     assert.ok(mkdirIdx < daemonStartIdx, 'tmpfs mkdir must precede daemon start');
     const mkdirLine = script.split('\n').find((line) => line.startsWith('mkdir -p') && line.includes('/run/crtr/socks'));
     assert.ok(mkdirLine, 'expected a single mkdir line covering the tmpfs dirs');

package/dist/core/__tests__/history-inbox.test.d.ts

@@ -0,0 +1 @@
+export {};