@crouton-kit/crouter 0.3.18 → 0.3.20

package/dist/pi-extensions/__tests__/canvas-context-intro.test.d.ts

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

package/dist/pi-extensions/__tests__/canvas-context-intro.test.js

@@ -0,0 +1,171 @@
+// Run with: node --import tsx/esm --test src/pi-extensions/__tests__/canvas-context-intro.test.ts
+//
+// BUG REGRESSION (crouter/CLAUDE.md testing policy):
+//   `crtr node new --fork-from <node>` caused AGENT IDENTITY CONFUSION. A fork
+//   inherits the SOURCE node's entire first-person conversation (pi COPIES it
+//   into the fork's session), so on boot the forked agent impersonated the
+//   source — it kept acting AS the source, even "monitoring itself" as a phantom
+//   child, until it happened to check CRTR_NODE_ID. Two root causes, both fixed
+//   here and pinned by these tests:
+//     1. canvas-context-intro never re-asserted the node's OWN identity, so the
+//        copied first-person narrative won.
+//     2. the idempotency guard misfired for a fork: the copied conversation
+//        already carries the SOURCE's <crtr-context> entry, so the guard treated
+//        it as "already present" and SUPPRESSED the fork's own intro entirely —
+//        the fork booted with the source's bearings (source id, source dir).
+//   Symptom write-up: nodes/mq4ns376-da6e56c9/reports/20260608T075810-final.md.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { buildContextIntro, registerCanvasContextIntro, CONTEXT_INTRO_CUSTOM_TYPE, } from '../canvas-context-intro.js';
+import { createNode } from '../../core/canvas/canvas.js';
+import { closeDb } from '../../core/canvas/db.js';
+let home;
+let origNode;
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+/** A session entry as `sessionManager.getEntries()` would return it — a custom
+ *  message carrying a bearings block (string content). */
+function introEntry(content) {
+    return { type: 'custom_message', customType: CONTEXT_INTRO_CUSTOM_TYPE, content };
+}
+function makeFakePi() {
+    let handler;
+    return {
+        sent: [],
+        on(event, h) {
+            if (event === 'session_start')
+                handler = h;
+        },
+        sendMessage(m) {
+            this.sent.push(m);
+        },
+        registerMessageRenderer() {
+            /* display-only; irrelevant here */
+        },
+        fireSessionStart(entries) {
+            handler?.(undefined, { sessionManager: { getEntries: () => entries } });
+        },
+    };
+}
+before(() => {
+    origNode = process.env['CRTR_NODE_ID'];
+});
+beforeEach(() => {
+    closeDb();
+    if (home)
+        rmSync(home, { recursive: true, force: true });
+    home = mkdtempSync(join(tmpdir(), 'crtr-context-intro-'));
+    process.env['CRTR_HOME'] = home;
+    delete process.env['CRTR_NODE_ID'];
+});
+after(() => {
+    closeDb();
+    if (home)
+        rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+    if (origNode === undefined)
+        delete process.env['CRTR_NODE_ID'];
+    else
+        process.env['CRTR_NODE_ID'] = origNode;
+});
+test('boot intro asserts the node\'s OWN identity up front (regression: forked node impersonated source)', () => {
+    createNode(node('alpha', { name: 'fix-auth', kind: 'developer' }));
+    const intro = buildContextIntro('alpha');
+    assert.match(intro, /<crtr-identity>/, 'opens with an explicit identity block');
+    assert.match(intro, /You are node alpha/, 'names the node by its own id');
+    assert.match(intro, /kind developer/, 'states the node kind');
+    // Gated (Option A): a fresh (non-fork) node's bearings are its FIRST entry, so
+    // there is no earlier narrative to disown — the disown framing (the fork callout
+    // naming the copied history "inherited reference material") is fork-only and must
+    // NOT appear here.
+    assert.ok(!/inherited reference material/.test(intro), 'a non-fork node carries no disown-the-earlier-narrative line');
+    // The identity block must come BEFORE the <crtr-context> bearings, so it is the
+    // first thing the model reads — the orienting frame, not a trailing note.
+    assert.ok(intro.indexOf('<crtr-identity>') < intro.indexOf('<crtr-context'), 'identity assertion precedes the context bearings');
+});
+test('a FORK\'s intro names the source and disowns it (regression: fork acted AS the source)', () => {
+    // The source node whose conversation pi copied into the fork.
+    createNode(node('src7', { name: 'looking-pi-crouter', description: 'monitor-telemetry' }));
+    // The fork: fork_from provenance persisted at spawn.
+    createNode(node('fork9', { fork_from: 'src7' }));
+    const intro = buildContextIntro('fork9');
+    assert.match(intro, /You are node fork9/, 'the fork is told its OWN id');
+    assert.match(intro, /You are a FORK of src7/, 'names the fork source explicitly');
+    assert.match(intro, /You are NOT src7/, '"you are NOT the source" flag is present');
+    // Carries the source's human label so the agent recognizes the copied persona.
+    assert.match(intro, /looking-pi-crouter/, 'surfaces the source label');
+    // The fork DOES carry the disown framing — it has a real referent (copied history).
+    assert.match(intro, /inherited reference material/, 'the fork disowns the copied first-person narrative');
+    // It must NOT tell the fork it is the source node.
+    assert.ok(!/You are node src7/.test(intro), 'fork is never told it is the source node');
+    // A non-fork sibling gets the identity assertion but NO fork callout and NO
+    // disown line (gated on fork_from).
+    createNode(node('plain2'));
+    const plain = buildContextIntro('plain2');
+    assert.match(plain, /You are node plain2/);
+    assert.ok(!/FORK of/.test(plain), 'a fresh (non-fork) node carries no fork callout');
+    assert.ok(!/inherited reference material/.test(plain), 'a non-fork node carries no disown line');
+});
+test('session_start INJECTS the fork\'s own bearings despite the inherited source block (the misfiring-idempotency bug)', () => {
+    createNode(node('srcA'));
+    createNode(node('forkB', { fork_from: 'srcA' }));
+    // A fork boots with the SOURCE's whole conversation copied in — including the
+    // source's <crtr-context> intro entry (which names srcA, not forkB).
+    const inheritedSourceBlock = introEntry(buildContextIntro('srcA'));
+    process.env['CRTR_NODE_ID'] = 'forkB';
+    const pi = makeFakePi();
+    registerCanvasContextIntro(pi);
+    pi.fireSessionStart([inheritedSourceBlock]);
+    // The fix: the inherited block belongs to srcA, so it must NOT suppress
+    // forkB's own intro. forkB's bearings (with its identity assertion) ARE sent.
+    assert.equal(pi.sent.length, 1, 'fork injects its OWN bearings over the inherited source block');
+    assert.equal(pi.sent[0].customType, CONTEXT_INTRO_CUSTOM_TYPE);
+    assert.match(pi.sent[0].content, /You are node forkB/, 'injected bearings name the fork, not the source');
+    assert.match(pi.sent[0].content, /You are a FORK of srcA/, 'injected bearings carry the fork callout');
+    // The exact, machine-readable resume discriminator rides along (not sent to
+    // the LLM): it names THIS node, so a later resume tells our block apart from
+    // any inherited one without depending on prose.
+    assert.equal(pi.sent[0].details?.nodeId, 'forkB', 'injected block carries the exact node-id stamp');
+});
+test('resume idempotency uses the EXACT details stamp, independent of block text (regression hardening)', () => {
+    createNode(node('stampD'));
+    // A restored block that carries OUR exact stamp but whose TEXT does not mention
+    // our id. The old content-substring-only guard would re-inject (and accumulate)
+    // here; the exact `details.nodeId` match skips correctly.
+    const stampedNoIdInText = {
+        type: 'custom_message',
+        customType: CONTEXT_INTRO_CUSTOM_TYPE,
+        content: '<crtr-context dir="/elsewhere">bearings with no id in the text</crtr-context>',
+        details: { nodeId: 'stampD' },
+    };
+    process.env['CRTR_NODE_ID'] = 'stampD';
+    const pi = makeFakePi();
+    registerCanvasContextIntro(pi);
+    pi.fireSessionStart([stampedNoIdInText]);
+    assert.equal(pi.sent.length, 0, 'exact details-stamp match skips re-injection even when the text omits the id');
+});
+test('session_start stays IDEMPOTENT on a genuine resume (our own bearings already present)', () => {
+    createNode(node('resumeC'));
+    // A `--session` relaunch restores OUR conversation — our own bearings (naming
+    // resumeC) are already in history.
+    const ownBlock = introEntry(buildContextIntro('resumeC'));
+    process.env['CRTR_NODE_ID'] = 'resumeC';
+    const pi = makeFakePi();
+    registerCanvasContextIntro(pi);
+    pi.fireSessionStart([ownBlock]);
+    assert.equal(pi.sent.length, 0, 'our own bearings already present → no duplicate injection');
+});

