@crouton-kit/crouter 0.3.14 → 0.3.15

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

@@ -0,0 +1,266 @@
+// Run with: node --import tsx/esm --test src/pi-extensions/__tests__/canvas-stophook-agentend.test.ts
+//
+// The stophook's agent_end routing no longer auto-pushes anything: a node
+// reaches its subscribers ONLY through its own explicit `crtr push` calls.
+// These tests pin that on the three stop outcomes:
+//   • natural stop while awaiting a live worker → idle-release, NO push
+//   • refresh-yield (intent='refresh')          → re-exec/shutdown, NO push
+//   • stalled leaf (nothing live, no final)      → reprompt still fires
+// Every assertion is on DB / disk effects (report files, inbox pointers) plus
+// the captured sendUserMessage — tmux is unavailable here, so the focus/respawn
+// helpers no-op (TMUX_PANE is cleared) and we drive a clean shutdown path.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import registerCanvasStophook from '../canvas-stophook.js';
+import { createNode, subscribe, getNode, setStatus } from '../../core/canvas/canvas.js';
+import { openFocusRow, getFocusByNode, getFocusById, listFocuses } from '../../core/canvas/focuses.js';
+import { closeDb } from '../../core/canvas/db.js';
+import { reportsDir } from '../../core/canvas/paths.js';
+import { readInboxSince } from '../../core/feed/inbox.js';
+import { STALL_REPROMPT } from '../../core/runtime/stop-guard.js';
+let home;
+let origNode;
+let origPane;
+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,
+    };
+}
+function makeFakePi() {
+    const handlers = {};
+    return {
+        injected: [],
+        on(e, h) { handlers[e] = h; },
+        sendUserMessage(content, options) { this.injected.push({ content, deliverAs: options?.deliverAs }); },
+        fire(e, ev, ctx) { handlers[e]?.(ev, ctx); },
+    };
+}
+/** A natural-stop agent_end event carrying one assistant text block. */
+function stopEvent(text) {
+    return { messages: [{ role: 'assistant', stopReason: 'stop', content: [{ type: 'text', text }] }] };
+}
+/** Count of report files written under a node's reports/ dir (0 when none). */
+function reportCount(id) {
+    const dir = reportsDir(id);
+    return existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.md')).length : 0;
+}
+before(() => {
+    origNode = process.env['CRTR_NODE_ID'];
+    origPane = process.env['TMUX_PANE'];
+});
+beforeEach(() => {
+    closeDb();
+    if (home)
+        rmSync(home, { recursive: true, force: true });
+    home = mkdtempSync(join(tmpdir(), 'crtr-stophook-end-'));
+    process.env['CRTR_HOME'] = home;
+    // Force the clean-shutdown path (no in-place respawn) so the refresh test is
+    // deterministic even when the suite runs inside a tmux pane.
+    delete process.env['TMUX_PANE'];
+});
+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;
+    if (origPane === undefined)
+        delete process.env['TMUX_PANE'];
+    else
+        process.env['TMUX_PANE'] = origPane;
+});
+test('natural stop while awaiting a live worker → idle-release with NO push (no report, no inbox pointer)', () => {
+    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); // root would receive any push mgr emits
+    subscribe('mgr', 'worker', true); // mgr holds an active live subscription → "awaiting"
+    process.env['CRTR_NODE_ID'] = 'mgr';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    let shutdown = false;
+    pi.fire('agent_end', stopEvent('still waiting on the worker'), { shutdown: () => { shutdown = true; } });
+    const m = getNode('mgr');
+    assert.equal(m?.intent, 'idle-release', 'mgr idle-released');
+    assert.equal(m?.status, 'idle', 'mgr marked idle');
+    assert.equal(shutdown, true, 'pi shut down');
+    assert.equal(reportCount('mgr'), 0, 'NO report file written');
+    assert.equal(readInboxSince('root').length, 0, 'NO inbox pointer fanned to subscriber');
+    assert.equal(pi.injected.length, 0, 'no reprompt on a legitimate idle-release');
+    // §5.1 case 6 (awaiting + UNFOCUSED → idle-release, no focus): the awaiting
+    // branch must never create/touch a focus row. Non-vacuous: an impl that ran
+    // the done-branch handoff/openFocus on an idle-release would leave a row here.
+    assert.equal(listFocuses().length, 0, 'awaiting+unfocused leaves the focuses table empty');
+});
+// ---------------------------------------------------------------------------
+// §5.1 — the §1.7 agent_end branch map on the focuses table. Every assertion is
+// on the canvas focuses/runtime rows after firing agent_end (TMUX_PANE is
+// cleared in beforeEach, so the focus helpers in the handler are pure DB and the
+// '%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', () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident' }));
+    createNode(node('mgr', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator' }));
+    // 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);
+    openFocusRow('fM', '%m', 'Suser', 'M');
+    process.env['CRTR_NODE_ID'] = 'M';
+    setStatus('M', 'done'); // pushed final this turn
+    const pi = makeFakePi();
+    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
+    // 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.
+    assert.equal(getFocusByNode('mgr')?.focus_id, 'fM', 'focus row taken over by the manager');
+    assert.equal(getFocusByNode('M'), null, 'the finished node no longer occupies any focus');
+    assert.equal(shutdown, true, 'pi shut down after the handoff');
+    // MINOR: after a successful takeover M (done) owns no pane (Invariant P) — its
+    // own presence is nulled so two rows never reference %m. Non-vacuous: an impl
+    // that skips the done-path setPresence-null leaves getNode('M').pane === '%m'.
+    assert.equal(getNode('M')?.pane ?? null, null, 'the finished node\'s own LOCATION pane is nulled');
+    assert.equal(getNode('M')?.window ?? null, null, 'the finished node\'s window presence is nulled too');
+});
+test('§5.1.2 truly-done + focused + NO manager (root) → focus row CLOSED (Q1)', () => {
+    // R carries a LOCATION so the close-path presence-null is observable.
+    createNode(node('R', { parent: null, lifecycle: 'terminal', pane: '%r', tmux_session: 'Suser', window: '@wr' }));
+    openFocusRow('fR', '%r', 'Suser', 'R');
+    process.env['CRTR_NODE_ID'] = 'R';
+    setStatus('R', 'done');
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    pi.fire('agent_end', stopEvent('root done'), { shutdown: () => { } });
+    // managerId = R.parent(null) ?? subscribersOf(R)[0](none) = null →
+    // handFocusToManager returns false → the close path: closeFocusRow(fR) +
+    // setRemainOnExit(%r's window, false) (return-to-shell) + null R's presence.
+    // Non-vacuous: a takeover-instead-of-close impl would leave the row present;
+    // an impl that skips the MINOR presence-null leaves getNode('R').pane === '%r'.
+    assert.equal(getFocusById('fR'), null, 'a manager-less finished focus is closed, not handed off');
+    assert.equal(listFocuses().length, 0, 'no focus rows survive');
+    assert.equal(getNode('R')?.pane ?? null, null, 'the finished root\'s own LOCATION pane is nulled (close path reaps)');
+});
+test('§5.1.3 truly-done + focused + manager ALREADY focused elsewhere → focus CLOSED, manager UNMOVED', () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident' }));
+    createNode(node('mgr', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator' }));
+    createNode(node('M', { parent: 'mgr', lifecycle: 'terminal', pane: '%m', tmux_session: 'Sa', window: '@wm' }));
+    subscribe('mgr', 'M', true);
+    openFocusRow('fOther', '%o', 'Sb', 'mgr'); // mgr already on its OWN viewport
+    openFocusRow('fM', '%m', 'Sa', 'M');
+    process.env['CRTR_NODE_ID'] = 'M';
+    setStatus('M', 'done');
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    pi.fire('agent_end', stopEvent('M done'), { shutdown: () => { } });
+    // handFocusToManager sees getFocusByNode('mgr') != null → returns false →
+    // closeFocusRow(fM). Non-vacuous: moving mgr would either repoint its focus_id
+    // to fM (and a wrong impl that didn't close fM would leave it present) or throw
+    // UNIQUE(node_id); this pins mgr's OTHER focus untouched and M's focus gone.
+    assert.equal(getFocusById('fM'), null, "M's focus is closed");
+    assert.equal(getFocusByNode('mgr')?.focus_id, 'fOther', "the manager's other viewport is NOT stolen");
+    // MINOR: M (done) is reaped on the close path — its own presence nulled.
+    // Non-vacuous: an impl that skips the done-path setPresence-null leaves
+    // getNode('M').pane === '%m'.
+    assert.equal(getNode('M')?.pane ?? null, null, "the finished node's own LOCATION pane is nulled");
+});
+test('§5.1.4 truly-done + UNFOCUSED → no focus row created/touched, shuts down (Invariant P)', () => {
+    createNode(node('mgr', { parent: null, lifecycle: 'terminal', mode: 'orchestrator' }));
+    createNode(node('M', { parent: 'mgr', lifecycle: 'terminal' }));
+    subscribe('mgr', 'M', true);
+    process.env['CRTR_NODE_ID'] = 'M';
+    setStatus('M', 'done');
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    let shutdown = false;
+    pi.fire('agent_end', stopEvent('done, never had a viewport'), { shutdown: () => { shutdown = true; } });
+    // focusOf(M) is null → the focus block is skipped entirely → just shutdown.
+    // Non-vacuous: an impl that created or handed off a focus row would leave
+    // listFocuses non-empty.
+    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)', () => {
+    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
+    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)');
+    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', () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident' }));
+    openFocusRow('fR', '%r', 'Suser', 'root');
+    process.env['CRTR_NODE_ID'] = 'root';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    let shutdown = false;
+    pi.fire('agent_end', stopEvent('I have wrapped up'), { shutdown: () => { shutdown = true; } });
+    // evaluateStop on a resident → reason 'dormant' (NOT 'awaiting'), so the
+    // awaiting branch is skipped and the handler does nothing: no release, no
+    // shutdown, no focus touch. Non-vacuous: an impl that idle-released a resident
+    // would flip status→idle / intent→idle-release; one that touched focus would
+    // change/remove fR.
+    assert.equal(getNode('root')?.status, 'active', 'a resident is never forced dormant');
+    assert.equal(getNode('root')?.intent ?? null, null, 'no idle-release intent on a resident');
+    assert.equal(getFocusByNode('root')?.focus_id, 'fR', 'focus row survives untouched');
+    assert.equal(shutdown, false, 'a resident attended node is not shut down');
+});
+test('refresh-yield (intent=refresh) writes NO push — silent to subscribers', () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident' }));
+    createNode(node('orch', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator', intent: 'refresh' }));
+    subscribe('root', 'orch', true);
+    process.env['CRTR_NODE_ID'] = 'orch';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    let shutdown = false;
+    pi.fire('agent_end', stopEvent('checkpoint before refreshing'), { shutdown: () => { shutdown = true; } });
+    assert.equal(shutdown, true, 'pi shut down (no tmux pane → clean shutdown)');
+    assert.equal(reportCount('orch'), 0, 'a yield is silent: NO report file');
+    assert.equal(readInboxSince('root').length, 0, 'a yield is silent: NO inbox pointer');
+    assert.equal(pi.injected.length, 0, 'no reprompt on a refresh-yield');
+});
+test('stalled leaf (nothing live to await, no final) is still reprompted', () => {
+    createNode(node('mgr', { parent: null, lifecycle: 'terminal', mode: 'orchestrator' }));
+    createNode(node('leaf', { parent: 'mgr', lifecycle: 'terminal', status: 'active' }));
+    subscribe('mgr', 'leaf', true); // mgr subscribes to leaf; leaf itself awaits nothing
+    process.env['CRTR_NODE_ID'] = 'leaf';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    let shutdown = false;
+    pi.fire('agent_end', stopEvent('I think I am basically done here'), { shutdown: () => { shutdown = true; } });
+    assert.equal(pi.injected.length, 1, 'the stall reprompt fired');
+    assert.equal(pi.injected[0].content, STALL_REPROMPT, 'reprompt carries the stall nudge to push final / ask');
+    assert.equal(pi.injected[0].deliverAs, 'followUp', 'reprompt delivered as a followUp');
+    assert.equal(shutdown, false, 'a stalled leaf is NOT shut down — it is re-prompted to finish');
+    assert.notEqual(getNode('leaf')?.intent, 'idle-release', 'a stalled leaf does not idle-release');
+    assert.equal(reportCount('leaf'), 0, 'NO report file written on a stall');
+    assert.equal(readInboxSince('mgr').length, 0, 'NO inbox pointer fanned on a stall');
+});

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

@@ -1,11 +1,11 @@
 // canvas-commands.ts — pi extension registering canvas slash-commands on nodes.
 //
-//   /promote [kind]  — promote THIS node to a resident orchestrator. Runs
+//   /promote [kind]  — promote THIS node to an orchestrator. Runs
 //     `crtr node promote --json` for CRTR_NODE_ID (optionally specializing its
-//     kind), then injects the orchestration guidance the command returns into
-//     context and triggers a turn, so the node authors its roadmap immediately.
-//     This is the same mid-turn guidance dump the node would get by running the
-//     command itself by hand — surfaced as a one-keystroke affordance.
+//     kind), then triggers a turn. The orchestration guidance is injected
+//     CENTRALLY by the persona injector (canvas-stophook turn_end) at the turn
+//     boundary — the same path the node gets by running the command itself by
+//     hand — surfaced as a one-keystroke affordance.
 //
 // The Alt+C tmux action menu's "promote to orchestrator" item (key `o`) simply
 // send-keys `/promote` into the active pane, so the menu and the slash command
@@ -46,7 +46,7 @@ export function registerCanvasCommands(pi) {
     if (nodeId === undefined || nodeId.trim() === '')
         return; // not a canvas node
     pi.registerCommand('promote', {
-        description: 'Promote this node to a resident orchestrator — /promote, or /promote <kind> to specialize',
+        description: 'Promote this node to an orchestrator — /promote, or /promote <kind> to specialize',
         getArgumentCompletions: (prefix) => {
             const items = kinds()
                 .filter((k) => k.startsWith(prefix))
@@ -87,13 +87,16 @@ export function registerCanvasCommands(pi) {
             }
             const rmPath = (result.roadmap_path ?? '').trim();
             ctx.ui.notify(`Promoted to ${result.kind ?? 'orchestrator'} orchestrator — authoring roadmap${rmPath !== '' ? ` (${rmPath})` : ''}.`, 'info');
-            // The guidance is operating instructions for the node, not the user.
-            // Inject it silently and trigger a turn so the node acts on it now —
-            // exactly what happens when the node runs `crtr node promote` by hand.
-            const guidance = (result.guidance ?? '').trim();
-            if (guidance === '')
-                return;
-            pi.sendMessage({ customType: 'crtr-promote', content: guidance, display: false }, { triggerTurn: true });
+            // The orchestration guidance is no longer returned by the command — the
+            // persona injector (canvas-stophook turn_end) is the single source and
+            // steers it in at the next turn boundary. Trigger a turn so the node wakes
+            // and the injector fires, exactly as when the node runs `crtr node
+            // promote` itself by hand.
+            pi.sendMessage({
+                customType: 'crtr-promote',
+                content: 'You have just been promoted to an orchestrator. Your new-role guidance is arriving — read it, author your roadmap, and start delegating.',
+                display: false,
+            }, { triggerTurn: true });
         },
     });
 }

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

@@ -0,0 +1,70 @@
+/** The `customType` stamped on the injected session message. Used both to write
+ *  the entry and to detect it on resume (the idempotency guard). */
+export declare const CONTEXT_INTRO_CUSTOM_TYPE = "crtr-context";
+interface SessionEntryLike {
+    type: string;
+    customType?: string;
+}
+interface SessionStartCtxLike {
+    sessionManager: {
+        getEntries: () => SessionEntryLike[];
+    };
+}
+interface CustomMessageLike {
+    customType: string;
+    content: string;
+    display?: boolean;
+}
+/** 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. */
+interface RenderedMessageLike {
+    customType: string;
+    content: string | Array<{
+        type: string;
+        text?: string;
+    }>;
+}
+/** Minimal structural match for pi-tui's `Component` (render + invalidate). A
+ *  plain object of this shape is a valid child for pi's Container. */
+interface ComponentLike {
+    render: (width: number) => string[];
+    invalidate: () => void;
+}
+/** Subset of pi's `Theme` we touch — `fg(color, text)` wraps text in ANSI. Used
+ *  defensively (falls back to plain text if absent). */
+interface ThemeLike {
+    fg?: (color: string, text: string) => string;
+}
+interface PiLike {
+    on: (event: 'session_start', handler: (event: unknown, ctx: SessionStartCtxLike) => void | Promise<void>) => void;
+    sendMessage: (message: CustomMessageLike, options?: {
+        deliverAs?: string;
+        triggerTurn?: boolean;
+    }) => void;
+    registerMessageRenderer: (customType: string, renderer: (message: RenderedMessageLike, options: {
+        expanded?: boolean;
+    }, theme: ThemeLike) => ComponentLike | undefined) => void;
+}
+/** Build the <crtr-context> bearings block for `nodeId`. Thin wrapper over the
+ *  shared builder in core/runtime/bearings.ts (the single source of truth, also
+ *  used by the promotion guidance dump). Exported for testing. */
+export declare function buildContextIntro(nodeId: string): string;
+/**
+ * Renderer for `crtr-context` messages. Collapsed (default) shows a one-line
+ * stub; expanded (Ctrl+O) shows the label + full body. Returns a plain object
+ * matching pi's structural `Component` interface — no pi-tui import. Exported for
+ * testing.
+ */
+export declare function renderContextMessage(message: RenderedMessageLike, options: {
+    expanded?: boolean;
+}, theme: ThemeLike): ComponentLike;
+/**
+ * Register the context-intro preamble on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent. On `session_start`
+ * it injects the <crtr-context> block as the first message of a brand-new chat
+ * — but only when the session does not already carry it, so a `--session <id>`
+ * relaunch (which restores the conversation) never duplicates the block.
+ */
+export declare function registerCanvasContextIntro(pi: PiLike): void;
+export default registerCanvasContextIntro;

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

@@ -0,0 +1,164 @@
+// canvas-context-intro.ts — pi extension for pi-native canvas agent nodes.
+//
+// Loaded into every canvas node's pi process via the node's launch.extensions
+// list. INERT when CRTR_NODE_ID is absent (plain pi session or legacy job agent).
+//
+// The bearings preamble. On `session_start` — which fires BEFORE the node's
+// first user message enters the session — this injects ONE <crtr-context>
+// message via `pi.sendMessage` (no delivery options, so at the idle start it is
+// pushed straight onto the message list and persisted). Because the session is
+// still empty at that point, the bearings land as the FIRST entry, ahead of the
+// node's first prompt — the orienting frame, not a trailing afterthought.
+//   (before_agent_start / deliverAs:"nextTurn" both append AFTER the user
+//    message — see agent-session's submit path — which is why we use
+//    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.
+//
+// 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.
+//
+// COLLAPSED BY DEFAULT: a `registerMessageRenderer` keyed to our customType
+// renders the block as a single one-line stub; the full body only appears when
+// the user expands tool output (Ctrl+O / `app.tools.expand`). pi drives this via
+// `CustomMessageComponent.setExpanded(toolOutputExpanded)`, so the same toggle
+// that expands tool results expands the bearings. The renderer returns a plain
+// object satisfying pi's structural `Component` interface ({ render, invalidate })
+// — no pi-tui class needed. The LLM always sees the full `content` regardless of
+// how it renders; the renderer is display-only.
+//
+// Plain TS-with-types — no imports from @earendil-works/* so this compiles inside
+// crouter's own tsc build without a dep on the pi packages.
+import { buildContextBearings } from '../core/runtime/bearings.js';
+/** The `customType` stamped on the injected session message. Used both to write
+ *  the entry and to detect it on resume (the idempotency guard). */
+export const CONTEXT_INTRO_CUSTOM_TYPE = 'crtr-context';
+// ---------------------------------------------------------------------------
+// Block builder
+// ---------------------------------------------------------------------------
+/** Build the <crtr-context> bearings block for `nodeId`. Thin wrapper over the
+ *  shared builder in core/runtime/bearings.ts (the single source of truth, also
+ *  used by the promotion guidance dump). Exported for testing. */
+export function buildContextIntro(nodeId) {
+    return buildContextBearings(nodeId);
+}
+// ---------------------------------------------------------------------------
+// Collapsed-by-default rendering
+// ---------------------------------------------------------------------------
+/** Pull the plain text out of a custom message's content (string or blocks). */
+function messageText(message) {
+    if (typeof message.content === 'string')
+        return message.content;
+    return message.content
+        .filter((c) => c.type === 'text' && typeof c.text === 'string')
+        .map((c) => c.text)
+        .join('\n');
+}
+/** 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. */
+function wrapLine(line, width) {
+    if (width <= 0)
+        return [''];
+    const chars = Array.from(line);
+    if (chars.length <= width)
+        return [line];
+    const out = [];
+    for (let i = 0; i < chars.length; i += width)
+        out.push(chars.slice(i, i + width).join(''));
+    return out;
+}
+/** Truncate plain text to at most `width` columns, appending an ellipsis when it
+ *  would overflow. Content here is ANSI-free plain text (label + prose), so a
+ *  code-point count stands in for visible width. The renderer MUST keep every
+ *  emitted line within the terminal width or pi's TUI aborts the whole render. */
+function truncateToWidth(text, width) {
+    if (width <= 0)
+        return '';
+    const chars = Array.from(text);
+    if (chars.length <= width)
+        return text;
+    if (width === 1)
+        return '…';
+    return chars.slice(0, width - 1).join('') + '…';
+}
+/**
+ * Renderer for `crtr-context` messages. Collapsed (default) shows a one-line
+ * stub; expanded (Ctrl+O) shows the label + full body. Returns a plain object
+ * matching pi's structural `Component` interface — no pi-tui import. Exported for
+ * testing.
+ */
+export function renderContextMessage(message, options, theme) {
+    const expanded = options?.expanded === true;
+    const paint = (color, text) => typeof theme?.fg === 'function' ? theme.fg(color, text) : text;
+    return {
+        render(width) {
+            const w = typeof width === 'number' && width > 0 ? width : 80;
+            if (!expanded) {
+                // Truncate BEFORE painting so the ANSI wrapper never inflates the
+                // measured width; an over-wide line aborts pi's entire TUI render.
+                const stub = `[${CONTEXT_INTRO_CUSTOM_TYPE}] orienting bearings — ctrl+o to expand`;
+                return [paint('dim', truncateToWidth(stub, w))];
+            }
+            const lines = [paint('customMessageLabel', truncateToWidth(`[${CONTEXT_INTRO_CUSTOM_TYPE}]`, w)), ''];
+            for (const raw of messageText(message).split('\n')) {
+                for (const wrapped of wrapLine(raw, w))
+                    lines.push(paint('customMessageText', wrapped));
+            }
+            return lines;
+        },
+        invalidate() {
+            /* stateless — nothing to clear */
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+/**
+ * Register the context-intro preamble on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent. On `session_start`
+ * it injects the <crtr-context> block as the first message of a brand-new chat
+ * — but only when the session does not already carry it, so a `--session <id>`
+ * relaunch (which restores the conversation) never duplicates the block.
+ */
+export function registerCanvasContextIntro(pi) {
+    // Collapse the block to a one-liner until the user expands tool output (Ctrl+O).
+    // Harmless to register outside TUI mode (it's only consulted while rendering).
+    pi.registerMessageRenderer(CONTEXT_INTRO_CUSTOM_TYPE, renderContextMessage);
+    pi.on('session_start', (_event, ctx) => {
+        try {
+            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
+                .getEntries()
+                .some((e) => e.type === 'custom_message' && e.customType === CONTEXT_INTRO_CUSTOM_TYPE);
+            if (present)
+                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.
+            pi.sendMessage({
+                customType: CONTEXT_INTRO_CUSTOM_TYPE,
+                content: buildContextIntro(nodeId),
+                display: true,
+            });
+        }
+        catch {
+            // Best-effort: a failure here must never break session startup.
+            return;
+        }
+    });
+}
+export default registerCanvasContextIntro;

package/dist/pi-extensions/canvas-goal-capture.d.ts

@@ -6,6 +6,9 @@ interface InputEventLike {
 }
 interface PiLike {
     on: (event: 'input', handler: (event: InputEventLike, ctx: any) => void) => void;
+    /** Update the live session display name (pi's editor label). Present in
+     *  interactive mode; optional so the extension stays inert where it's not. */
+    setSessionName?: (name: string) => void;
 }
 /**
  * Register the goal-capture handler on `pi`.

package/dist/pi-extensions/canvas-goal-capture.js

@@ -19,6 +19,8 @@
 // Plain TS-with-types — no imports from @earendil-works/* so this compiles inside
 // crouter's own tsc build without a dep on the pi packages.
 import { captureGoalIfAbsent, REVIVE_KICKOFF_SENTINEL } from '../core/runtime/kickoff.js';
+import { generateAndPersistName } from '../core/runtime/naming.js';
+import { editorLabel } from '../core/canvas/index.js';
 /**
  * Register the goal-capture handler on `pi`.
  *
@@ -43,7 +45,19 @@ export function registerCanvasGoalCapture(pi) {
             // masquerade as the user's first mandate.
             if (text.startsWith(REVIVE_KICKOFF_SENTINEL))
                 return;
-            captureGoalIfAbsent(nodeId, text);
+            // First mandate for a bare root: persist it as the goal, and ask pi
+            // (async, non-blocking) to name the session from it. The name lands on
+            // meta.description; the onNamed callback pushes the new editor label into
+            // THIS live session via setSessionName, so it updates immediately instead
+            // of only on the next cycle.
+            if (captureGoalIfAbsent(nodeId, text)) {
+                generateAndPersistName(nodeId, text, (meta) => {
+                    try {
+                        pi.setSessionName?.(editorLabel(meta));
+                    }
+                    catch { /* best-effort */ }
+                });
+            }
         }
         catch {
             // Best-effort: a capture failure must never drop or alter the message.

package/dist/pi-extensions/canvas-inbox-watcher.js

@@ -32,6 +32,7 @@
 // Plain TS-with-types — no imports from @earendil-works/* so this compiles inside
 // crouter's own tsc build without a dep on the pi packages.
 import { readInboxSince, readCursor, writeCursor, coalesce, } from '../core/feed/inbox.js';
+import { getNode } from '../core/canvas/index.js';
 // ---------------------------------------------------------------------------
 // Module-level timer — prevents stacking on /reload (the double-notify bug).
 //
@@ -179,6 +180,16 @@ export function registerCanvasInboxWatcher(pi) {
                 seeded = true;
             }
             const newEntries = readInboxSince(nodeId, cursor);
+            // Refresh-yield in flight: the node ran `crtr node yield` and is about to be
+            // torn down and revived fresh. Hold everything — don't consume the cursor
+            // (advancing it past these entries would drop them on tear-down) and don't
+            // deliver (steering a child's `final` into the yielding turn hijacks the
+            // clean stop the refresh path depends on, which is how a yield got derailed
+            // mid-flight). The fresh pi re-reads the feed on boot. getNode only when
+            // there's actual work pending, so idle ticks stay cheap.
+            if ((newEntries.length > 0 || buffer.length > 0) && getNode(nodeId)?.intent === 'refresh') {
+                return;
+            }
             if (newEntries.length > 0) {
                 // Advance and persist the cursor BEFORE buffering, so a crash after this
                 // point loses at most one coalesced message rather than re-injecting