@crouton-kit/crouter 0.3.33 → 0.3.35

package/dist/core/runtime/revive.js

@@ -9,36 +9,47 @@
 // auto-reconnect), and a node with no viewer is brought on screen by the next
 // `focus`.
 //
-//   resume=true  → `pi --session <path|id>` — wakes the saved conversation,
-//                  preferring the absolute session-file path (cwd-immune) over
-//                  the bare session id.
+//   resume=true  → `pi --session <path>` — wakes the saved conversation by its
+//                  absolute session-file path (cwd-immune), but only when that
+//                  file actually exists on disk; otherwise falls through to a
+//                  fresh launch (see resumeArgs).
 //   resume=false → fresh pi invocation — the node re-reads its roadmap/context dir.
 //
 // reviveNode remains the ONLY sanctioned launcher of the node engine.
+import { existsSync } from 'node:fs';
 import { getNode, updateNode, clearPid, fullName, cancelDeadlinesFor, } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
 import { buildPiArgv } from './launch.js';
 import { buildReviveKickoff, drainBearings } from './kickoff.js';
 import { headlessBrokerHost } from './host.js';
 import { isPidAlive } from '../canvas/pid.js';
+import { reconcileBootLiveness } from '../canvas/boot.js';
 import { clearFault } from './fault.js';
 import { clearInjectedDocs } from '../substrate/injected-store.js';
 // ---------------------------------------------------------------------------
 // resumeArgs — which session source a revive resumes from
 // ---------------------------------------------------------------------------
-/** 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 function resumeArgs(meta, resume) {
     if (!resume)
         return {};
-    return {
-        resumeSessionId: meta.pi_session_id ?? undefined,
-        resumeSessionPath: meta.pi_session_file ?? undefined,
-    };
+    const path = meta.pi_session_file;
+    if (path != null && path !== '' && existsSync(path)) {
+        return { resumeSessionPath: path };
+    }
+    return {};
 }
 // ---------------------------------------------------------------------------
 // reviveNode
@@ -62,6 +73,15 @@ export function reviveNode(nodeId, opts) {
         updateNode(nodeId, { host_kind: 'broker' });
         meta.host_kind = 'broker';
     }
+    // A durable-row / ephemeral-pid boot change (a sandbox/VM destroy+recreate,
+    // or a host reboot) invalidates every `pi_pid` recorded before it — the OS
+    // process table reset, so a small stale pid can coincidentally collide with
+    // an unrelated process on the new boot and fool the double-launch guard
+    // right below into believing a dead broker is still alive. Idempotent and
+    // cheap once reconciled (a single small file read) except the one time it
+    // actually matters, so it's safe to call on every revive regardless of
+    // entry point (daemon tick, or a direct/manual `canvas revive`).
+    reconcileBootLiveness();
     // Double-revive guard: the broker's isAlive IS isPidAlive(pi_pid), so a node
     // whose broker pid is still running was already revived by another path —
     // re-launching would put a SECOND broker on the same session file. No-op.
@@ -78,10 +98,26 @@ export function reviveNode(nodeId, opts) {
     // launches with the incremented count.
     meta.cycles = (meta.cycles ?? 0) + 1;
     updateNode(nodeId, { cycles: meta.cycles });
-    // Decide whether to wake the saved pi conversation or start fresh. Prefer the
-    // absolute session-file path (cwd-immune); fall back to the bare id.
+    // Decide whether to wake the saved pi conversation or start fresh. resumeArgs
+    // resumes ONLY by the absolute session-file path (cwd-immune) and ONLY when
+    // that .jsonl actually exists; there is no bare-id fallback (the broker
+    // preflight rejects a bare `--session`). Anything else is a fresh launch.
     const resume = resumeArgs(meta, opts.resume);
-    const resuming = resume.resumeSessionPath !== undefined || resume.resumeSessionId !== undefined;
+    const resuming = resume.resumeSessionPath !== undefined;
+    // A fresh (non-resuming) launch starts a NEW pi session — the old session
+    // identity is dead. Clear it from meta NOW, before launch, so the recorded
+    // state matches what we're about to do. This is load-bearing for boot-failure
+    // classification: if this fresh broker dies BEFORE session_start (recording
+    // no new pid and no new session), the daemon's pid-null branch keys on
+    // pi_session_id — a leftover stale id would be misread as a "stranded
+    // relaunch" and retried forever instead of surfaced via transition('crash') +
+    // surfaceBootFailure. Clearing it makes the failure show as pid=NULL +
+    // session=NULL → boot failure, the correct terminal outcome.
+    if (!resuming && (meta.pi_session_id != null || meta.pi_session_file != null)) {
+        updateNode(nodeId, { pi_session_id: null, pi_session_file: null });
+        meta.pi_session_id = null;
+        meta.pi_session_file = null;
+    }
     // A fresh revive (no resume) gets a kickoff prompt so it re-reads its roadmap
     // and continues; resuming a saved conversation needs none. drainBearings is the
     // one-shot consuming step (yield note + feed cursor + persona ack); the builder

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

@@ -7,7 +7,7 @@ export interface BootRootOpts {
     /** Optional starter prompt (bare `crtr` requires none). */
     prompt?: string;
 }
