@crouton-kit/crouter 0.3.33 → 0.3.35

package/dist/core/resolver.d.ts

@@ -1,4 +1,5 @@
 import type { InstalledMarketplace, InstalledPlugin, Scope } from '../types.js';
+export declare function listInstalledPluginsInRoot(scope: Scope, scopeRootPath: string): InstalledPlugin[];
 export declare function listInstalledPlugins(scope: Scope): InstalledPlugin[];
 export declare function listAllPlugins(): InstalledPlugin[];
 export declare function findPluginByName(name: string, scope?: Scope): InstalledPlugin | null;

package/dist/core/resolver.js

@@ -1,40 +1,47 @@
 import { join } from 'node:path';
+import { CONFIG_FILE } from '../types.js';
 import { readConfig } from './config.js';
-import { listDirs, pathExists } from './fs-utils.js';
+import { listDirs, pathExists, readJsonIfExists } from './fs-utils.js';
 import { readMarketplaceManifest, readPluginManifest } from './manifest.js';
 import { InputError } from './io.js';
-import { marketplacesDir, pluginsDir, projectScopeRoot, userScopeRoot, } from './scope.js';
-export function listInstalledPlugins(scope) {
-    // The builtin scope has no scopeRoot, so pluginsDir('builtin') is null and
-    // this returns [] — builtin content is the memory substrate, not plugins.
-    const dir = pluginsDir(scope);
-    if (!dir || !pathExists(dir))
+import { marketplacesDir, projectScopeRoot, scopeRoot, userScopeRoot, } from './scope.js';
+function pluginConfigForRoot(root) {
+    const cfg = readJsonIfExists(join(root, CONFIG_FILE));
+    return cfg && cfg.plugins && typeof cfg.plugins === 'object' ? cfg.plugins : {};
+}
+export function listInstalledPluginsInRoot(scope, scopeRootPath) {
+    const dir = join(scopeRootPath, 'plugins');
+    if (!pathExists(dir))
         return [];
-    const cfg = readConfig(scope);
+    const cfg = pluginConfigForRoot(scopeRootPath);
     const out = [];
     for (const name of listDirs(dir)) {
         const root = join(dir, name);
         const manifest = readPluginManifest(root);
         if (!manifest)
             continue;
-        const entry = cfg.plugins[name];
-        let version;
-        if (entry && entry.version !== undefined)
-            version = entry.version;
-        else if (manifest.version !== undefined)
-            version = manifest.version;
+        const entry = cfg[name];
+        const version = typeof entry?.version === 'string' ? entry.version : manifest.version;
         out.push({
             name,
             scope,
             root,
             manifest,
-            enabled: entry ? entry.enabled : true,
-            sourceMarketplace: entry ? entry.source_marketplace : undefined,
+            enabled: typeof entry?.enabled === 'boolean' ? entry.enabled : true,
+            sourceMarketplace: typeof entry?.source_marketplace === 'string' ? entry.source_marketplace : undefined,
             version,
         });
     }
     return out;
 }
+export function listInstalledPlugins(scope) {
+    // The builtin scope has no scopeRoot, so this returns [] — builtin content is
+    // the memory substrate, not plugins.
+    const root = scopeRoot(scope);
+    if (!root)
+        return [];
+    return listInstalledPluginsInRoot(scope, root);
+}
 export function listAllPlugins() {
     const scopes = [];
     if (projectScopeRoot())

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

@@ -1,4 +1,4 @@
-import { type WakeKind, type Wakeup } from '../canvas/index.js';
+import { type Trigger } from '../canvas/index.js';
 /** The `<project_context>` block for the files discovered from `cwd`, plus the
  *  cwd/git environment snapshot that now rides at the end of the wrapper.
  *  Always emits the wrapper because the environment snapshot is always present
@@ -32,26 +32,27 @@ export declare function buildGraphMap(nodeId: string): string;
  *  contradiction with no referent). Also prepended to a fork's kickoff prompt in
  *  spawn.ts. Exported for testing. */
 export declare function buildIdentityAssertion(nodeId: string): string;
-/** Why a node woke or was born, as carried from the fired wakeup row to the
+/** Why a node woke or was born, as carried from the fired trigger row to the
  *  injection seam. `ownerName` is the armer's resolved display name when it
  *  still exists (a reaped cron's armer renders as a bare id, never crashes). */
 export interface WakeOrigin {
-    /** The firing kind. The <crtr-wake> block is rendered for 'spawn' (birth) and
-     *  'bare' (revive); 'noted'/'deadline' self-mark at the message seam instead. */
-    kind: WakeKind;
-    /** The armer node id (wakeups.owner_id), or null if somehow absent. */
+    /** Which enactment birthed/woke the node — the only two action_modes that
+     *  ever route through this provenance block; inbox_message/deadline_message
+     *  self-mark via their inbox label at the message seam instead. */
+    kind: 'fresh_revive' | 'node_birth';
+    /** The armer node id (triggers.owner_id), or null if somehow absent. */
     ownerId: string | null;
     /** The armer's display name, resolved if it still exists. */
     ownerName?: string;
-    /** wakeups.created — when the wake was armed (ISO). */
+    /** triggers.created — when the trigger was armed (ISO). */
     armedAt: string;
-    /** wakeups.recur JSON when recurring, else null/undefined for a one-shot. */
+    /** triggers.recur JSON when recurring, else null/undefined for a one-shot. */
     recur?: string | null;
 }
-/** Build a WakeOrigin from a fired wakeup row, resolving the armer's display
+/** Build a WakeOrigin from a fired trigger row, resolving the armer's display
  *  name if the node still exists. The daemon calls this at fire time for the
  *  bare-revive and spawn-birth seams. */
-export declare function wakeOriginFrom(w: Wakeup): WakeOrigin;
+export declare function wakeOriginFrom(t: Trigger): WakeOrigin;
 /** The <crtr-wake> provenance block — load-bearing agent-facing prose read by
  *  every wake-born or wake-woken node. Decision-first: it leads with the fact a
  *  TIMER (not a message/event) caused this turn, names the wake kind, surfaces

package/dist/core/runtime/bearings.js

@@ -332,17 +332,17 @@ export function buildIdentityAssertion(nodeId) {
     }
     return lines.join('\n');
 }
-/** Build a WakeOrigin from a fired wakeup row, resolving the armer's display
+/** Build a WakeOrigin from a fired trigger row, resolving the armer's display
  *  name if the node still exists. The daemon calls this at fire time for the
  *  bare-revive and spawn-birth seams. */
-export function wakeOriginFrom(w) {
-    const owner = w.owner_id != null ? getNode(w.owner_id) : null;
+export function wakeOriginFrom(t) {
+    const owner = t.owner_id != null ? getNode(t.owner_id) : null;
     return {
-        kind: w.kind,
-        ownerId: w.owner_id ?? null,
+        kind: t.action_mode === 'node_birth' ? 'node_birth' : 'fresh_revive',
+        ownerId: t.owner_id ?? null,
         ownerName: owner !== null ? fullName(owner) : undefined,
-        armedAt: w.created,
-        recur: w.recur,
+        armedAt: t.created,
+        recur: t.recur,
     };
 }
 /** The armer rendered for prose, ROLE-explicit so a newborn never mistakes the
@@ -372,7 +372,7 @@ export function buildWakeBearings(origin) {
     const recurring = origin.recur !== null && origin.recur !== undefined && origin.recur !== '';
     const cadence = recurring ? cadenceDisplay(origin.recur) : null;
     let body;
-    if (origin.kind === 'spawn') {
+    if (origin.kind === 'node_birth') {
         const armer = armerPhrase(origin);
         body = recurring
             ? `You were BORN by a scheduled wake, not spawned on demand — a recurring spawn-cron armed by ` +

package/dist/core/runtime/broker-protocol.d.ts

@@ -315,7 +315,7 @@ export interface WelcomeFrame {
     pending_dialog?: RpcExtensionUIRequest | null;
     /** The pi agent dir (`~/.pi/agent`) from the broker's process — so the viewer
      *  can construct an AuthStorage/ModelRegistry pointing at the SAME auth.json.
-     *  crtr attach is tmux-local only: broker + viewer share a filesystem. */
+     *  crtr surface attach is tmux-local only: broker + viewer share a filesystem. */
     agentDir?: string;
 }
 export interface ControlChangedFrame {
@@ -552,7 +552,7 @@ export declare const BROKER_READ_CAPS: FrameDecoderCaps;
  *  arriving in ~64 KiB socket chunks costs O(frame) total instead of O(frame ×
  *  chunks). The old `buf += chunk; buf.indexOf('\n')` shape flattened + re-walked
  *  the whole carry per chunk: a 16 MiB welcome snapshot cost ~250 ms of
- *  event-loop stall in `crtr attach` (typing lag) and the same again in the
+ *  event-loop stall in `crtr surface attach` (typing lag) and the same again in the
  *  broker; this shape decodes it in ~13 ms.
  *
  *  A `StringDecoder` decodes incoming Buffer chunks: an incomplete trailing

package/dist/core/runtime/broker-protocol.js

@@ -1,7 +1,7 @@
 // broker-protocol.ts — the client↔broker wire protocol for the headless node
 // Surface (design §5.2). Pure types + a newline-delimited JSON codec; no I/O, no
 // SDK construction. Consumed by the broker (src/core/runtime/broker.ts) and, in
-// Phase 4, by the `crtr attach` terminal client and the `crtr web` bridge.
+// Phase 4, by the `crtr surface attach` terminal client and the surface web bridge.
 //
 // The transport is one unix socket per node (`nodeDir(id)/view.sock`) speaking
 // newline-delimited JSON frames. Live engine events are relayed VERBATIM — the
@@ -88,7 +88,7 @@ export const BROKER_READ_CAPS = {
  *  arriving in ~64 KiB socket chunks costs O(frame) total instead of O(frame ×
  *  chunks). The old `buf += chunk; buf.indexOf('\n')` shape flattened + re-walked
  *  the whole carry per chunk: a 16 MiB welcome snapshot cost ~250 ms of
- *  event-loop stall in `crtr attach` (typing lag) and the same again in the
+ *  event-loop stall in `crtr surface attach` (typing lag) and the same again in the
  *  broker; this shape decodes it in ~13 ms.
  *
  *  A `StringDecoder` decodes incoming Buffer chunks: an incomplete trailing

package/dist/core/runtime/close.js

@@ -1,4 +1,4 @@
-// close.ts — the "close this node + its subtree" action behind `crtr node close`.
+// close.ts — the "close this node + its subtree" action behind `crtr node lifecycle close`.
 //
 // Closing a node tears down the focused node and every descendant it
 // EXCLUSIVELY owns, walking DOWN the subscribes_to spine (subscriptionsOf = a
@@ -177,7 +177,7 @@ export function closeNode(rootId, opts = {}) {
             }
             // 4) Wake any SURVIVING manager subscribed to this node — the doctrine wake.
             //    A node going dormant trusts the runtime to wake it on a child's
-            //    terminal outcome; D-1 found that `node close` notified ONLY the closed
+            //    terminal outcome; D-1 found that `node lifecycle close` notified ONLY the closed
             //    node itself, never its subscribers, so a parent that delegated then
             //    just stopped hangs forever when its child is closed out from under it.
             //    Only the close ROOT can have a surviving subscriber (closingSet adds a

package/dist/core/runtime/kickoff.js

@@ -268,7 +268,7 @@ export function buildReviveKickoff(meta, bearings, wakeReason) {
             'directly with the user, so stay available and continue the conversation when they ' +
             'write back.');
     // Persona-transition catch-up. If the node's mode/lifecycle was changed
-    // EXTERNALLY while it was dormant (e.g. a human ran `crtr node lifecycle` /
+    // EXTERNALLY while it was dormant (e.g. a human ran `crtr node config --lifecycle` /
     // `node promote --node` on it), it never saw the turn_end injector. drainBearings
     // captured the guidance for its new persona and committed the ack (the second
     // and only other delivery site); we just surface it. A clean fresh revive has

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

@@ -77,8 +77,12 @@ export interface PiInvocation {
  *    — pi COPIES that conversation into a NEW session for this node, then `prompt`
  *    is delivered as the next message. One-shot at birth: the node thereafter
  *    captures its OWN pi_session_file and revives by `--session` like any other.
- *  - revive idle/done: pass `resumeSessionPath` (absolute .jsonl path, preferred)
- *    or `resumeSessionId` (bare uuid fallback) to `--session` (keeps conversation).
+ *  - revive idle/done: pass `resumeSessionPath` (absolute .jsonl path) to
+ *    `--session` (keeps conversation). `resumeSessionId` (a bare uuid) is
+ *    accepted here too, but revive.ts's `resumeArgs` never produces one —
+ *    `headlessBrokerHost`'s preflight (host.ts) fatally rejects a bare
+ *    `--session` id before ever spawning the broker, so a real revive only
+ *    ever resumes by path (or falls through to fresh when no path exists).
  *  - refresh-yield: fresh again (no resume) — the node re-reads its roadmap. */
 export declare function buildPiArgv(meta: NodeMeta, opts?: {
     prompt?: string;
@@ -104,7 +108,9 @@ export interface BrokerSdkConfig {
     forkFrom?: string;
     /** Resume by absolute `.jsonl` path (preferred — `SessionManager.open`). */
     resumeSessionPath?: string;
-    /** Resume by bare session uuid (legacy fallback). */
+    /** Resume by bare session uuid. Accepted by the generic builder, but no live
+     *  caller sets it — revive resumes by absolute path only, and the broker
+     *  preflight rejects a bare `--session`. */
     resumeSessionId?: string;
     /** Model spec, e.g. `anthropic/sonnet` (`--model`). */
     model?: string;

package/dist/core/runtime/launch.js

@@ -2,8 +2,9 @@
 //
 // pi-only. No claude branch — we are a super-opinionated system. A node's
 // LaunchSpec (persisted in meta.json) is the canonical recipe the daemon
-// replays to revive it faithfully: `--session <id>` to wake a done/idle node
-// (keeps its conversation), or fresh (against the context dir) for a refresh-yield.
+// replays to revive it faithfully: `--session <path>` (the saved conversation's
+// absolute .jsonl) to wake a done/idle node, or fresh (against the context dir)
+// for a refresh-yield.
 // The spec is rewritten on every polymorph (base→orchestrator) so a node
 // always comes back as its *current* self.
 import { existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
@@ -249,8 +250,12 @@ function writeSystemPromptFile(nodeId, prompt) {
  *    — pi COPIES that conversation into a NEW session for this node, then `prompt`
  *    is delivered as the next message. One-shot at birth: the node thereafter
  *    captures its OWN pi_session_file and revives by `--session` like any other.
- *  - revive idle/done: pass `resumeSessionPath` (absolute .jsonl path, preferred)
- *    or `resumeSessionId` (bare uuid fallback) to `--session` (keeps conversation).
+ *  - revive idle/done: pass `resumeSessionPath` (absolute .jsonl path) to
+ *    `--session` (keeps conversation). `resumeSessionId` (a bare uuid) is
+ *    accepted here too, but revive.ts's `resumeArgs` never produces one —
+ *    `headlessBrokerHost`'s preflight (host.ts) fatally rejects a bare
+ *    `--session` id before ever spawning the broker, so a real revive only
+ *    ever resumes by path (or falls through to fresh when no path exists).
  *  - refresh-yield: fresh again (no resume) — the node re-reads its roadmap. */
 export function buildPiArgv(meta, opts = {}) {
     const spec = meta.launch;
@@ -264,8 +269,10 @@ export function buildPiArgv(meta, opts = {}) {
     // absolute FILE path when present: pi resolves a bare id cwd-relative first
     // and shows a cross-project "Fork? [y/N]" prompt when the revive cwd differs
     // from the session's creation cwd, whereas a path (contains `/` or ends
-    // `.jsonl`) is opened directly — immune to any cwd discrepancy. The bare uuid
-    // is the fallback for older nodes booted before pi_session_file was captured.
+    // `.jsonl`) is opened directly — immune to any cwd discrepancy. In practice
+    // revive always passes the absolute path: a resume happens only when the saved
+    // `.jsonl` exists (resumeArgs), and the broker preflight rejects a bare id
+    // outright, so `resumeSessionId` is a generic builder param no live caller sets.
     // `--fork <path|id>` is the spawn-time branch: pi copies the source session
     // into a fresh one for this node (the source is untouched), then delivers the
     // kickoff prompt as the next message. Mutually exclusive with `--session`
@@ -328,9 +335,10 @@ export function piInvocationToSdkConfig(inv) {
                 break;
             case '--session': {
                 const v = argv[++i];
-                // A path (contains `/` or ends `.jsonl`) resumes via SessionManager.open;
-                // a bare uuid is the legacy fallback. Same classification buildPiArgv
-                // documents (path preferred, immune to cwd discrepancy).
+                // A path (contains `/` or ends `.jsonl`) resumes via SessionManager.open.
+                // A bare uuid is classified here for completeness but is rejected by the
+                // broker preflight and never produced by revive — the live path is always
+                // the absolute path. Same classification buildPiArgv documents.
                 if (v.includes('/') || v.endsWith('.jsonl'))
                     cfg.resumeSessionPath = v;
                 else

package/dist/core/runtime/lifecycle.js

@@ -35,7 +35,7 @@
 // row UPDATE directly via openDb — the one sanctioned exception to "only
 // canvas.ts touches the db" (see canvas/CLAUDE.md), exactly as db.ts's backfill
 // is the sanctioned exception for a data migration.
-import { openDb, getNode, cancelWakesFor, cancelSelfAlarms } from '../canvas/index.js';
+import { openDb, getNode, cancelTriggersFor, cancelSelfAlarms } from '../canvas/index.js';
 const ANY = '*';
 /** The supervised statuses — a live node the daemon watches. */
 const LIVE = ['active', 'idle'];
@@ -88,19 +88,19 @@ export function transition(nodeId, event) {
     else if (writeIntent) {
         db.prepare('UPDATE nodes SET intent = ? WHERE node_id = ?').run(spec.intent ?? null, nodeId);
     }
-    // Wakeups cleanup — writes a DIFFERENT table (wakeups) AFTER the atomic
+    // Triggers cleanup — writes a DIFFERENT table (triggers) AFTER the atomic
     // status/intent write above, so the single-(status,intent)-writer rule holds.
-    // Event-gated; exactly ONE delegated wakeups helper per event, never inline
-    // wakeups SQL here (design §6.7 / D2 / D6, Q1/Q2):
-    //   cancel   → cancelWakesFor: reap node-anchored AND owner-armed detached
-    //              wakes this node armed (ruling A) — covers both cancel sites
+    // Event-gated; exactly ONE delegated triggers helper per event, never inline
+    // triggers SQL here (design §6.7 / D2 / D6, Q1/Q2):
+    //   cancel   → cancelTriggersFor: reap node-anchored AND owner-armed detached
+    //              triggers this node armed (ruling A) — covers both cancel sites
     //              uniformly (close cascade · reapDescendants).
     //   finalize → cancelSelfAlarms: clear this node's one-shot self-alarms only;
     //              node-anchored declarative crons SURVIVE a finishing instance (Q1).
     //   crash    → NOTHING. A fault is not a deliberate end-of-waiting; self-alarms
     //              and crons MUST survive instance death (D2 / Invariant E / AC-R3).
     if (event === 'cancel')
-        cancelWakesFor(nodeId);
+        cancelTriggersFor(nodeId);
     else if (event === 'finalize')
         cancelSelfAlarms(nodeId);
     return getNode(nodeId);

package/dist/core/runtime/model-swap.js

@@ -1,4 +1,4 @@
-// model-swap.ts — the engine behind `crtr node model`: swap a node's model
+// model-swap.ts — the engine behind `crtr node config`: swap a node's model
 // (and thus its provider) WITHOUT attaching a viewer, persisting the choice so
 // it survives revives. Two paths, chosen on broker liveness:
 //

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

@@ -51,21 +51,21 @@ export interface FocusResult {
     inPlace: boolean;
     revived: boolean;
 }
-/** Env for a `crtr attach` VIEWER pane (the focus split, the spawn viewer
+/** Env for a `crtr surface attach` VIEWER pane (the focus split, the spawn viewer
  *  window, AND recycle's re-attach respawn): propagate CRTR_HOME so the viewer
  *  resolves the SAME canvas home — and thus the right view.sock — under a
  *  non-default override; otherwise an empty env (the pane inherits the tmux
  *  server env, like every other crtr chrome pane). One helper so the viewer-pane
  *  sites can't drift. */
 export declare function viewerSplitEnv(): Record<string, string>;
-/** Register a `crtr attach` VIEWER pane as the node's one viewer focus row.
+/** Register a `crtr surface attach` VIEWER pane as the node's one viewer focus row.
  *  UNIQUE(node_id) ⇒ one viewer per node: returns
  *  the existing row (no insert) when the pane or the node is already registered.
  *  `window` is accepted for the call contract (spawn passes it) but not stored —
  *  the focuses table keys on pane + session only. The attach client self-tags the
  *  pane `@crtr_node` on connect, so `nodeInPane` resolves it either way. */
 export declare function registerViewerFocus(nodeId: string, pane: string, session: string | null, window: string | null): FocusRow | null;
-/** Open a `crtr attach` VIEWER for `nodeId` and register its viewer focus row —
+/** Open a surface-attach viewer for `nodeId` and register its viewer focus row —
  *  the shared opener used by `focus` (a split beside the caller) and by a --root
  *  spawn (a fresh window in the caller's current session). Wraps `ensureSession`
  *  + `openNodeWindow`/`splitWindow` + `registerViewerFocus`. The attach client
@@ -92,9 +92,9 @@ export declare function focus(nodeId: string, opts: {
  *  and drop its registry row. Best-effort tmux; the DB write always lands. No-op
  *  when the node has no viewer. */
 export declare function tearDownNode(nodeId: string): void;
-/** Detach a node from the foreground (the `node lifecycle --detach` / Alt+C → D
+/** Detach a node from the foreground (the `node lifecycle demote --detach` / Alt+C → D
  *  half). Every node is a headless broker — the only thing on screen is its
- *  `crtr attach` VIEWER pane — so "detach" means STOP FOREGROUNDING it: close the
+ *  surface-attach viewer pane — so "detach" means STOP FOREGROUNDING it: close the
  *  viewer pane (and drop its row) and leave the broker engine running untouched,
  *  reconnectable by a later `focus`. `pane` is the authoritative pane the caller
  *  acts on (the Alt+C menu's `#{pane_id}`); falls back to the node's registered

package/dist/core/runtime/placement.js

@@ -2,7 +2,7 @@
 //
 // After the broker-is-the-host cut the engine NEVER lives in a tmux pane: every
 // node is a detached `headlessBrokerHost` process that binds `view.sock`. A tmux
-// pane is only a `crtr attach` VIEWER of that broker, exactly like a web tab. So
+// pane is only a surface-attach viewer of that broker, exactly like a web tab. So
 // the whole engine-in-pane placement machinery (hot-swap, resume-into-focus,
 // backstage relocation, remain-on-exit freeze, spread, node-row reconcile) is
 // gone. What remains is:
@@ -40,7 +40,7 @@ import { isPidAlive } from '../canvas/pid.js';
 // `selectLayout` are FRESH minimal viewer-chrome helpers (not the deleted
 // engine-in-pane `breakPaneToSession`): `canvas tmux-spread` breaks the caller's
 // viewer pane into its own window and tiles sibling viewers beside it.
-// `piCommand` + `paneCurrentPath` are KEPT: the sessionless `crtr view` system
+// `piCommand` + `paneCurrentPath` are KEPT: the sessionless surface-view system
 // (view-cycle.ts / view-run.ts) builds its pane commands with them, and the §5.1
 // import-lint forbids those commands importing tmux.ts directly — they must reach
 // the driver through placement. (They are NOT engine-in-pane; the design's
@@ -185,7 +185,7 @@ export async function waitForBrokerViewSocket(nodeId, exited) {
 function newFocusId() {
     return `f-${newNodeId()}`;
 }
-/** Env for a `crtr attach` VIEWER pane (the focus split, the spawn viewer
+/** Env for a `crtr surface attach` VIEWER pane (the focus split, the spawn viewer
  *  window, AND recycle's re-attach respawn): propagate CRTR_HOME so the viewer
  *  resolves the SAME canvas home — and thus the right view.sock — under a
  *  non-default override; otherwise an empty env (the pane inherits the tmux
@@ -195,7 +195,7 @@ export function viewerSplitEnv() {
     const crtrHome = process.env['CRTR_HOME'];
     return crtrHome !== undefined ? { CRTR_HOME: crtrHome } : {};
 }
-/** Register a `crtr attach` VIEWER pane as the node's one viewer focus row.
+/** Register a `crtr surface attach` VIEWER pane as the node's one viewer focus row.
  *  UNIQUE(node_id) ⇒ one viewer per node: returns
  *  the existing row (no insert) when the pane or the node is already registered.
  *  `window` is accepted for the call contract (spawn passes it) but not stored —
@@ -213,7 +213,7 @@ export function registerViewerFocus(nodeId, pane, session, window) {
     openFocusRow(focusId, pane, session, nodeId);
     return getFocusById(focusId);
 }
-/** Open a `crtr attach` VIEWER for `nodeId` and register its viewer focus row —
+/** Open a surface-attach viewer for `nodeId` and register its viewer focus row —
  *  the shared opener used by `focus` (a split beside the caller) and by a --root
  *  spawn (a fresh window in the caller's current session). Wraps `ensureSession`
  *  + `openNodeWindow`/`splitWindow` + `registerViewerFocus`. The attach client
@@ -225,7 +225,7 @@ export function registerViewerFocus(nodeId, pane, session, window) {
  *    - `besidePane` → a SPLIT beside that pane in its own session (the focus
  *      open-beside-the-caller path); `session` is then only a fallback. */
 export function openViewerWindow(nodeId, session, opts = {}) {
-    const command = `crtr attach to ${nodeId}`;
+    const command = `crtr surface attach to ${nodeId}`;
     const env = viewerSplitEnv();
     const cwd = opts.cwd ?? process.cwd();
     let pane;
@@ -255,7 +255,7 @@ export function openViewerWindow(nodeId, session, opts = {}) {
 // ---------------------------------------------------------------------------
 /** Bring a node's ONE viewer pane forefront (§A.4). Every node is a detached
  *  broker, so there is no engine pane to swap into the caller's viewport — focus
- *  instead ensures the node's single `crtr attach` viewer is on screen beside (or
+ *  instead ensures the node's single surface-attach viewer is on screen beside (or
  *  navigated to) the caller:
  *    (a) ensure the broker ENGINE is alive (idempotent injected reviver) and its
  *        view.sock is ACCEPTING (closes the cold-start race against attach's
@@ -324,7 +324,7 @@ export async function focus(nodeId, opts) {
     // (c) Reuse / move the node's one live viewer — but ONLY a pane that still
     //     carries THIS node's `@crtr_node` tag. `paneExists` is not enough: the
     //     front-door root registers the user's own terminal as its viewer pane and
-    //     runs `crtr attach` inline; on a clean detach the pane returns to the
+    //     runs `crtr surface attach` inline; on a clean detach the pane returns to the
     //     user's shell (attach clears the tag) yet the pane — and the row — survive,
     //     and a reused pane carries some OTHER node's tag. Navigating to / closing
     //     such a pane would strand the user on (or kill) their shell. So verify the
@@ -379,9 +379,9 @@ export function tearDownNode(nodeId) {
         closePane(f.pane);
     closeFocusRow(f.focus_id);
 }
-/** Detach a node from the foreground (the `node lifecycle --detach` / Alt+C → D
+/** Detach a node from the foreground (the `node lifecycle demote --detach` / Alt+C → D
  *  half). Every node is a headless broker — the only thing on screen is its
- *  `crtr attach` VIEWER pane — so "detach" means STOP FOREGROUNDING it: close the
+ *  surface-attach viewer pane — so "detach" means STOP FOREGROUNDING it: close the
  *  viewer pane (and drop its row) and leave the broker engine running untouched,
  *  reconnectable by a later `focus`. `pane` is the authoritative pane the caller
  *  acts on (the Alt+C menu's `#{pane_id}`); falls back to the node's registered

package/dist/core/runtime/recycle.js

@@ -1,4 +1,4 @@
-// recycle.ts — the "finalize + reboot this pane" action behind `crtr node recycle`.
+// recycle.ts — the "finalize + reboot this pane" action behind `crtr node lifecycle recycle`.
 //
 // Recycle FINALIZES the agent occupying a tmux pane and recycles that pane for
 // fresh work, in three steps:
@@ -8,7 +8,7 @@
 //   2. Close    — tear the agent's broker engine down (the pane is only a viewer).
 //   3. Recycle  — boot a fresh resident broker root the pane re-attaches to.
 //
-// NOT to be confused with `node demote` (flip-to-terminal IN PLACE, which keeps
+// NOT to be confused with `node lifecycle demote` (flip-to-terminal IN PLACE, which keeps
 // the agent focused and running): recycle ENDS this agent and boots a brand-new
 // resident root here.
 //
@@ -73,7 +73,7 @@ export async function recycleNode(nodeId, callerPane) {
         finalized = true;
     }
     catch { /* recycle the pane even if the report failed */ }
-    // The node's pane is a VIEWER (`crtr attach`), not its engine: the engine is
+    // The node's pane is a VIEWER (`crtr surface attach`), not its engine: the engine is
     // the detached broker process, so respawn-pane -k below would only kill the
     // viewer, never the engine. Tear the broker PROCESS down so it exits and
     // releases the sole .jsonl writer. Status is already flipped done by pushFinal
@@ -127,7 +127,7 @@ export async function recycleNode(nodeId, callerPane) {
  *  engine runs in a DETACHED broker, not the pane. Birth-launch that broker via
  *  the Host seam (mirrors spawnChild's birth path — the host records its pid),
  *  wait for its view.sock to accept, then respawn the pane in place to the VIEWER
- *  `crtr attach to <root>`. The pane stays a viewer (attach self-tags it
+ *  `crtr surface attach to <root>`. The pane stays a viewer (attach self-tags it
  *  `@crtr_node`); it never hosts the engine. Returns false (recycle reports the
  *  pane was not respawned) when the broker never serves — the fresh root row
  *  still exists, broker-hosted, for the daemon to revive. */
@@ -138,15 +138,15 @@ async function recycleBrokerViewer(fresh, pane, inv) {
     if (!(await waitForBrokerViewSocket(fresh.node_id, placed.exited)))
         return false;
     // Clear the finalized node's stale `@crtr_node` tag before respawn so the tag
-    // never names a done node during the gap before the new `crtr attach` re-tags
+    // never names a done node during the gap before the new `crtr surface attach` re-tags
     // on connect. Node ids are shell-safe identifiers; no quoting needed.
     try {
         setPaneOption(pane, '@crtr_node', '');
     }
     catch { /* best-effort */ }
     // SYNC respawn: the recycle command runs as a SEPARATE CLI process (the viewer
-    // runs `crtr attach`, a TUI — it never execs recycle), so we are NOT respawning
+    // runs `crtr surface attach`, a TUI — it never execs recycle), so we are NOT respawning
     // our own pane and can confirm the respawn actually landed (the honest exit
     // status), unlike the tmux path which often recycles the caller's own pane.
-    return respawnPaneSync({ pane, cwd: fresh.cwd, env: viewerSplitEnv(), command: `crtr attach to ${fresh.node_id}` });
+    return respawnPaneSync({ pane, cwd: fresh.cwd, env: viewerSplitEnv(), command: `crtr surface attach to ${fresh.node_id}` });
 }

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

@@ -6,7 +6,7 @@ import { respawnPaneSync } from './placement.js';
  *  keep parent=rootId. No wipe. Returns the reaped ids.
  *
  *  Why `canceled` (A5, human-confirmed 2026-06-06): an externally-reaped node —
- *  whether via `node close` OR a root reset — did not finish its OWN work, so it
+ *  whether via `node lifecycle close` OR a root reset — did not finish its OWN work, so it
  *  unifies on `canceled`; `done` is reserved for finalize. Why marking is STILL
  *  explicit: an abrupt broker teardown fires NO clean `session_shutdown`, so the
  *  general quit→done rule does NOT auto-resolve a force-killed descendant — we

package/dist/core/runtime/reset.js

@@ -2,7 +2,7 @@
 // termination.
 //
 // A node's engine is a detached broker process bound to one CRTR_NODE_ID, and
-// its on-screen viewer is a SEPARATE `crtr attach` pane. `/new` splits by who
+// its on-screen viewer is a SEPARATE `crtr surface attach` pane. `/new` splits by who
 // ran it:
 //
 //   • relaunchRoot — a `/new` on a ROOT starts a genuinely new node: the old
@@ -35,7 +35,7 @@ import { spawnNode, rootOfSpine } from './nodes.js';
  *  keep parent=rootId. No wipe. Returns the reaped ids.
  *
  *  Why `canceled` (A5, human-confirmed 2026-06-06): an externally-reaped node —
- *  whether via `node close` OR a root reset — did not finish its OWN work, so it
+ *  whether via `node lifecycle close` OR a root reset — did not finish its OWN work, so it
  *  unifies on `canceled`; `done` is reserved for finalize. Why marking is STILL
  *  explicit: an abrupt broker teardown fires NO clean `session_shutdown`, so the
  *  general quit→done rule does NOT auto-resolve a force-killed descendant — we
@@ -129,7 +129,7 @@ export async function relaunchRoot(oldId, deps = {}) {
             pane: oldFocus.pane,
             cwd: old.cwd,
             env: viewerSplitEnv(),
-            command: `crtr attach to ${newMeta.node_id}`,
+            command: `crtr surface attach to ${newMeta.node_id}`,
         });
         const window = windowOfPane(oldFocus.pane);
         if (window !== null)

package/dist/core/runtime/revive-all.d.ts

@@ -11,8 +11,11 @@ export declare const TERMINAL_BY_CHOICE: readonly NodeStatus[];
  *  — the precise "disconnected" predicate (gh #9).
  *
  *  - engine not running: no live `pi_pid` (a dead/absent broker pid).
- *  - resumable: a captured pi session (`pi_session_file` or `pi_session_id`) —
- *    without one there is nothing to resume.
+ *  - reconnectable: a captured pi session marker (`pi_session_file` or
+ *    `pi_session_id`) — without one there is nothing to reopen. reviveNode
+ *    resumes by the `.jsonl` path when it still exists, else relaunches fresh (a
+ *    bare `pi_session_id` alone no longer resumes — the broker preflight rejects
+ *    it — so such a node comes back fresh).
  *  - `human`-kind rows are the `crtr human` bridge, never a pi engine, so they
  *    are never "disconnected" (mirrors the daemon's superviseTick carve-out).
  *  - terminal-by-choice (`done`/`canceled`) is always excluded.

package/dist/core/runtime/revive-all.js

@@ -27,8 +27,11 @@ export const TERMINAL_BY_CHOICE = ['done', 'canceled'];
  *  — the precise "disconnected" predicate (gh #9).
  *
  *  - engine not running: no live `pi_pid` (a dead/absent broker pid).
- *  - resumable: a captured pi session (`pi_session_file` or `pi_session_id`) —
- *    without one there is nothing to resume.
+ *  - reconnectable: a captured pi session marker (`pi_session_file` or
+ *    `pi_session_id`) — without one there is nothing to reopen. reviveNode
+ *    resumes by the `.jsonl` path when it still exists, else relaunches fresh (a
+ *    bare `pi_session_id` alone no longer resumes — the broker preflight rejects
+ *    it — so such a node comes back fresh).
  *  - `human`-kind rows are the `crtr human` bridge, never a pi engine, so they
  *    are never "disconnected" (mirrors the daemon's superviseTick carve-out).
  *  - terminal-by-choice (`done`/`canceled`) is always excluded.

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

@@ -1,14 +1,20 @@
 import { type NodeMeta } from '../canvas/index.js';
 import type { WakeOrigin } from './bearings.js';
 import { headlessBrokerHost } from './host.js';
-/** Pick the `--session` source for a revive. resume=true prefers the absolute
- *  session-file path (immune to cwd; pi opens it directly) and keeps the bare
- *  session id as the fallback for older nodes booted before pi_session_file was
- *  captured. buildPiArgv prefers the path when both are present. resume=false (a
- *  refresh-yield) selects neither — the node re-reads its roadmap fresh. Pure so
- *  the path-vs-id selection is unit-testable without tmux. */
+/** Pick the `--session` source for a revive. resume=true resumes by the
+ *  absolute session-file path (immune to cwd; pi opens it directly) — but ONLY
+ *  when that file actually exists on disk. A node's `pi_session_file` can be
+ *  recorded in meta with nothing ever written there (e.g. its first-boot engine
+ *  died before session_start ever ran), and `headlessBrokerHost.launch`'s
+ *  preflight (host.ts) fatally rejects handing pi a `--session` for a missing
+ *  path OR a bare id — either would crash the revive and strand the node dead
+ *  with nothing to recover it. So when there is no real `.jsonl` to resume,
+ *  this selects NEITHER source: the caller then falls through to a fresh
+ *  (`--fresh`-equivalent) launch, which is always safe. resume=false (a
+ *  refresh-yield) also selects neither — the node re-reads its roadmap fresh.
+ *  Pure so the decision is unit-testable without tmux or a real filesystem
+ *  fixture beyond a temp file. */
 export declare function resumeArgs(meta: NodeMeta, resume: boolean): {
-    resumeSessionId?: string;
     resumeSessionPath?: string;
 };
 export interface ReviveResult {
@@ -18,7 +24,8 @@ export interface ReviveResult {
     /** The node's last live LOCATION session, or null — the broker engine has no
      *  tmux session of its own (it opens no viewer). Kept for caller back-compat. */
     session: string | null;
-    /** True when pi was instructed to resume its saved conversation (`--session <id>`). */
+    /** True when pi was instructed to resume its saved conversation by its
+     *  absolute session-file path (`--session <path>`). */
     resumed: boolean;
     /** Launch handle for the detached broker, so callers can fail fast on its real
      *  exit before the socket appears. */