package/dist/pi-extensions/__tests__/canvas-stophook-agentend.test.js

@@ -113,9 +113,11 @@ test('natural stop while awaiting a live worker → idle-release with NO push (n
 // '%pane' ids below are never read by tmux). status='done' is reached by setting
 // the runtime row directly (the branch reads getNode(nodeId).status).
 // ---------------------------------------------------------------------------
-test('§5.1.1 truly-done + focused + manager-not-focused → MANAGER TAKEOVER of the focus row', () => {
+test('§5.1.1 truly-done + focused + dormant idle-release manager-not-focused → MANAGER TAKEOVER of the focus row', () => {
     createNode(node('root', { parent: null, lifecycle: 'resident' }));
-    createNode(node('mgr', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator' }));
+    // mgr is dormant + idle-release — the ONLY dormant manager the daemon will
+    // revive INTO the frozen pane, so the ONLY dormant case that is a real takeover.
+    createNode(node('mgr', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator', status: 'idle', intent: 'idle-release' }));
     // M starts WITH a recorded LOCATION so the MINOR presence-null is observable.
     createNode(node('M', { parent: 'mgr', lifecycle: 'terminal', pane: '%m', tmux_session: 'Suser', window: '@wm' }));
     subscribe('mgr', 'M', true);
@@ -126,8 +128,9 @@ test('§5.1.1 truly-done + focused + manager-not-focused → MANAGER TAKEOVER of
     registerCanvasStophook(pi);
     let shutdown = false;
     pi.fire('agent_end', stopEvent('done — pushed final'), { shutdown: () => { shutdown = true; } });
-    // managerId = M.parent = 'mgr' (not focused elsewhere, no live pane here → the
-    // DORMANT-takeover path) → handFocusToManager repoints fM's occupant M→mgr. The
+    // managerId = M.parent = 'mgr' (idle-release, not focused elsewhere, no live
+    // pane here → the DORMANT-takeover path) → handFocusToManager repoints fM's
+    // occupant M→mgr (true ONLY because mgr is idle+idle-release). The
     // daemon later revives mgr INTO M's frozen focus pane. Non-vacuous: a no-op (no
     // handoff) impl leaves M as occupant, so getFocusByNode('mgr') is null AND
     // getFocusByNode('M') still names fM — both asserts fail.
@@ -197,22 +200,26 @@ test('§5.1.4 truly-done + UNFOCUSED → no focus row created/touched, shuts dow
     assert.equal(shutdown, true, 'an unfocused done node shuts down');
     assert.equal(listFocuses().length, 0, 'no focus row was created or touched');
 });
-test('§5.1.5 awaiting + focused → idle-release FREEZE: the focus row SURVIVES untouched (F3)', () => {
+test('§5.1.5 awaiting + FOCUSED → STAY ALIVE: pi keeps running (no release), focus row untouched (F3)', () => {
     createNode(node('root', { parent: null, lifecycle: 'resident' }));
     createNode(node('mgr', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator' }));
     createNode(node('worker', { parent: 'mgr', lifecycle: 'terminal', status: 'active' }));
     subscribe('root', 'mgr', true);
-    subscribe('mgr', 'worker', true); // mgr awaits a live worker → idle-release
+    subscribe('mgr', 'worker', true); // mgr awaits a live worker → would idle-release if UNfocused
     openFocusRow('fMgr', '%g', 'Suser', 'mgr');
     process.env['CRTR_NODE_ID'] = 'mgr';
     const pi = makeFakePi();
     registerCanvasStophook(pi);
-    pi.fire('agent_end', stopEvent('still waiting on the worker'), { shutdown: () => { } });
-    // The awaiting branch only transition('release')s — it must NOT close or
-    // repoint the focus (that is the done branch). Non-vacuous: a wrong impl that
-    // routed an idle-release through the done-branch handoff/close would change or
-    // remove fMgr.
-    assert.equal(getNode('mgr')?.intent, 'idle-release', 'mgr idle-released (frozen)');
+    let shutdown = false;
+    pi.fire('agent_end', stopEvent('still waiting on the worker'), { shutdown: () => { shutdown = true; } });
+    // A FOCUSED awaiting node holds the user's viewport, so the awaiting branch
+    // keeps pi LIVE and dormant (the in-process inbox-watcher wakes it) instead of
+    // releasing + shutting down. It must NOT release, NOT shut down, and NOT touch
+    // the focus row. Non-vacuous: the old freeze impl flipped intent→idle-release
+    // and shut pi down; this pins all three as untouched.
+    assert.equal(getNode('mgr')?.status, 'active', 'a focused awaiting node stays active (not released)');
+    assert.equal(getNode('mgr')?.intent ?? null, null, 'no idle-release intent while focused');
+    assert.equal(shutdown, false, 'a focused awaiting node is NOT shut down — pi stays live');
     assert.equal(getFocusByNode('mgr')?.focus_id, 'fMgr', 'the focus row is UNCHANGED — not closed, not handed off');
 });
 test('§5.1.7 resident attended (no live subs) → nothing happens; focus + status survive', () => {

package/dist/pi-extensions/canvas-commands.d.ts

@@ -8,6 +8,9 @@ interface CommandUI {
 }
 interface CommandCtx {
     ui: CommandUI;
+    /** Current run mode: "tui" | "rpc" | "json" | "print". Guard "tui" for the
+     *  interactive-only path (headless brokers bind 'print'). */
+    mode: string;
 }
 interface CustomMessage {
     customType: string;

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

@@ -54,6 +54,16 @@ export function registerCanvasCommands(pi) {
             return items.length > 0 ? items : null;
         },
         handler: async (args, ctx) => {
+            // Interactive-only. A headless (print-mode) broker never invokes /promote
+            // (promotion there runs `crtr node promote` directly), so the command is
+            // inert. Under tmux ctx.mode is always 'tui' — byte-identical there.
+            if (ctx.mode !== 'tui') {
+                try {
+                    ctx.ui.notify('/promote needs the interactive TUI', 'warning');
+                }
+                catch { /* best-effort */ }
+                return;
+            }
             const kind = args.trim().toLowerCase();
             ctx.ui.setStatus('crtr-promote', kind ? `promoting → ${kind}…` : 'promoting…');
             const argv = ['node', 'promote', '--json'];

package/dist/pi-extensions/canvas-context-intro.d.ts

@@ -4,6 +4,18 @@ export declare const CONTEXT_INTRO_CUSTOM_TYPE = "crtr-context";
 interface SessionEntryLike {
     type: string;
     customType?: string;
+    /** custom_message entries carry their injected content (string or blocks). */
+    content?: string | Array<{
+        type: string;
+        text?: string;
+    }>;
+    /** Extension metadata we stamp on the block (NOT sent to the LLM). The
+     *  authoritative idempotency discriminator: `nodeId` is the node the block
+     *  belongs to, so a fork (whose copied source block carries the SOURCE's id)
+     *  is told apart from a genuine resume by an EXACT id match. */
+    details?: {
+        nodeId?: string;
+    };
 }
 interface SessionStartCtxLike {
     sessionManager: {
@@ -14,6 +26,11 @@ interface CustomMessageLike {
     customType: string;
     content: string;
     display?: boolean;
+    /** Extension-only metadata (not sent to the LLM); used as the exact
+     *  idempotency discriminator on resume — see SessionEntryLike.details. */
+    details?: {
+        nodeId: string;
+    };
 }
 /** The message handed to a message renderer. `content` is normally the string we
  *  sent, but pi types it as string-or-blocks, so we handle both. */

package/dist/pi-extensions/canvas-context-intro.js

@@ -14,17 +14,26 @@
 //    session_start instead.)
 //
 // The block carries: the path to the node's own context dir and the framing for
-// what belongs there (a shared document store for the other nodes). Resident
-// orchestrators additionally get the across-refresh-cycles framing + a <memory>
-// block merging the indexes of their three scoped memory stores (user-global,
-// project, node-local), each labeled with its absolute dir + index path. The
-// prose lives in core/runtime/bearings.ts (shared with the promotion guidance
-// dump), which gates the memory block on the node having a node-local store — so
-// a terminal worker gets no memory framing at all.
+// what belongs there (a shared document store for the other nodes). EVERY node
+// also gets a <memory> block merging the indexes of its three scoped memory
+// stores (user-global, project, node-local), each labeled with its dir — one
+// consistent surface, since every node is born with all three stores. An
+// orchestrator additionally gets the across-refresh-cycles framing (the one
+// thing a terminal worker's bearings drop). The prose lives in
+// core/runtime/bearings.ts (shared with the promotion guidance dump).
 //
-// IDEMPOTENT across resumes: a `--session` relaunch restores the conversation,
-// so the block is already in history; the session_start handler sees it via
-// `sessionManager.getEntries()` and skips, so it never accumulates.
+// IDEMPOTENT across resumes, but FORK-AWARE: a `--session` relaunch restores OUR
+// conversation (whose bearings name OUR node id), so the session_start handler
+// sees it via `sessionManager.getEntries()` and skips — it never accumulates. A
+// `--fork-from` boot, by contrast, COPIES the source node's whole conversation
+// (whose bearings name the SOURCE's node id), so the handler must NOT treat that
+// inherited block as ours; it only skips when a bearings block belonging to OUR
+// node is already present (exact `details.nodeId` stamp, content-match
+// fallback), otherwise it injects ours — whose <crtr-identity> block reasserts
+// the fork's identity over the inherited persona. This is ONE of two reinforcing
+// channels: spawn.ts ALSO prepends the same identity assertion to a fork's
+// kickoff prompt (the turn-triggering message), so the override does not rest on
+// a single trailing custom_message.
 //
 // COLLAPSED BY DEFAULT: a `registerMessageRenderer` keyed to our customType
 // renders the block as a single one-line stub; the full body only appears when
@@ -62,6 +71,21 @@ function messageText(message) {
         .map((c) => c.text)
         .join('\n');
 }
+/** Plain text of a session entry's content (string or text blocks), '' when
+ *  absent. Used by the idempotency guard to tell OUR own injected bearings
+ *  (which name our node id) from a SOURCE's bearings copied in by `--fork-from`. */
+function entryText(e) {
+    const c = e.content;
+    if (typeof c === 'string')
+        return c;
+    if (Array.isArray(c)) {
+        return c
+            .filter((b) => typeof b?.text === 'string')
+            .map((b) => b.text)
+            .join('\n');
+    }
+    return '';
+}
 /** Hard-wrap a single logical line to `width` columns (content carries no ANSI).
  *  Code-point aware so wide-string slicing never splits a surrogate pair; the
  *  bearings prose is plain text, so code-point count == visible columns. */
@@ -140,19 +164,35 @@ export function registerCanvasContextIntro(pi) {
             const nodeId = process.env['CRTR_NODE_ID'];
             if (nodeId === undefined || nodeId.trim() === '')
                 return; // not a canvas node
-            // Idempotent: a restored/reloaded session already carries the block.
-            const present = ctx.sessionManager
+            // Idempotent on RESUME, but NOT fooled by a FORK. A `--session` relaunch
+            // restores OUR conversation, whose bearings name OUR node id — skip then,
+            // so the block never accumulates. A `--fork-from` boot instead copies the
+            // SOURCE node's whole conversation (its bearings name ITS node id, not
+            // ours), so a naive "any crtr-context present?" check would suppress our
+            // own intro and let the fork inherit — and impersonate — the source. So we
+            // only skip when a bearings block belonging to OUR node is already present.
+            // Primary discriminator: the EXACT `details.nodeId` stamp (machine-
+            // readable, copied on fork, never sent to the LLM). Fallback: a substring
+            // match on the block text (our id appears in the identity line AND the
+            // context-dir path `…/nodes/<nodeId>/context`) — covers legacy blocks
+            // persisted before the stamp existed. Either match ⇒ this is our own
+            // resume, not an inherited fork block, so skip.
+            const ours = ctx.sessionManager
                 .getEntries()
-                .some((e) => e.type === 'custom_message' && e.customType === CONTEXT_INTRO_CUSTOM_TYPE);
-            if (present)
+                .some((e) => e.type === 'custom_message' &&
+                e.customType === CONTEXT_INTRO_CUSTOM_TYPE &&
+                (e.details?.nodeId === nodeId || entryText(e).includes(nodeId)));
+            if (ours)
                 return;
             // No delivery options: at the idle start of a session this is pushed onto
             // the (still empty) message list and persisted immediately, so it precedes
-            // the node's first prompt.
+            // the node's first prompt. The `details.nodeId` stamp rides along as the
+            // exact resume discriminator (not shown to the LLM).
             pi.sendMessage({
                 customType: CONTEXT_INTRO_CUSTOM_TYPE,
                 content: buildContextIntro(nodeId),
                 display: true,
+                details: { nodeId },
             });
         }
         catch {

package/dist/pi-extensions/canvas-doc-substrate.d.ts

@@ -0,0 +1,44 @@
+/** before_agent_start: pi hands us the assembled system prompt; returning a new
+ *  `systemPrompt` replaces it for this agent run (pi rebuilds it each run, so
+ *  splicing fresh every time is idempotent — never cumulative). */
+interface BeforeAgentStartEventLike {
+    systemPrompt: string;
+}
+interface BeforeAgentStartResultLike {
+    systemPrompt: string;
+}
+/** tool_result: fired after a tool returns. `content` is the tool's output
+ *  blocks; returning a new `content` replaces what the model sees. */
+interface ContentBlockLike {
+    type: string;
+    text?: string;
+}
+interface ToolResultEventLike {
+    toolName: string;
+    isError?: boolean;
+    /** The tool's resolved input. For `read` it carries the file path under
+     *  `path` (or the legacy `file_path`). Typed loosely; narrowed at use. */
+    input?: unknown;
+    content: ContentBlockLike[];
+}
+interface ToolResultCtxLike {
+    /** The session cwd — used to resolve a relative read path. */
+    cwd?: string;
+}
+type ToolResultResultLike = {
+    content: ContentBlockLike[];
+} | void;
+interface PiLike {
+    on(event: 'before_agent_start', handler: (event: BeforeAgentStartEventLike) => BeforeAgentStartResultLike | void | Promise<BeforeAgentStartResultLike | void>): void;
+    on(event: 'session_start', handler: (event: unknown, ctx: unknown) => void): void;
+    on(event: 'tool_result', handler: (event: ToolResultEventLike, ctx: ToolResultCtxLike) => ToolResultResultLike | Promise<ToolResultResultLike>): void;
+}
+/**
+ * Register the document substrate's two render hooks on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent — a non-canvas pi
+ * session gets neither hook. Each handler is independently wrapped so a failure
+ * degrades to a no-op (boot proceeds, the read returns) rather than bricking.
+ */
+export declare function registerCanvasDocSubstrate(pi: PiLike): void;
+export default registerCanvasDocSubstrate;

package/dist/pi-extensions/canvas-doc-substrate.js

@@ -0,0 +1,112 @@
+// canvas-doc-substrate.ts — the document substrate's two render hooks, owned by
+// a single self-contained canvas pi extension.
+//
+// Loaded into a canvas node's pi process via the node's launch.extensions list
+// (registered in CANVAS_EXTENSIONS at the flip — see the note at the bottom of
+// this file; AUTHOR-ONLY for now, NOT yet registered). INERT when CRTR_NODE_ID
+// is absent (a plain pi session or legacy job agent loads it as a no-op).
+//
+// It owns the substrate's two new pi hooks:
+//
+//   1. before_agent_start — the BOOT system-prompt half. Splices the rendered
+//      `## Skills` + `## Preferences` sections into `event.systemPrompt`, right
+//      after pi's native "Available tools" list (before the `\n\nGuidelines:`
+//      anchor), so the substrate's skills/preferences sit in the tool-selection
+//      frame the agent reads while choosing a capability — mirroring the
+//      personal crouter-help.ts anchor logic. Falls back to appending when the
+//      anchor is absent.
+//
+//   2. tool_result (gated on `read`) — the ON-READ half. For each non-error
+//      `read`, surfaces the substrate docs that should appear alongside the file
+//      (positional `.crouter/memory/` ancestors + `applies-to` globs) at their
+//      file-read-visibility rung, prepended as a `<auto-loaded-context>` block
+//      before the file contents. A per-session realpath set dedups so the same
+//      doc is not re-injected on repeat reads.
+//
+// Both handler bodies are wrapped in try/catch and degrade to INERT on error —
+// a substrate bug must never brick node boot or break a `read`, only quietly
+// stop surfacing docs. The pure render lives in core/substrate/ (render.ts +
+// on-read.ts); this file is only the pi-hook plumbing.
+//
+// Plain TS-with-types — NO imports from @earendil-works/* (a local structural
+// PiLike interface stands in), so it compiles inside crouter's own tsc build
+// with no dep on the pi packages. Mirrors canvas-context-intro.ts.
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { renderOnReadDocs, renderPreferencesSection, renderSkillsSection, } from '../core/substrate/index.js';
+import { clearSessionCache } from '../core/substrate/session-cache.js';
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+/** The stable seam that closes pi's native "Available tools" list. We splice the
+ *  substrate's boot sections right before it — the agent decides which capability
+ *  to reach for while reading the tools, so skills/preferences must sit there,
+ *  not far below. Mirrors crouter-help.ts. Falls back to appending if absent. */
+const TOOLS_ANCHOR = '\n\nGuidelines:';
+/**
+ * Register the document substrate's two render hooks on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent — a non-canvas pi
+ * session gets neither hook. Each handler is independently wrapped so a failure
+ * degrades to a no-op (boot proceeds, the read returns) rather than bricking.
+ */
+export function registerCanvasDocSubstrate(pi) {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId.trim() === '')
+        return; // not a canvas node — inert
+    // Per-session set of injected doc realpaths → a doc surfaces at most once per
+    // session across repeated reads. Cleared on every session_start (so a resume
+    // starts fresh, matching the on-read precedent).
+    // Also clears the per-session substrate parse cache so the corpus is re-scanned
+    // fresh for each new session (avoids stale docs after a skill/memory write).
+    const injectedDocs = new Set();
+    pi.on('session_start', () => {
+        injectedDocs.clear();
+        clearSessionCache();
+    });
+    // 1. BOOT system-prompt half — splice `## Skills` + `## Preferences`.
+    pi.on('before_agent_start', (event) => {
+        try {
+            const sections = [renderSkillsSection(nodeId), renderPreferencesSection(nodeId)].filter((s) => s !== '');
+            if (sections.length === 0)
+                return; // nothing eligible — leave the prompt untouched
+            const block = sections.join('\n\n');
+            const idx = event.systemPrompt.indexOf(TOOLS_ANCHOR);
+            if (idx === -1) {
+                return { systemPrompt: `${event.systemPrompt}\n\n${block}` };
+            }
+            return {
+                systemPrompt: `${event.systemPrompt.slice(0, idx)}\n\n${block}${event.systemPrompt.slice(idx)}`,
+            };
+        }
+        catch {
+            return; // inert on error — never brick node boot
+        }
+    });
+    // 2. ON-READ half — augment a non-error `read` result with surfacing docs.
+    pi.on('tool_result', (event, ctx) => {
+        try {
+            if (event.toolName !== 'read' || event.isError === true)
+                return;
+            const input = event.input;
+            const rawPath = input?.path ?? input?.file_path;
+            if (rawPath === undefined || rawPath === '')
+                return;
+            // Resolve to an absolute path (renderOnReadDocs realpaths it). pi's read
+            // tool expands a leading `~`, but event.input keeps the raw form, so
+            // expand it ourselves before resolving against the session cwd.
+            const cwd = typeof ctx?.cwd === 'string' && ctx.cwd !== '' ? ctx.cwd : process.cwd();
+            const expanded = rawPath.startsWith('~') ? join(homedir(), rawPath.slice(1)) : rawPath;
+            const absFile = resolve(cwd, expanded);
+            const injected = renderOnReadDocs(nodeId, absFile, injectedDocs);
+            if (injected === '')
+                return; // nothing surfaced — pass the read through unchanged
+            // Prepend the surfacing docs ahead of the file contents.
+            return { content: [{ type: 'text', text: injected }, ...event.content] };
+        }
+        catch {
+            return; // inert on error — a bug must degrade a read, never break it
+        }
+    });
+}
+export default registerCanvasDocSubstrate;

package/dist/pi-extensions/canvas-nav.d.ts

@@ -15,6 +15,9 @@ interface UIContext {
 }
 interface ExtensionCtx {
     ui: UIContext;
+    /** Current run mode: "tui" | "rpc" | "json" | "print". The nav chrome +
+     *  ask-poll timer are interactive-only; headless brokers bind 'print'. */
+    mode: string;
 }
 interface CommandCtx {
     ui: UIContext;