-/** Create the front-door root: launch its broker engine, then exec `crtr attach`
+/** Create the front-door root: launch its broker engine, then exec `crtr surface attach`
  *  inline so THIS terminal becomes the broker's controller-viewer. Does not
  *  return — it process.exit()s when the inline attach exits (detach leaves the
  *  resident broker running, to be reconnected later). */

package/dist/core/runtime/spawn.js

@@ -3,7 +3,7 @@
 // (resolve), launch (pi argv), and tmux (placement).
 //
 //   bootRoot   — the user-opened front door (bare `crtr`). Resident; launches the
-//                root's broker engine, then execs `crtr attach` inline so THIS
+//                root's broker engine, then execs `crtr surface attach` inline so THIS
 //                terminal becomes the broker's controller-viewer.
 //   spawnChild — a node spawned by a live node (`crtr node new`). A managed,
 //                terminal background worker by default; with `root`, an
@@ -42,12 +42,12 @@ function launchBrokerOrCrash(nodeId, inv, opts) {
         throw new Error(`[broker] refusing to launch ${nodeId}: ${error.message}`);
     }
 }
-/** Create the front-door root: launch its broker engine, then exec `crtr attach`
+/** Create the front-door root: launch its broker engine, then exec `crtr surface attach`
  *  inline so THIS terminal becomes the broker's controller-viewer. Does not
  *  return — it process.exit()s when the inline attach exits (detach leaves the
  *  resident broker running, to be reconnected later). */
 export async function bootRoot(opts) {
-    // crtr is tmux-only: the front door execs `crtr attach` inline in THIS pane to
+    // crtr is tmux-only: the front door execs `crtr surface attach` inline in THIS pane to
     // become the root's controller-viewer, so there must be a tmux pane to anchor
     // on. Outside tmux there is no viewer surface — throw with a friendly message
     // rather than boot a root nobody can see.
@@ -101,7 +101,7 @@ export async function bootRoot(opts) {
     // pane lives in the focuses table (below).
     const here = currentTmux();
     // The FOREGROUND front-door terminal is the root's one viewer: record its pane
-    // as the node's viewer focus row so focus/nav can find it. The `crtr attach`
+    // as the node's viewer focus row so focus/nav can find it. The `crtr surface attach`
     // exec below makes the terminal a controller-viewer of the broker; detaching
     // leaves the resident broker running.
     if (here !== null) {
@@ -113,7 +113,7 @@ export async function bootRoot(opts) {
     const inv = buildPiArgv(meta, { prompt: opts.prompt });
     // Broker is the only host: the root runs as a detached broker engine (so its
     // first refresh/revive doesn't strand this terminal — the daemon revives the
-    // broker and the viewer reconnects), and THIS terminal execs `crtr attach`
+    // broker and the viewer reconnects), and THIS terminal execs `crtr surface attach`
     // inline to become its controller-viewer. The host sets CRTR_FRONT_DOOR.
     inv.env = { ...inv.env, CRTR_SUBTREE: rootOfSpine(meta.node_id) };
     const placed = launchBrokerOrCrash(meta.node_id, inv, {
@@ -140,7 +140,7 @@ export async function bootRoot(opts) {
         throw new Error(`the front-door root broker ${meta.node_id} never bound its view socket — cannot attach.`);
     }
     const attachEnv = { ...process.env, ...viewerSplitEnv() };
-    const r = spawnSync('crtr', ['attach', 'to', meta.node_id], { stdio: 'inherit', env: attachEnv });
+    const r = spawnSync('crtr', ['surface', 'attach', 'to', meta.node_id], { stdio: 'inherit', env: attachEnv });
     process.exit(r.status ?? 0);
 }
 /** pi's sessions root, VENDORED from pi `config.getSessionsDir()` (= `<agentDir>/
@@ -314,7 +314,7 @@ export async function spawnChild(opts) {
     inv.env = { ...inv.env, CRTR_SUBTREE: rootOfSpine(meta.node_id) };
     // Broker is the only host: launch the detached broker ENGINE. A managed child
     // gets NO viewer — spawning it returns once the engine is launched and a human
-    // opens a viewer on demand via `crtr node focus` / `crtr attach`. A --root gets
+    // opens a viewer on demand via `crtr node focus` / surface attach. A --root gets
     // one foreground viewer below.
     const placed = launchBrokerOrCrash(meta.node_id, inv, {
         cwd: meta.cwd,

package/dist/core/runtime/stop-guard.js

@@ -16,7 +16,7 @@
 //                      Also fine.
 //   • otherwise      → a TERMINAL node with nothing live to wait for and no
 //                      final pushed. Re-prompt it to finish or escalate.
-import { hasActiveLiveSubscription, hasPendingSelfWake, getNode } from '../canvas/index.js';
+import { hasActiveLiveSubscription, hasPendingSelfTrigger, getNode } from '../canvas/index.js';
 export const STALL_REPROMPT = "You've stopped but you're not waiting on anyone and haven't finished. " +
     'Run `crtr push final "<result>"` if the work is done, or `crtr human ask` if you are blocked or need the user.';
 /** Decide what to do when a node stops. Pure given the canvas + this turn's
@@ -40,10 +40,10 @@ export function evaluateStop(nodeId, signals) {
     if (node !== null && node.lifecycle === 'resident') {
         return { action: 'allow', reason: 'dormant' };
     }
-    // A terminal node with a pending self-scheduled wakeup is legitimately
-    // waiting on the clock: the daemon's wakeup sweep resumes it when the wake
-    // fires, so it should idle-release rather than busy-wait holding pi/window.
-    if (hasPendingSelfWake(nodeId))
+    // A terminal node with a pending self-scheduled trigger is legitimately
+    // waiting on the clock: the daemon's trigger sweep resumes it when the
+    // trigger fires, so it should idle-release rather than busy-wait holding pi/window.
+    if (hasPendingSelfTrigger(nodeId))
         return { action: 'allow', reason: 'scheduled' };
     // A terminal node holding something live to wake it is legitimately awaiting.
     if (hasActiveLiveSubscription(nodeId))

package/dist/core/runtime/surface-bg.js

@@ -17,7 +17,7 @@
 // door (which never otherwise loads pi). We only READ the process-global symbol;
 // any process that needs styling (the attach viewer, a node's broker) has already
 // called `initTheme()` and populated it. Where the symbol is absent (the front
-// door, before it execs into the themed `crtr attach`), the tmux helpers return
+// door, before it execs into the themed `crtr surface attach`), the tmux helpers return
 // no style args and the chrome stays at its default — the viewer re-themes it.
 const THEME_SYMBOL = Symbol.for('@earendil-works/pi-coding-agent:theme');
 /** The live pi Theme if a process has already run `initTheme()`, else undefined.

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

@@ -120,7 +120,7 @@ export declare function paneLocation(pane: string): {
 export declare function paneExists(pane: string): boolean;
 /** Does this pane exist AND have its command still RUNNING (`#{pane_dead}` = 0)?
  *  Distinguishes a pane genuinely hosting a live process from a remain-on-exit
- *  corpse frozen after exit (`pane_dead` = 1). Node viewer panes run `crtr attach`
+ *  corpse frozen after exit (`pane_dead` = 1). Node viewer panes run `crtr surface attach`
  *  as the pane command, so pane-running ⟹ a live viewer occupies it. */
 export declare function paneRunning(pane: string): boolean;
 /** Every live pane id on the server (`list-panes -a`), as a Set for membership

package/dist/core/runtime/tmux.js

@@ -247,7 +247,7 @@ export function paneExists(pane) {
 }
 /** Does this pane exist AND have its command still RUNNING (`#{pane_dead}` = 0)?
  *  Distinguishes a pane genuinely hosting a live process from a remain-on-exit
- *  corpse frozen after exit (`pane_dead` = 1). Node viewer panes run `crtr attach`
+ *  corpse frozen after exit (`pane_dead` = 1). Node viewer panes run `crtr surface attach`
  *  as the pane command, so pane-running ⟹ a live viewer occupies it. */
 export function paneRunning(pane) {
     const r = tmux(['display-message', '-p', '-t', pane, '#{pane_id}\t#{pane_dead}']);
@@ -501,7 +501,7 @@ export function installNavBindings() {
 // is claimed, and bare Alt pairs are a minefield in real configs (e.g. Alt+,/. 
 // and Alt+]/.[ commonly bound to window/pane nav). The bracket lives in the
 // private table, so it also sidesteps the M-[ vs CSI-introducer ambiguity that
-// dogs installNavBindings' Alt+[. Each key shells `crtr view cycle`, passing the
+// dogs installNavBindings' Alt+[. Each key shells surface-view cycle, passing the
 // active pane; cycle reads the pane's @crtr_view tag and respawns it on the
 // next/prev view. Output discarded so the keypress never pops a results view.
 // Installed at root boot alongside the node nav + Alt+C menu.
@@ -523,11 +523,11 @@ export function installViewNavBindings() {
     ]).ok;
     const next = tmux([
         'bind-key', '-T', 'crtr-view', ']', 'run-shell',
-        `crtr view cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`,
+        `crtr surface view cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`,
     ]).ok;
     const prev = tmux([
         'bind-key', '-T', 'crtr-view', '[', 'run-shell',
-        `crtr view cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`,
+        `crtr surface view cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`,
     ]).ok;
     return enter && next && prev;
 }

package/dist/core/scope.d.ts

@@ -1,9 +1,18 @@
 import type { InstalledPlugin, Scope } from '../types.js';
 export declare function builtinViewsRoot(): string;
 export declare function builtinMemoryRoot(): string;
+export declare function builtinPiPackagesDir(): string;
+export declare function builtinPiPackageDir(name: string): string;
 export declare function userScopeRoot(): string;
 export declare function findProjectScopeRoot(startDir?: string): string | null;
+/** Every project scope root visible from `startDir`, nearest first. Each
+ *  ancestor directory with a `.crouter/` contributes memory/preferences to the
+ *  current workspace; the nearest root still wins for writes and duplicate doc
+ *  names. The user-global `~/.crouter/` is excluded because it is the separate
+ *  user scope, not a project ancestor. */
+export declare function findProjectScopeRoots(startDir?: string): string[];
 export declare function projectScopeRoot(startDir?: string): string | null;
+export declare function projectScopeRoots(startDir?: string): string[];
 export declare function scopeRoot(scope: Scope): string | null;
 export declare function requireScopeRoot(scope: Scope): string;
 export declare function ensureProjectScopeRoot(startDir?: string): string;

package/dist/core/scope.js

@@ -24,38 +24,60 @@ export function builtinMemoryRoot() {
     const pkgDir = dirname(coreDir); // src/ or dist/
     return join(pkgDir, 'builtin-memory');
 }
+export function builtinPiPackagesDir() {
+    const thisFile = fileURLToPath(import.meta.url);
+    const coreDir = dirname(thisFile);
+    const pkgDir = dirname(coreDir); // src/ or dist/
+    return join(pkgDir, 'builtin-pi-packages');
+}
+export function builtinPiPackageDir(name) {
+    return join(builtinPiPackagesDir(), name);
+}
 export function userScopeRoot() {
     return join(homedir(), CRTR_DIR_NAME);
 }
+function isProjectScopeDir(candidate, userRoot) {
+    if (candidate === userRoot || !existsSync(candidate))
+        return false;
+    try {
+        return statSync(candidate).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 export function findProjectScopeRoot(startDir = process.cwd()) {
     if (cachedProjectRoot !== undefined)
         return cachedProjectRoot;
+    const roots = findProjectScopeRoots(startDir);
+    cachedProjectRoot = roots[0] ?? null;
+    return cachedProjectRoot;
+}
+/** Every project scope root visible from `startDir`, nearest first. Each
+ *  ancestor directory with a `.crouter/` contributes memory/preferences to the
+ *  current workspace; the nearest root still wins for writes and duplicate doc
+ *  names. The user-global `~/.crouter/` is excluded because it is the separate
+ *  user scope, not a project ancestor. */
+export function findProjectScopeRoots(startDir = process.cwd()) {
+    const roots = [];
     const userRoot = userScopeRoot();
     let dir = resolve(startDir);
     while (true) {
         const candidate = join(dir, CRTR_DIR_NAME);
-        if (candidate !== userRoot && existsSync(candidate)) {
-            try {
-                if (statSync(candidate).isDirectory()) {
-                    cachedProjectRoot = candidate;
-                    return candidate;
-                }
-            }
-            catch {
-                /* fall through */
-            }
-        }
+        if (isProjectScopeDir(candidate, userRoot))
+            roots.push(candidate);
         const parent = dirname(dir);
-        if (parent === dir) {
-            cachedProjectRoot = null;
-            return null;
-        }
+        if (parent === dir)
+            return roots;
         dir = parent;
     }
 }
 export function projectScopeRoot(startDir) {
     return findProjectScopeRoot(startDir);
 }
+export function projectScopeRoots(startDir) {
+    return findProjectScopeRoots(startDir);
+}
 export function scopeRoot(scope) {
     // The builtin scope has no scope-root dir: its only content is memory
     // (builtinMemoryRoot) and views (builtinViewsRoot), both hard special cases.

package/dist/core/substrate/on-read.js

@@ -7,10 +7,12 @@
 // surface (design §4/§6; Stream A native rules):
 //
 //   • POSITIONAL — walk the read file's ancestor dirs; any doc living in an
-//     ancestor's `.crouter/memory/` surfaces (a doc surfaces when a file
-//     beside/under its own scope dir is read), UNLESS it carries an explicit
-//     read-trigger (see D5 below). This mirrors nested-context's `.claude/rules`
-//     ancestor walk, but keyed on `.crouter/memory/`.
+//     ancestor PROJECT `.crouter/memory/` surfaces (a doc surfaces when a file
+//     beside/under its own project scope dir is read), UNLESS it carries an
+//     explicit read-trigger (see D5 below). This mirrors nested-context's
+//     `.claude/rules` ancestor walk, but keyed on `.crouter/memory/`. The
+//     user-global `~/.crouter/memory/` store is NOT positional; user docs only
+//     fire on reads through explicit `applies-to` / `read-when` triggers.
 //   • applies-to GLOB — any RESOLVED substrate doc (user/project/builtin scope)
 //     whose `appliesTo` glob matches the read file path surfaces, regardless of
 //     where the read file sits relative to the doc.
@@ -35,8 +37,8 @@
 //   parse → gatePasses(doc, assembleNodeSubject(nodeId)) → render
 //   (content → body, preview → previewLine, name → bare tag, none → skip).
 // The result is the faithful envelope (verdict n1):
-//   <auto-loaded-context file="…">
-//   <doc kind="…" name="…" src="…" triggered-by="…">…body/preview…</doc>
+//   <auto-loaded-context>
+//   <memory kind="…" name="…" src="…">…body/preview…</memory>
 //   </auto-loaded-context>
 // Returns '' when nothing surfaces.
 //
@@ -141,27 +143,28 @@ function safeWalkMd(dir) {
 function hasExplicitTrigger(doc) {
     return (doc.appliesTo !== undefined && doc.appliesTo.length > 0) || doc.readWhen !== undefined;
 }
-/** POSITIONAL trigger: every substrate doc in an ancestor dir's
+/** POSITIONAL trigger: every substrate doc in an ancestor PROJECT dir's
  *  `.crouter/memory/`, walking from the read file up to $HOME (or the
- *  filesystem root for a read outside $HOME), skipping junk ancestors. */
+ *  filesystem root for a read outside $HOME), skipping junk ancestors. The
+ *  user-global `~/.crouter/memory/` store is deliberately skipped: otherwise
+ *  every file read under $HOME would surface unrelated user-wide preferences. */
 function positionalCandidates(absReadFile) {
     const out = [];
     const seenDocPaths = new Set();
-    const home = homedir();
+    const home = realpathOrSelf(homedir());
     const fsRoot = parse(absReadFile).root;
     let dir = dirname(absReadFile);
     let depth = 0;
     while (true) {
-        if (!isJunkAncestor(dir)) {
+        if (dir !== home && !isJunkAncestor(dir)) {
             const memDir = join(dir, CRTR_DIR_NAME, 'memory');
             if (pathExists(memDir)) {
-                const scope = dir === home ? 'user' : 'project';
                 for (const file of safeWalkMd(memDir)) {
                     const real = realpathOrSelf(file);
                     if (seenDocPaths.has(real))
                         continue;
                     seenDocPaths.add(real);
-                    const doc = loadPositionalDoc(file, memDir, scope);
+                    const doc = loadPositionalDoc(file, memDir, 'project');
                     // D5: a doc with an explicit read-trigger (applies-to/read-when) does
                     // NOT fire positionally — it surfaces only via that trigger.
                     if (doc && !hasExplicitTrigger(doc))
@@ -276,10 +279,10 @@ function readWhenCandidates(readFileFm, taken) {
 // ---------------------------------------------------------------------------
 // Per-doc envelope render.
 // ---------------------------------------------------------------------------
-/** One doc as a `<doc …>` element at its fileReadVisibility rung, or null when
- *  that rung is `none`. `content` → full body; `preview` → the routing line;
- *  `name` → a bare self-closed tag (the `name=` attribute IS the surface). */
-function renderDocEnvelope(doc, absReadFile) {
+/** One memory as a `<memory …>` element at its fileReadVisibility rung, or null
+ *  when that rung is `none`. `content` → full body; `preview` → the routing
+ *  line; `name` → a bare self-closed tag (the `name=` attribute IS the surface). */
+function renderDocEnvelope(doc) {
     const rung = doc.fileReadVisibility;
     if (rung === 'none')
         return null;
@@ -289,9 +292,8 @@ function renderDocEnvelope(doc, absReadFile) {
     else if (rung === 'preview')
         body = previewLine(doc);
     // 'name' → body stays '' (the tag's name attribute is the whole surface).
-    const attrs = `kind="${attr(doc.kind)}" name="${attr(doc.name)}" ` +
-        `src="${attr(disp(doc.path))}" triggered-by="${attr(disp(absReadFile))}"`;
-    return body === '' ? `<doc ${attrs} />` : `<doc ${attrs}>\n${body}\n</doc>`;
+    const attrs = `kind="${attr(doc.kind)}" name="${attr(doc.name)}" src="${attr(disp(doc.path))}"`;
+    return body === '' ? `<memory ${attrs} />` : `<memory ${attrs}>\n${body}\n</memory>`;
 }
 // ---------------------------------------------------------------------------
 // Public entry point.
@@ -366,7 +368,7 @@ export function renderOnReadDocs(nodeId, readFilePath, seen = new Set()) {
             const doc = rung === c.doc.fileReadVisibility && displayName(c.doc.name) === c.doc.name
                 ? c.doc
                 : { ...c.doc, fileReadVisibility: rung, name: displayName(c.doc.name) };
-            block = renderDocEnvelope(doc, absReadFile);
+            block = renderDocEnvelope(doc);
         }
         catch {
             continue; // a single bad doc never breaks the read
@@ -378,5 +380,5 @@ export function renderOnReadDocs(nodeId, readFilePath, seen = new Set()) {
     }
     if (rendered.length === 0)
         return '';
-    return `<auto-loaded-context file="${attr(disp(absReadFile))}">\n${rendered.join('\n')}\n</auto-loaded-context>`;
+    return `<auto-loaded-context>\n${rendered.join('\n')}\n</auto-loaded-context>`;
 }

package/dist/core/substrate/render.js

@@ -285,9 +285,9 @@ const PREFERENCES_INTRO = 'Preferences are how the user wants you to behave —
     READ_LEGEND.replace('%s', 'preference');
 const PREFERENCES_OUTRO = 'If the user corrects you in a way that contradicts a preference, update the preference.';
 const KNOWLEDGE_INTRO = 'Knowledge documents are what you consult — playbooks and techniques for how to do things, and ' +
-    'references on the user, projects, and this node. They are aggregated from your three memory ' +
-    'scopes: user-global (`~/.crouter/memory/`), project (`<project-root>/.crouter/memory/`), and ' +
-    "node-local (this node's `context/memory/`). To read one, run `crtr memory read <name>`. " +
+    'references on the user, projects, and this node. They are aggregated from your memory stores: ' +
+    'user-global (`~/.crouter/memory/`), every ancestor project store (`<dir>/.crouter/memory/`) ' +
+    "from the cwd upward, and node-local (this node's `context/memory/`). To read one, run `crtr memory read <name>`. " +
     'Each doc exists to prevent a specific mistake you would make without it, so when your task ' +
     'matches one — by its name or its `# read when:` line — read it before you act; consulting it ' +
     'only after the work is done forfeits the entire reason it exists. ' +

package/dist/core/view/loader.js

@@ -161,7 +161,7 @@ export function requireTui(r) {
         throw new InputError({
             error: 'view_web_only',
             message: `'${r.id}' is web-only — it ships no tui.mjs presenter`,
-            next: `Run \`crtr view serve ${r.id}\` to open it in the browser.`,
+            next: 'Open it in the browser through the surface web server.',
         });
     }
 }
@@ -171,7 +171,7 @@ export function requireWeb(r) {
         throw new InputError({
             error: 'view_tui_only',
             message: `'${r.id}' is tui-only — it ships no web.jsx presenter`,
-            next: `Run \`crtr view run ${r.id}\` to open it in a tmux pane.`,
+            next: 'Open it in a tmux pane with the surface view run leaf.',
         });
     }
 }

package/dist/core/wake.d.ts

@@ -67,9 +67,9 @@ export declare function parseCadence(every: string, opts: ParseOpts): CadenceRes
  *   - {"cron":"0 9 * * *","tz":"America/…"}  -> ``cron `0 9 * * *` (America/…)``
  *   - null / undefined / unparseable         -> `none`
  *
- * The ONE cadence-display helper, shared by the `node wake` CLI surface
+ * The ONE cadence-display helper, shared by the `node triggers` CLI surface
  * (list/guidance) and the <crtr-wake> wake-provenance block (bearings.ts), so
- * the cadence an agent reads in its wake block matches `crtr node wake list`
+ * the cadence an agent reads in its wake block matches `crtr node triggers`
  * exactly. Cadence only — never an instance count.
  */
 export declare function cadenceDisplay(recur: string | null | undefined): string;

package/dist/core/wake.js

@@ -1,9 +1,9 @@
-// Time grammar + recurrence evaluation for scheduled wakeups.
+// Time grammar + recurrence evaluation for scheduled triggers.
 //
-// This is the ONE place that owns wakeup time logic. Both the CLI surface
-// (`node wake at|until|spawn`) and the daemon's firing pass import
-// from here, so there is no duplicated cron usage and no surface<->daemon
-// inverted dependency:
+// This is the ONE place that owns trigger time logic. Both the CLI surface
+// (`node new --at/--every/--when`, `node msg --at/--every/--when`) and the
+// daemon's firing pass import from here, so there is no duplicated cron usage
+// and no surface<->daemon inverted dependency:
 //   - parseWhen / parseCadence  — arm-time grammar (surface, T7)
 //   - nextSlotAfter             — per-tick advance / coalescing (daemon, T4)
 //
@@ -250,9 +250,9 @@ export function parseCadence(every, opts) {
  *   - {"cron":"0 9 * * *","tz":"America/…"}  -> ``cron `0 9 * * *` (America/…)``
  *   - null / undefined / unparseable         -> `none`
  *
- * The ONE cadence-display helper, shared by the `node wake` CLI surface
+ * The ONE cadence-display helper, shared by the `node triggers` CLI surface
  * (list/guidance) and the <crtr-wake> wake-provenance block (bearings.ts), so
- * the cadence an agent reads in its wake block matches `crtr node wake list`
+ * the cadence an agent reads in its wake block matches `crtr node triggers`
  * exactly. Cadence only — never an instance count.
  */
 export function cadenceDisplay(recur) {