@crouton-kit/crouter 0.3.45 → 0.3.47

package/dist/commands/{worktree.js → node-worktree.js}

@@ -1,3 +1,7 @@
+// `crtr node worktree` — the node-owned managed-worktree lifecycle. Birth is
+// `node new --worktree` (a flag on spawn); this branch holds the single close
+// verb, symmetric with birth, so a git worktree's whole lifecycle sits under
+// `node`.
 import { defineBranch, defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
 import { closeManagedWorktree, WorktreeError } from '../core/worktree.js';
@@ -27,7 +31,7 @@ const worktreeClose = defineLeaf({
     description: 'land and close the current node-managed worktree',
     whenToUse: 'you are inside the node that owns an open managed worktree and are ready to rebase it onto origin/main, push it to main, and (best-effort) remove the worktree and delete the branch before finishing',
     help: {
-        name: 'worktree close',
+        name: 'node worktree close',
         summary: 'land and close the current node-managed worktree',
         params: [],
         output: [
@@ -77,18 +81,13 @@ const worktreeClose = defineLeaf({
         return base;
     },
 });
-export function registerWorktree() {
-    return defineBranch({
-        name: 'worktree',
-        rootEntry: {
-            concept: 'crouter-managed git worktrees tied to node lifecycle',
-            desc: 'close a node-owned managed worktree',
-            useWhen: 'landing completed work from inside the node that owns the worktree',
-        },
-        help: {
-            name: 'worktree',
-            summary: 'manage a node-owned git worktree',
-        },
-        children: [worktreeClose],
-    });
-}
+export const nodeWorktreeBranch = defineBranch({
+    name: 'worktree',
+    description: 'manage a node-owned git worktree — close the one born by `node new --worktree`',
+    whenToUse: 'you are inside a node that was spawned with `node new --worktree` and are ready to land it: rebase onto origin/main, push, and close the worktree. Symmetric with `node new --worktree`, which births it',
+    help: {
+        name: 'node worktree',
+        summary: 'manage a node-owned git worktree — birth is `node new --worktree`; this branch closes it',
+    },
+    children: [worktreeClose],
+});

package/dist/commands/node.js

@@ -19,6 +19,9 @@ import { readRoadmap, hasRoadmap, seedRoadmap } from '../core/runtime/roadmap.js
 import { parseWhen, parseCadence, cadenceDisplay } from '../core/wake.js';
 import { nodeSnapshotLeaf } from './node-snapshot.js';
 import { nodeContextLeaf } from './node-context.js';
+import { nodeArtifactsLeaf } from './node-inspect-artifacts.js';
+import { nodeWorktreeBranch } from './node-worktree.js';
+import { nodeReviveLeaf } from './node-lifecycle-revive.js';
 import { recycleNode } from '../core/runtime/recycle.js';
 import { readFaultAsync } from '../core/runtime/fault.js';
 import { activeFaultForDisplay } from '../core/canvas/render.js';
@@ -128,7 +131,7 @@ const nodeNew = defineLeaf({
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name (tmux window + resume picker). Defaults to the kind.' },
             { kind: 'flag', name: 'parent', type: 'string', required: false, constraint: 'Parent node id. Defaults to the calling node (CRTR_NODE_ID).' },
             { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an INDEPENDENT root instead of a managed child: no parent (top-level on the canvas), NO subscription back to you (you are NOT woken by it), resident lifecycle. It records spawned_by=you for provenance and is brought forefront so it can be driven directly. Use for a node you hand off and do not manage (e.g. a sub-orchestrator a human will discuss with). Mutually exclusive with --worktree.' },
-            { kind: 'flag', name: 'worktree', type: 'bool', required: false, constraint: 'Use when the child will COMMIT to the repo while you or other agents may also be editing it — the worktree isolates its work so nothing collides; skip it for read-only work or when the child is the sole writer. Creates a crouter-managed git worktree for the spawned child, keyed by the child node id, at `~/.crouter/canvas/worktrees/<node-id>/` on branch `crtr/<node-id>` based on `origin/main`; the child\'s cwd is pinned there, and it lands the work serially onto origin/main later with `crtr worktree close`. Mutually exclusive with --root.' },
+            { kind: 'flag', name: 'worktree', type: 'bool', required: false, constraint: 'Use when the child will COMMIT to the repo while you or other agents may also be editing it — the worktree isolates its work so nothing collides; skip it for read-only work or when the child is the sole writer. Creates a crouter-managed git worktree for the spawned child, keyed by the child node id, at `~/.crouter/canvas/worktrees/<node-id>/` on branch `crtr/<node-id>` based on `origin/main`; the child\'s cwd is pinned there, and it lands the work serially onto origin/main later with `crtr node worktree close`. Mutually exclusive with --root.' },
             { kind: 'flag', name: 'fork-from', type: 'string', required: false, constraint: 'FORK the new node from an existing pi conversation instead of starting it fresh: pass a node id (forks from that node\'s session), an absolute session `.jsonl` path, or a partial pi session uuid. pi copies that whole history into a NEW session for the child (the source is untouched), then the prompt is delivered as the next message — i.e. the child wakes up as a continuation of that conversation. Use to branch exploratory work off a node that already built up the context you need, instead of re-deriving it. One-shot at birth: the fork resumes its own session thereafter.' },
             { kind: 'flag', name: 'model', type: 'string', required: false, constraint: 'Override the model the node runs on: exact `provider/id` (e.g. openai-codex/gpt-5.5), a `provider/tier` (anthropic|openai + ultra|strong|medium|light, e.g. openai/ultra — pin a specific model family, useful for spawning cross-family children), a bare capability TIER (ultra|strong|medium|light), or a family alias (opus|sonnet|haiku). Must resolve to a concrete model OFFLINE — unlike `node config --model`, no live broker exists yet at spawn to free-text substring-search a registry. Omit to use the kind\'s persona default (advisor=ultra, explore=light, most other builtins=strong). The override is durable — it survives revives and polymorphs (promote/demote).' },
             { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Select the profile this node runs under — an exact profile id or a unique manifest name (see the <profiles> list below, or `crtr profile list`). Omit to INHERIT the calling node\'s current profile (root has none, so an uninherited child has none either). --root does NOT reset this — it only means top-level, still inherits/uses the selected profile unless this overrides it.' },
@@ -157,7 +160,7 @@ const nodeNew = defineLeaf({
         dynamicState: () => [kindsStateBlock(), profilesStateBlock()].join('\n'),
         outputKind: 'object',
         effects: [
-            'Spawning now: creates a node under ~/.crouter/canvas/nodes/<id>/ and indexes it in canvas.db. Default (managed child): parent auto-subscribes (active) and is woken on the child\'s pushes. With --root: no subscription — records a spawned_by edge for provenance only. With --worktree: also creates a managed git worktree at ~/.crouter/canvas/worktrees/<node-id>/ on branch crtr/<node-id> based on origin/main; the child closes it later with `crtr worktree close` before finishing. With --output-schema: writes nodes/<id>/output-schema.json in terminal mode; the node must call submit, which writes context/result.json and pushes final. Launches the node\'s engine as a detached broker (the only host); a managed child opens NO viewer, a --root opens one in your current tmux session.',
+            'Spawning now: creates a node under ~/.crouter/canvas/nodes/<id>/ and indexes it in canvas.db. Default (managed child): parent auto-subscribes (active) and is woken on the child\'s pushes. With --root: no subscription — records a spawned_by edge for provenance only. With --worktree: also creates a managed git worktree at ~/.crouter/canvas/worktrees/<node-id>/ on branch crtr/<node-id> based on origin/main; the child closes it later with `crtr node worktree close` before finishing. With --output-schema: writes nodes/<id>/output-schema.json in terminal mode; the node must call submit, which writes context/result.json and pushes final. Launches the node\'s engine as a detached broker (the only host); a managed child opens NO viewer, a --root opens one in your current tmux session.',
             'Armed (--at/--every/--when): inserts one detached `new`/`node_birth` triggers row (node_id NULL, owner=you, parent/cwd resolved now); NO node and NO window exist until fire time. The daemon spawns from the stored recipe at fire time, re-deriving the launch spec live.',
         ],
     },
@@ -470,13 +473,13 @@ const nodeShow = defineLeaf({
 // ---------------------------------------------------------------------------
 const nodeInspect = defineBranch({
     name: 'inspect',
-    description: 'read the graph (list, show, context)',
-    whenToUse: 'reading the graph: enumerate nodes on the canvas (`list`), inspect one and its spine neighbors (`show`), or browse on-disk context dirs with `node inspect context` while reading a node. Use `canvas dashboard` instead to render the tree SHAPE, or `canvas attention` to find which nodes are blocked on a human',
+    description: 'read one node — its graph position, context, and artifacts',
+    whenToUse: 'reading everything about ONE node you can name: enumerate the roster (`list`), inspect a node and its spine neighbors (`show`), browse its on-disk context dir (`context`), or list its reports/docs as refs (`artifacts`). Use `canvas dashboard` instead to render the whole tree SHAPE, or `canvas attention` to find which nodes are blocked on a human',
     help: {
         name: 'node inspect',
-        summary: 'read the canvas graph — enumerate nodes, inspect one, or browse on-disk context dirs for a node',
+        summary: 'read one node (or the roster) — topology, context dir, and artifacts',
     },
-    children: [nodeList, nodeShow, nodeSnapshotLeaf, nodeContextLeaf],
+    children: [nodeList, nodeShow, nodeSnapshotLeaf, nodeContextLeaf, nodeArtifactsLeaf],
 });
 // ---------------------------------------------------------------------------
 // node focus — bring a node's viewer forefront (across roots if needed)
@@ -635,10 +638,10 @@ const nodeRecycle = defineLeaf({
 const nodeClose = defineLeaf({
     name: 'close',
     description: 'close a node + cascade-cancel its exclusive subtree (revivable)',
-    whenToUse: 'you want to tear a node down WITHOUT finishing it, cascade-cancelling every descendant it exclusively owns: abandoning a line of work, killing a stuck or wrong-turn subtree, clearing a branch you no longer need. Windows die but nothing is deleted — each closed node keeps its pi session and can be revived later (`canvas revive`). Use `node lifecycle recycle` instead to FINISH the agent in your pane with a final report, and `push final` when a worker should end its own work normally (Alt+C → x)',
+    whenToUse: 'you want to tear a node down WITHOUT finishing it, cascade-cancelling every descendant it exclusively owns: abandoning a line of work, killing a stuck or wrong-turn subtree, clearing a branch you no longer need. Windows die but nothing is deleted — each closed node keeps its pi session and can be revived later (`node lifecycle revive`). Use `node lifecycle recycle` instead to FINISH the agent in your pane with a final report, and `push final` when a worker should end its own work normally (Alt+C → x)',
     help: {
         name: 'node lifecycle close',
-        summary: 'close a node and cascade-cancel its subtree — kill its tmux window plus those of every descendant it EXCLUSIVELY owns (down the subscribes_to spine), mark them all canceled, and leave each a notice it reads on resume. A descendant still subscribed to by a manager outside the subtree is left running. Nothing is deleted: every closed node keeps its pi session and can be revived later (`crtr canvas revive`)',
+        summary: 'close a node and cascade-cancel its subtree — kill its tmux window plus those of every descendant it EXCLUSIVELY owns (down the subscribes_to spine), mark them all canceled, and leave each a notice it reads on resume. A descendant still subscribed to by a manager outside the subtree is left running. Nothing is deleted: every closed node keeps its pi session and can be revived later (`crtr node lifecycle revive`)',
         params: [
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to close. Defaults to the node occupying --pane (or your current pane).' },
             { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id whose node to close. Defaults to $TMUX_PANE / your current pane. The Alt+C menu passes this for you.' },
@@ -1539,13 +1542,13 @@ const nodeDemote = defineLeaf({
 // ---------------------------------------------------------------------------
 const nodeLifecycle = defineBranch({
     name: 'lifecycle',
-    description: 'lifecycle actions — recycle, close, demote a node',
-    whenToUse: 'you are ending or transitioning a node\'s life: finish the agent in your pane and reboot a fresh root (`recycle`), tear a node + its exclusive subtree down without finishing (`close`), or flip a node onto a finishing track in place (`demote`). To merely SET the terminal/resident attribute headlessly use `node config --lifecycle`; to FINISH from inside a node\'s own turn use `crtr push final`.',
+    description: 'lifecycle actions — recycle, close, demote, or revive a node',
+    whenToUse: 'you are ending, transitioning, or bringing back one node you can name: finish the agent in your pane and reboot a fresh root (`recycle`), tear a node + its exclusive subtree down without finishing (`close`), flip a node onto a finishing track in place (`demote`), or bring a dormant node back (`revive`). To merely SET the terminal/resident attribute headlessly use `node config --lifecycle`; to FINISH from inside a node\'s own turn use `crtr push final`; to mass-reconnect EVERY disconnected node at once use `canvas revive --all`.',
     help: {
         name: 'node lifecycle',
-        summary: 'end or transition a node — recycle the pane, close + cascade-cancel a subtree, or demote to terminal in place',
+        summary: 'end, transition, or revive a node — recycle the pane, close + cascade-cancel a subtree, demote to terminal in place, or revive a dormant node',
     },
-    children: [nodeRecycle, nodeClose, nodeDemote],
+    children: [nodeRecycle, nodeClose, nodeDemote, nodeReviveLeaf],
 });
 // ---------------------------------------------------------------------------
 // node yield — refresh: discard context, revive fresh against the roadmap
@@ -1820,6 +1823,6 @@ export function registerNode() {
                 'HOW: the new leaf returns a node id immediately and runs the worker as a detached headless broker; no viewer opens unless a surface asks for one. Match the kind to the work and read the leaf schema before invoking. You are woken when a child finishes — the wake message ALREADY IS the coalesced digest, so dereference the report paths in that digest that matter instead of acting on a one-line label. Integrate, then either delegate the next units or finish.\n\n' +
                 'FINISH: a worker ends its own work with a final push, which writes the canonical result, marks done, and closes the window; stopping without it is not finishing. For a job too big for one context window, promote to an orchestrator; when context fills, yield to refresh against that roadmap.',
         },
-        children: [nodeNew, nodeMsg, nodeSubscribe, nodeUnsubscribe, nodePromote, nodeYield, nodeFocus, nodeCycle, nodeInspect, nodeLifecycle, nodeConfig, nodeTriggers],
+        children: [nodeNew, nodeMsg, nodeSubscribe, nodeUnsubscribe, nodePromote, nodeYield, nodeFocus, nodeCycle, nodeInspect, nodeLifecycle, nodeConfig, nodeTriggers, nodeWorktreeBranch],
     });
 }

package/dist/commands/push.js

@@ -101,7 +101,7 @@ function makeTierLeaf(tier) {
                     throw new InputError({
                         error: 'open_managed_worktree',
                         message: 'This node still owns an open managed worktree — `push final` is blocked until it is closed.',
-                        next: 'Commit the remaining work in the worktree, run `crtr worktree close`, then rerun `crtr push final`.',
+                        next: 'Commit the remaining work in the worktree, run `crtr node worktree close`, then rerun `crtr push final`.',
                     });
                 }
                 // A RESIDENT node with no subscribers is human-driven and has no one to

package/dist/commands/revive.d.ts

@@ -1,12 +1,2 @@
 import type { LeafDef } from '../core/command.js';
-import type { Fault } from '../core/runtime/fault.js';
-/** --now eligibility for a live, non-busy fault: a daemon-owned AUTO retry
- *  (kick it early instead of waiting out the schedule), or any fault the
- *  canvas dashboard flags "needs you" (`faultNeedsYou`, status-glyph.ts) — the
- *  disposition that otherwise has NO sanctioned recovery verb (issue #115).
- *  Both are scoped to `pi→provider`: refuses a client-owned auto retry
- *  (redialing) already in flight, and refuses any OTHER link — notably a
- *  `daemon→node` wedge fault, which --now can't clear (SIGTERM doesn't touch
- *  the runaway subprocess; see `wedged-child-on-runaway-bash`). */
-export declare function isNowEligibleFault(fault: Fault | null): boolean;
 export declare const reviveLeaf: LeafDef;

package/dist/commands/revive.js

@@ -1,90 +1,42 @@
-// `crtr canvas revive` — explicit node revival.
+// `crtr canvas revive` — mass node recovery.
 //
-// Bypasses the daemon: directly relaunches the broker engine for a node that is
-// done, idle, or dead. Default behavior resumes the saved pi conversation by its
-// absolute session-file path (--session <path>) when that .jsonl still exists,
-// else falls through to a fresh launch. `--fresh` skips the true resume: if the
-// `.jsonl` already exists it CYCLES in place instead (same file, a fresh
-// `crtr-cycle` branch — `resumed:false`), and only starts a genuinely clean
-// session when no `.jsonl` exists yet (also `resumed:false`).
+// Sweeps EVERY disconnected node (engine not running, resumable session) in
+// one shot — the recovery for a reboot / mass-crash / daemon-down-a-while
+// event. It is a two-step gate: run it once to PREVIEW the candidates
+// (nothing is launched), then confirm to actually revive them.
 //
-// `--all` sweeps EVERY disconnected node (engine not running, resumable session)
-// in one shot — the recovery for a reboot / mass-crash / daemon-down-a-while
-// event. It is a two-step gate: run it once to PREVIEW the candidates (nothing is
-// launched), then confirm to actually revive them.
+// Reviving ONE named node is a per-node lifecycle action and lives instead at
+// `crtr node lifecycle revive <id>` (src/commands/node-lifecycle-revive.ts).
 import { defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
-import { reviveNode } from '../core/runtime/revive.js';
 import { listDisconnected, reviveAll } from '../core/runtime/revive-all.js';
-import { waitForBrokerViewSocket } from '../core/runtime/placement.js';
 import { getNode, fullName } from '../core/canvas/index.js';
-import { isPidAlive } from '../core/canvas/pid.js';
-import { readFault } from '../core/runtime/fault.js';
-import { isBusy } from '../core/runtime/busy.js';
-import { faultNeedsYou } from '../core/canvas/status-glyph.js';
-/** --now eligibility for a live, non-busy fault: a daemon-owned AUTO retry
- *  (kick it early instead of waiting out the schedule), or any fault the
- *  canvas dashboard flags "needs you" (`faultNeedsYou`, status-glyph.ts) — the
- *  disposition that otherwise has NO sanctioned recovery verb (issue #115).
- *  Both are scoped to `pi→provider`: refuses a client-owned auto retry
- *  (redialing) already in flight, and refuses any OTHER link — notably a
- *  `daemon→node` wedge fault, which --now can't clear (SIGTERM doesn't touch
- *  the runaway subprocess; see `wedged-child-on-runaway-bash`). */
-export function isNowEligibleFault(fault) {
-    if (fault === null || fault.link !== 'pi→provider')
-        return false;
-    if (faultNeedsYou(fault))
-        return true;
-    return fault.retry.by === 'daemon';
-}
 // ---------------------------------------------------------------------------
-// revive node
+// revive --all
 // ---------------------------------------------------------------------------
 export const reviveLeaf = defineLeaf({
     name: 'revive',
-    description: 'reopen a window for a done/idle/dead/canceled node, or --all disconnected nodes',
-    whenToUse: 'you want to bring a dormant node back yourself — reopen a window for one that is done, idle, dead, or canceled: resume a node you closed with `node lifecycle close`, reopen a finished worker for a follow-up, or restart a crashed one now instead of waiting. It resumes the saved conversation by default, or can restart the node clean. Pass `--all` instead of a node id to bring back EVERY disconnected node at once (engine not running but a saved session intact) — the recovery after a reboot, a killed login/tmux session, a mass crash, or the daemon being down a while. You rarely need this for crashes — the daemon auto-revives those; reach for it to bring a node back on demand, to revive a canceled node the daemon will never touch on its own, or to mass-reconnect survivors after a disconnect event',
+    description: 'mass-reconnect every disconnected node',
+    whenToUse: 'you need to bring back EVERY disconnected node at once (engine not running but a saved session intact) — the recovery after a reboot, a killed login/tmux session, a mass crash, or the daemon being down a while. You rarely need this for an ordinary crash — the daemon auto-revives those. To bring back ONE named node (a follow-up on a finished worker, a canceled node, or an on-demand kick of a hanging one), use `node lifecycle revive <id>` instead',
     help: {
         name: 'canvas revive',
-        summary: 'relaunch a node\'s broker engine (resuming its saved conversation), or --all disconnected nodes',
+        summary: 'mass-reconnect every disconnected node (engine not running, resumable saved session)',
         params: [
-            {
-                kind: 'positional',
-                name: 'node',
-                required: false,
-                constraint: 'Node id to revive. Omit when using --all.',
-            },
             {
                 kind: 'flag',
                 name: 'all',
                 type: 'bool',
                 required: false,
                 default: false,
-                constraint: 'Revive EVERY disconnected node (engine not running, resumable saved session) — excludes done/canceled (terminal-by-choice). Run it once to PREVIEW the candidates; nothing is launched until you confirm. Mutually exclusive with a node id.',
-            },
-            {
-                kind: 'flag',
-                name: 'fresh',
-                type: 'bool',
-                required: false,
-                default: false,
-                constraint: 'When set, do NOT do a true resume. If the node already has a session `.jsonl`, this instead CYCLES it in place — reuses that SAME file, resets the tree leaf, and roots a fresh `crtr-cycle` branch (a clean-context restart that still carries the file\'s history, output `resumed:false`). Only when no `.jsonl` exists yet does this start a genuinely brand-new session (also `resumed:false`). Default (no --fresh): a true resume — replays the existing `.jsonl` as-is (`resumed:true`). Ignored with --all (which always resumes).',
-            },
-            {
-                kind: 'flag',
-                name: 'now',
-                type: 'bool',
-                required: false,
-                default: false,
-                constraint: 'On-demand kick of an active-fault node (parked on a `pi→provider` fault, broker still alive). Its broker pid is alive, so an ordinary revive no-ops (double-launch guard) — --now SIGTERMs the live broker instead, so the daemon\'s crash→grace→resume path brings it back in ~20s. Valid for a live `pi→provider` fault that is either a daemon-owned auto retry (kicks it early), or ANY fault the canvas dashboard flags "needs you" (e.g. exhausted retries, an auth fault you just fixed) — that disposition otherwise has no recovery verb. Mutually exclusive with --all/--fresh.',
+                constraint: 'Required (rejected without it) — confirms this is the graph-wide sweep, not a typo for a single-node revive (that lives at `node lifecycle revive <id>`). Excludes done/canceled (terminal-by-choice). Run it once to PREVIEW the candidates; nothing is launched until you confirm.',
             },
-            // --force is a DELIBERATELY UNDOCUMENTED confirmation gate for --all (hidden
-            // from -h; see FlagParam.hidden). Silas's intent (2026-06-13): a mass revive
-            // can have large, unforeseen consequences, so the agent must NOT be able to
-            // discover a one-shot bypass by reading the schema. The unforced --all path
-            // PREVIEWS the candidates and instructs the agent to double-check with the
-            // USER before re-running; only then, having been told the flag, does it pass
-            // --force. Documenting it here would defeat that gate.
+            // --force is a DELIBERATELY UNDOCUMENTED confirmation gate (hidden from
+            // -h; see FlagParam.hidden). Silas's intent (2026-06-13): a mass revive
+            // can have large, unforeseen consequences, so the agent must NOT be able
+            // to discover a one-shot bypass by reading the schema. The unforced --all
+            // path PREVIEWS the candidates and instructs the agent to double-check
+            // with the USER before re-running; only then, having been told the flag,
+            // does it pass --force. Documenting it here would defeat that gate.
             {
                 kind: 'flag',
                 name: 'force',
@@ -92,135 +44,33 @@ export const reviveLeaf = defineLeaf({
                 required: false,
                 default: false,
                 hidden: true,
-                constraint: 'Confirm a --all sweep (internal gate; see code comment).',
+                constraint: 'Confirm the sweep (internal gate; see code comment).',
             },
         ],
         output: [
-            { name: 'window', type: 'string', required: false, constraint: 'Always null — the revived broker is headless and opens no tmux window. Kept for caller back-compat.' },
-            { name: 'session', type: 'string', required: false, constraint: 'The node\'s last live location session, or null — the headless broker has no tmux session of its own.' },
-            { name: 'resumed', type: 'boolean', required: false, constraint: 'True ONLY for a true resume (the existing `.jsonl` replayed as-is). False for a --fresh revive, whether that landed as an in-place CYCLE (an existing `.jsonl` reused with a fresh `crtr-cycle` branch — pi is still told --session, but this is not a resume) or a genuinely fresh launch (no `.jsonl` existed). Single-node revive only.' },
-            { name: 'ready', type: 'boolean', required: false, constraint: 'True when the revived broker\'s view.sock accepted a connection before return — the node is immediately attachable/drivable. Single-node revive only.' },
-            { name: 'mode', type: 'string', required: false, constraint: '"preview" (the --all candidate list, nothing launched), "revived" (the --all sweep ran), or absent for a single-node revive.' },
-            { name: 'candidates', type: 'string', required: false, constraint: '--all preview: the node ids that WOULD be revived (newline-joined). Empty when none are disconnected.' },
-            { name: 'revived', type: 'string', required: false, constraint: '--all sweep: the node ids whose broker engine was relaunched (newline-joined).' },
-            { name: 'failed', type: 'string', required: false, constraint: '--all sweep: node ids whose relaunch threw, with the error (newline-joined). Absent when none failed.' },
-            { name: 'kicked', type: 'boolean', required: false, constraint: '--now only: true when the hanging node\'s live broker was SIGTERM\'d (the daemon resumes it on the saved session within ~20s). Absent for an ordinary revive.' },
+            { name: 'mode', type: 'string', required: true, constraint: '"preview" (the candidate list, nothing launched) or "revived" (the sweep ran).' },
+            { name: 'candidates', type: 'string', required: false, constraint: 'Preview: the node ids that WOULD be revived (newline-joined). Empty when none are disconnected.' },
+            { name: 'revived', type: 'string', required: false, constraint: 'Sweep: the node ids whose broker engine was relaunched (newline-joined).' },
+            { name: 'failed', type: 'string', required: false, constraint: 'Sweep: node ids whose relaunch threw, with the error (newline-joined). Absent when none failed.' },
         ],
         outputKind: 'object',
         effects: [
-            'Launches the node\'s detached headless broker engine (no tmux window).',
-            'Updates the node\'s canvas record: status=active, intent=null.',
-            'Blocks until the broker\'s view.sock accepts a connection (up to ~30s), so a caller can attach/dial immediately on return.',
-            '--all without confirmation launches NOTHING — it only previews the disconnected candidates.',
+            'Launches the detached headless broker engine (no tmux window) for every disconnected node.',
+            'Updates each revived node\'s canvas record: status=active, intent=null.',
+            'Without --force: launches NOTHING — only previews the disconnected candidates.',
         ],
     },
     run: async (input) => {
-        const all = input['all'] ?? false;
-        const now = input['now'] ?? false;
-        const nodeId = input['node'];
-        if (all) {
-            if (now) {
-                throw new InputError({
-                    error: 'conflicting_args',
-                    message: '`--now` kicks ONE hanging node; it cannot combine with `--all`.',
-                    next: 'Run `crtr canvas revive <node> --now` for the hanging node, or `crtr canvas revive --all` (no --now).',
-                });
-            }
-            if (nodeId !== undefined) {
-                throw new InputError({
-                    error: 'conflicting_args',
-                    message: '`--all` reconnects every disconnected node; do not also pass a node id.',
-                    next: 'Run `crtr canvas revive --all` (no node id), or `crtr canvas revive <node>` for one.',
-                });
-            }
-            return runReviveAll(input);
-        }
-        if (nodeId === undefined) {
+        if (input['all'] !== true) {
             throw new InputError({
                 error: 'missing_parameter',
-                message: 'pass a node id to revive, or `--all` to reconnect every disconnected node.',
-                next: 'Run `crtr canvas revive <node>` or `crtr canvas revive --all`. List nodes with `crtr node inspect list`.',
-            });
-        }
-        const fresh = input['fresh'] ?? false;
-        if (now && fresh) {
-            throw new InputError({
-                error: 'conflicting_args',
-                message: '`--now` kicks a live hanging broker (SIGTERM → daemon resumes the SAVED session); `--fresh` is meaningless there.',
-                next: 'Run `crtr canvas revive <node> --now` (resumes), or `crtr canvas revive <node> --fresh` (no --now) to relaunch clean.',
+                message: '`canvas revive` is the mass-recovery sweep and requires --all.',
+                next: 'Run `crtr canvas revive --all` to reconnect every disconnected node, or `crtr node lifecycle revive <id>` to bring back one named node.',
             });
         }
-        // Validate the node exists before attempting revival.
-        const meta = getNode(nodeId);
-        if (meta === null) {
-            throw new InputError({
-                error: 'not_found',
-                message: `no node: ${nodeId}`,
-                next: 'List nodes with `crtr node inspect list`.',
-            });
-        }
-        // --now: the on-demand kick for an active fault. The broker is ALIVE (so
-        // reviveNode would no-op the double-launch guard) — SIGTERM it so the daemon's
-        // ordinary crash→grace→resume path recovers it on the saved session, the same
-        // thing the daemon does at the auto-recovery grace, just on demand. Gated on
-        // a live pid and an eligible pi→provider fault (`isNowEligibleFault` above) so
-        // it can't be used to nuke a healthy node.
-        if (now) {
-            const pid = meta.pi_pid;
-            const stall = readFault(nodeId);
-            if (pid == null || !isPidAlive(pid)) {
-                throw new InputError({
-                    error: 'not_hanging',
-                    message: `${nodeId} has no live broker — nothing to kick. --now is for a HANGING node (live broker parked on an active fault).`,
-                    next: 'Revive a dormant node with `crtr canvas revive ' + nodeId + '` (no --now).',
-                });
-            }
-            if (!isNowEligibleFault(stall)) {
-                throw new InputError({
-                    error: 'not_hanging',
-                    message: `${nodeId} is live but has no pi→provider fault eligible for --now (either healthy, or a client-owned retry / non-provider fault already being handled elsewhere) — --now refuses to SIGTERM a node that isn't stuck on a kickable provider fault.`,
-                    next: 'Use --now only on a node the canvas shows as hanging (⚠) with a `pi→provider` fault. For a routine relaunch, omit --now.',
-                });
-            }
-            // 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({
-                    error: 'busy',
-                    message: `${nodeId} is mid-turn right now (busy) — --now refuses to SIGTERM a working engine; it has recovered on its own.`,
-                    next: 'Re-check the canvas — if it\'s no longer marked hanging (⚠), nothing to do.',
-                });
-            }
-            try {
-                process.kill(pid, 'SIGTERM');
-            }
-            catch {
-                /* best-effort: the broker may have just died; the daemon owns the resume */
-            }
-            return {
-                window: null,
-                session: meta.tmux_session ?? null,
-                kicked: true,
-                message: `Sent SIGTERM to ${fullName(meta)} (${nodeId}, pid ${pid}). The daemon will resume it on the saved session within ~20s (crash→grace→resume).`,
-            };
-        }
-        const result = reviveNode(nodeId, { resume: !fresh });
-        // Revive returns once the broker process is launched, which can be seconds
-        // before its view.sock listens. Callers (attach, the web shell's Wake) dial
-        // immediately on return, so block here until the socket accepts.
-        const ready = await waitForBrokerViewSocket(nodeId, result.launch?.exited);
-        return {
-            window: result.window ?? undefined,
-            session: result.session,
-            resumed: result.resumed,
-            ready,
-        };
+        return runReviveAll(input);
     },
 });
-// ---------------------------------------------------------------------------
-// revive --all
-// ---------------------------------------------------------------------------
 /** One line per candidate: `<id>  <full name>  [<status>]`. */
 function describe(ids) {
     return ids

package/dist/core/__tests__/kickoff.test.js

@@ -100,8 +100,8 @@ test('a fresh revive is pointed at its subscriptions\' on-disk report history (c
     assert.ok(!msg.includes(older), 'absolute report paths not rendered');
     assert.ok(!msg.includes(newer), 'absolute report paths not rendered');
     assert.ok(/canvas history read <ref>/.test(msg), 'points at one-report expansion');
-    assert.ok(/canvas history show <node-id> --type report/.test(msg), 'points at full per-node expansion');
-    assert.ok(/canvas history show <node-id> --type inbox/.test(msg), 'points at the cursor-independent full-history replay');
+    assert.ok(/node inspect artifacts <node-id> --type report/.test(msg), 'points at full per-node expansion');
+    assert.ok(/node inspect artifacts <node-id> --type inbox/.test(msg), 'points at the cursor-independent full-history replay');
 });
 test('buildReviveKickoff is pure — building twice eats nothing', () => {
     const id = 'n2';

package/dist/core/canvas/boot.js

@@ -10,7 +10,7 @@
 // broker it once named is long gone. Left unchecked this fools BOTH the
 // daemon's own liveness poll (crtrd.ts) and reviveNode's double-launch guard
 // (revive.ts) into believing a dead broker is still running — the node then
-// stays permanently unrevivable until a human runs `canvas revive --fresh`.
+// stays permanently unrevivable until a human runs `node lifecycle revive --fresh`.
 //
 // The signal (primary): the Linux kernel's per-boot identity at
 // `/proc/sys/kernel/random/boot_id` — a fresh random UUID minted on every

package/dist/core/canvas/browse/app.js

@@ -80,12 +80,12 @@ export async function runBrowse(opts = {}) {
     // Safety net: an uncaught throw in the (un-unit-tested) keystroke path must
     // never strand the tty in raw + alt-screen + hidden-cursor.
     process.once('exit', cleanup);
-    /** On-demand kick of a hanging node: shell `canvas revive <id> --now` (which
-     *  SIGTERMs the live broker — the daemon resumes it). Synchronous + quiet
-     *  (stdio ignored) so it never takes over the TUI; best-effort. */
+    /** On-demand kick of a hanging node: shell `node lifecycle revive <id> --now`
+     *  (which SIGTERMs the live broker — the daemon resumes it). Synchronous +
+     *  quiet (stdio ignored) so it never takes over the TUI; best-effort. */
     const reviveNow = (id) => {
         try {
-            execFileSync('crtr', ['canvas', 'revive', id, '--now'], { stdio: 'ignore' });
+            execFileSync('crtr', ['node', 'lifecycle', 'revive', id, '--now'], { stdio: 'ignore' });
         }
         catch {
             /* best-effort — the SIGTERM is what matters; the daemon owns the resume */
@@ -471,8 +471,8 @@ export async function runBrowse(opts = {}) {
         }
         // Revive now (on-demand kick): for a HANGING node, SIGTERM the live broker so
         // the daemon's crash→grace→resume path brings it back in ~20s instead of
-        // waiting out the 5-min auto-revive grace. Shells `canvas revive <id> --now`
-        // (browse goes through commands, never touching the runtime directly). 'k' is
+        // waiting out the 5-min auto-revive grace. Shells `node lifecycle revive <id>
+        // --now` (browse goes through commands, never touching the runtime directly). 'k' is
         // vim-up here, so the kick is on SHIFT-K.
         if (input === 'K') {
             if (row !== undefined) {

package/dist/core/canvas/browse/render.js

@@ -472,7 +472,7 @@ export function renderFrame(state, size, caps = { color: false, color256: false
     }
     else {
         // When the cursor row has an active fault, lead the footer with the on-demand kick
-        // hint (K shells `canvas revive <id> --now` — immediate revive instead of
+        // hint (K shells `node lifecycle revive <id> --now` — immediate revive instead of
         // waiting for the daemon's retry schedule).
         const selRow = state.visible[state.cursor];
         const cursorRow = selRow !== undefined ? state.tree.nodes.get(selRow.id)?.row : undefined;

package/dist/core/canvas/status-glyph.d.ts

@@ -26,7 +26,7 @@ export declare function resolveNodeVisual(status: NodeStatus, opts: {
 /** True for exactly the fault dispositions `faultDispositionText` renders as
  *  "needs you" — nothing (sdk/daemon/client) is auto-driving recovery, so the
  *  dashboard flags the node for the human. Exported so a recovery verb (e.g.
- *  `canvas revive --now`, src/commands/revive.ts) can gate on the SAME
+ *  `node lifecycle revive --now`, src/commands/node-lifecycle-revive.ts) can gate on the SAME
  *  predicate the dashboard advertises instead of drifting out of sync with it
  *  (issue #115 — `--now` used to reject exactly the nodes shown as "needs you"). */
 export declare function faultNeedsYou(fault: Pick<Fault, 'retry'>): boolean;

package/dist/core/canvas/status-glyph.js

@@ -73,7 +73,7 @@ function retryCountdown(iso, now) {
 /** True for exactly the fault dispositions `faultDispositionText` renders as
  *  "needs you" — nothing (sdk/daemon/client) is auto-driving recovery, so the
  *  dashboard flags the node for the human. Exported so a recovery verb (e.g.
- *  `canvas revive --now`, src/commands/revive.ts) can gate on the SAME
+ *  `node lifecycle revive --now`, src/commands/node-lifecycle-revive.ts) can gate on the SAME
  *  predicate the dashboard advertises instead of drifting out of sync with it
  *  (issue #115 — `--now` used to reject exactly the nodes shown as "needs you"). */
 export function faultNeedsYou(fault) {