@crouton-kit/crouter 0.3.28 → 0.3.29

package/dist/daemon/manage.js

@@ -8,6 +8,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { mkdirSync } from 'node:fs';
 import { crtrHome } from '../core/canvas/paths.js';
+import { hostExecPath } from '../core/runtime/branded-host.js';
 import { isDaemonRunning, readPidfile } from './crtrd.js';
 // ---------------------------------------------------------------------------
 // Entry point resolution
@@ -30,8 +31,12 @@ export function spawnDaemon() {
     }
     // Ensure the canvas home directory exists so the daemon can write its pidfile.
     mkdirSync(crtrHome(), { recursive: true });
+    // Launch from the crouter-branded host binary so the daemon shows "crouter"
+    // in macOS Full Disk Access, not "node" (see branded-host). NOTE: when crtrd
+    // is launchd-owned, the plist's ProgramArguments must point at the branded
+    // binary too — this path only covers a manual `crtr canvas daemon start`.
     const entry = resolveCrtrdEntry();
-    const child = spawn(process.execPath, [entry], {
+    const child = spawn(hostExecPath(), [entry], {
         detached: true,
         stdio: 'ignore',
     });

package/dist/index.js

@@ -10,7 +10,7 @@
 // side effects and no circular imports — keep it that way.
 // ── Runtime control ──────────────────────────────────────────────────────
 // Sanctioned launchers/mutators. reviveNode is the ONLY sanctioned launcher of
-// `pi --session`; spawnChild's host is chosen via `hostKind: 'tmux' | 'broker'`.
+// the broker engine; every node is broker-hosted (no host_kind choice).
 export { spawnChild } from './core/runtime/spawn.js';
 export { reviveNode } from './core/runtime/revive.js';
 export { closeNode } from './core/runtime/close.js';

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

@@ -109,37 +109,42 @@ test('natural stop while awaiting a live worker → idle-release with NO push (n
 // ---------------------------------------------------------------------------
 // §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).
+// cleared in beforeEach). NOTE (broker-host cut): the placement read `focusOf`
+// used by the handler now GC-prunes a viewer row whose pane is not a LIVE tmux
+// pane (liveOrPrune → paneExists), so a fabricated '%pane' id is pruned on the
+// first read. To drive the handler's focus path deterministically in the
+// tmux-free fast tier we register viewer rows with a NULL pane (a registered-
+// but-not-yet-realized viewer, which liveOrPrune passes through). status='done'
+// is reached by setting the runtime row directly (the branch reads
+// getNode(nodeId).status).
 // ---------------------------------------------------------------------------
-test('§5.1.1 truly-done + focused + dormant idle-release manager-not-focused → MANAGER TAKEOVER of the focus row', () => {
+test('§5.1.1 truly-done + focused → focus row CLOSED, NO manager takeover (broker cut deleted handFocusToManager)', () => {
+    // Regression guard for the broker-host cut: the engine is now a detached
+    // broker, not a pane, so there is no engine to hand to a manager. The old
+    // "dormant idle-release manager takes over the finished node's focus row"
+    // path (handFocusToManager) is DELETED — a truly-done focused node just
+    // tearDownNode's its own viewer and shuts down, EVEN when a dormant
+    // idle-release manager exists (the exact case that used to trigger takeover).
     createNode(node('root', { parent: null, lifecycle: 'resident' }));
-    // 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.
+    // M starts WITH a recorded LOCATION so the done-path 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');
+    openFocusRow('fM', null, 'Suser', 'M'); // null pane → focusOf returns it → drives tearDownNode
     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' (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.
-    assert.equal(getFocusByNode('mgr')?.focus_id, 'fM', 'focus row taken over by the manager');
+    // The done branch: focusOf('M') != null → tearDownNode('M') CLOSES fM. The
+    // manager is NOT handed anything (takeover deleted). Non-vacuous: a takeover
+    // impl would leave getFocusByNode('mgr').focus_id === 'fM'.
+    assert.equal(getFocusByNode('mgr'), null, 'the manager is NOT handed the finished node\'s focus (takeover deleted)');
+    assert.equal(getFocusById('fM'), null, 'the finished node\'s viewer focus row is closed');
     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(shutdown, true, 'pi shut down after teardown');
+    // The done node's own presence is nulled (setPresence(null) on the done path).
     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');
 });
@@ -206,7 +211,10 @@ test('§5.1.5 awaiting + FOCUSED → STAY ALIVE: pi keeps running (no release),
     createNode(node('worker', { parent: 'mgr', lifecycle: 'terminal', status: 'active' }));
     subscribe('root', 'mgr', true);
     subscribe('mgr', 'worker', true); // mgr awaits a live worker → would idle-release if UNfocused
-    openFocusRow('fMgr', '%g', 'Suser', 'mgr');
+    // null pane (broker cut): focusOf passes a null-pane viewer row through, so the
+    // handler reads mgr as FOCUSED in the tmux-free fast tier (a fabricated %pane
+    // would be GC-pruned by liveOrPrune and the node would wrongly release).
+    openFocusRow('fMgr', null, 'Suser', 'mgr');
     process.env['CRTR_NODE_ID'] = 'mgr';
     const pi = makeFakePi();
     registerCanvasStophook(pi);

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

@@ -15,11 +15,11 @@
 //
 // 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). EVERY node
-// also gets a `<references>` block rendered from the document substrate —
-// eligible `reference` docs at their system-prompt visibility rung, plus the
+// also gets a `<knowledge>` block rendered from the document substrate —
+// eligible `knowledge` docs at their system-prompt visibility rung, plus the
 // node's own node-local substrate docs — so the bearings name what to read on
-// demand. (Skills and preferences surface as their own `<skills>` /
-// `<preferences>` blocks of the system prompt, not in this block.) An
+// demand. (Preferences surface as their own `<preferences>` block of the
+// system prompt, not in this block.) 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).

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

@@ -9,13 +9,13 @@
 // It owns the substrate's two new pi hooks:
 //
 //   1. before_agent_start — the BOOT system-prompt half. Splices the rendered
-//      `<skills>` + `<preferences>` + `<memory-guidance>` blocks 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.
+//      `<preferences>` + `<memory-guidance>` blocks into `event.systemPrompt`,
+//      right after pi's native "Available tools" list (before the
+//      `\n\nGuidelines:` anchor), so the substrate's standing directives 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. (Knowledge rides the `<crtr-context>`
+//      bearings message instead — see core/substrate/render.ts.)
 //
 //   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
@@ -34,7 +34,7 @@
 // with no dep on the pi packages. Mirrors canvas-context-intro.ts.
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
-import { renderMemoryGuidance, renderOnReadDocs, renderPreferencesSection, renderSkillsSection, } from '../core/substrate/index.js';
+import { renderMemoryGuidance, renderOnReadDocs, renderPreferencesSection, } from '../core/substrate/index.js';
 import { clearSessionCache } from '../core/substrate/session-cache.js';
 import { loadInjectedDocs, saveInjectedDocs } from '../core/substrate/injected-store.js';
 // ---------------------------------------------------------------------------
@@ -61,9 +61,9 @@ export function registerCanvasDocSubstrate(pi) {
     // cycle. A resume reuses the same .jsonl transcript in a NEW pi process, so
     // the set is REHYDRATED from disk at process start (not started empty) and is
     // NOT cleared on session_start — a resume continues the transcript, so the
-    // dedup must carry forward. The launch paths that begin a FRESH transcript
-    // (revive resume=false, reviveInPlace, relaunchRootInPane) delete the file, so
-    // a new conversation rehydrates empty here. See core/substrate/injected-store.ts.
+    // dedup must carry forward. The one launch path that begins a FRESH transcript
+    // (reviveNode with resume=false) deletes the file, so a new conversation
+    // rehydrates empty here. See core/substrate/injected-store.ts.
     const injectedDocs = loadInjectedDocs(nodeId);
     pi.on('session_start', () => {
         // Only the per-session substrate PARSE cache resets each session (so the
@@ -71,14 +71,14 @@ export function registerCanvasDocSubstrate(pi) {
         // transcript-scoped, not session-scoped — deliberately NOT cleared here.
         clearSessionCache();
     });
-    // 1. BOOT system-prompt half — splice `<skills>` + `<preferences>` +
-    //    `<memory-guidance>`. The guidance block is always present for a canvas
-    //    node (the memory system always exists), so the splice is never empty even
-    //    when both trees are.
+    // 1. BOOT system-prompt half — splice `<preferences>` + `<memory-guidance>`.
+    //    The guidance block is always present for a canvas node (the memory system
+    //    always exists), so the splice is never empty even when the preferences
+    //    tree is. (Knowledge no longer enters the system prompt — it rides the
+    //    `<crtr-context>` bearings message via renderKnowledgeBlock.)
     pi.on('before_agent_start', (event) => {
         try {
             const sections = [
-                renderSkillsSection(nodeId),
                 renderPreferencesSection(nodeId),
                 renderMemoryGuidance(),
             ].filter((s) => s !== '');

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

@@ -47,6 +47,7 @@ import { execFile } from 'node:child_process';
 import { fullName } from '../core/canvas/index.js';
 import { beginFrame, cNode, managerOf, liveReports, sortedChildIds, subtreeIds, climbRoot, computeSubtreeActivity, buildGraphModel, renderGraphRow, navLabel, coloredGlyph, truncate, tokensCell, cycleBadge, childBadge, liveBelowBadge, askBadge, activityCell, focusedNodeIds, graphWidgetBudget, fetchAsksMap, shortId, DIM, RESET, BOLD, YELLOW, GRAPH_HINT, } from '../core/canvas/nav-model.js';
 import { readConfig } from '../core/config.js';
+import { onNavRerender } from './widget-order-bus.js';
 // ---------------------------------------------------------------------------
 // Module-level state — persists across /reload so guards don't stack and fold
 // state / current view survive a hot-swap.
@@ -317,6 +318,10 @@ export function registerCanvasNav(pi) {
             render();
         }, RENDER_DEBOUNCE_MS);
     };
+    // Let canvas-recap ask us to re-assert the manager line so its recap card
+    // stays the topmost aboveEditor chrome (pi's widget store is insertion-
+    // ordered; re-setting crtr-managers drops it below crtr-recap).
+    onNavRerender(scheduleRender);
     // -------------------------------------------------------------------------
     // Actions (all shell out; the extension stays tmux/revive-free)
     // -------------------------------------------------------------------------

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

@@ -0,0 +1,37 @@
+interface TextContentLike {
+    type: string;
+    text?: string;
+}
+interface MessageLike {
+    role: string;
+    content: string | TextContentLike[];
+}
+interface SessionEntryLike {
+    type: string;
+    message?: MessageLike;
+}
+interface SessionManagerLike {
+    getEntries(): SessionEntryLike[];
+}
+interface UIContextLike {
+    setWidget(key: string, content: string[] | undefined, options?: {
+        placement?: 'aboveEditor' | 'belowEditor';
+    }): void;
+}
+interface ExtensionCtxLike {
+    ui?: UIContextLike;
+    mode?: string;
+    sessionManager?: SessionManagerLike;
+}
+type PiEvents = 'session_start' | 'input' | 'turn_end' | 'session_shutdown';
+interface PiLike {
+    on(event: PiEvents, handler: (event: any, ctx: ExtensionCtxLike) => void): void;
+}
+/**
+ * Register the inactivity-recap chrome on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent — a plain pi session
+ * or legacy job agent loads it as a no-op.
+ */
+export declare function registerCanvasRecap(pi: PiLike): void;
+export default registerCanvasRecap;

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

@@ -0,0 +1,236 @@
+// canvas-recap.ts — pi extension for pi-native canvas agent nodes.
+//
+// A per-node INACTIVITY RECAP, drawn as the topmost chrome above the editor.
+// When a node has had NO new message (user or assistant) for IDLE_MS (300s by
+// default), it runs Haiku over the literal conversation and pins a terse
+// three-fragment card — goal / doing-now / next — above canvas-nav's manager
+// line. The card disappears the instant the next message arrives, and the idle
+// clock restarts.
+//
+//   trigger/clear are keyed off MESSAGES, not turns-of-work:
+//     • a user `input` event OR an assistant `turn_end` resets the idle clock
+//       and clears any shown recap.
+//     • a single low-rate timer (no busy-loop) checks elapsed-since-last-message
+//       and, on crossing IDLE_MS, generates + shows the recap once.
+//
+//   Haiku input = ALL user + assistant LITERAL text, most-recent within a char
+//   budget. Tool calls, tool results, thinking blocks, and extension-injected
+//   custom messages are excluded (only `message` entries with role user/assistant,
+//   and only their `text` content blocks).
+//
+//   Placement: key `crtr-recap`, placement `aboveEditor`, ordered ABOVE
+//   `crtr-managers` via the widget-order bus (pi's widget store is insertion-
+//   ordered and re-setting moves a key to the bottom; after we paint the recap
+//   we ask canvas-nav to re-assert its manager line, which drops it below us).
+//
+//   Surface gating: shows in BOTH the in-pane pi TUI (mode 'tui') and the
+//   headless broker → attach/web viewers (mode 'print', setWidget broadcasts to
+//   all surfaces). It does NOT gate on mode === 'tui' (that would kill the
+//   headless+attach path). It NO-OPs only when ui/setWidget is unavailable, and
+//   harmlessly in a true one-shot `pi -p` (the unref'd timer never fires before
+//   the process exits, and naming-style one-shots load with --no-extensions).
+//
+// INERT when CRTR_NODE_ID is absent (a plain pi session or legacy job agent).
+//
+// 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 { generateRecap } from '../core/runtime/recap.js';
+import { requestNavRerender } from './widget-order-bus.js';
+// ---------------------------------------------------------------------------
+// Tuning constants
+// ---------------------------------------------------------------------------
+/** No-new-message window before a recap is shown. 300s by default; override with
+ *  CRTR_RECAP_IDLE_MS (for fast runtime verification). */
+function idleMs() {
+    const raw = process.env['CRTR_RECAP_IDLE_MS'];
+    const n = raw !== undefined ? parseInt(raw, 10) : NaN;
+    return Number.isFinite(n) && n > 0 ? n : 300_000;
+}
+/** How often the (single, low-rate) timer checks elapsed-since-last-message.
+ *  Mirrors canvas-nav's ASK_POLL_MS — cheap and tmux/crtr-free. */
+const POLL_MS = 7_000;
+/** Char budget on the conversation fed to Haiku — the model only needs the gist,
+ *  so we keep the MOST-RECENT text within this cap (a recap is about where we
+ *  left off, not the whole history). */
+const CONVO_CHAR_BUDGET = 12_000;
+const WIDGET_KEY = 'crtr-recap';
+// ---------------------------------------------------------------------------
+// Module-level state — persists across /reload so the timer doesn't stack.
+// ---------------------------------------------------------------------------
+/** The one live poll timer. Cleared and replaced on every re-registration. */
+let liveTimer;
+// ---------------------------------------------------------------------------
+// Conversation extraction — literal user+assistant text ONLY.
+// ---------------------------------------------------------------------------
+/** Pull the literal text out of a message's content (string or text blocks),
+ *  dropping non-text blocks (thinking, toolCall, image). */
+function messageText(msg) {
+    const c = msg.content;
+    if (typeof c === 'string')
+        return c.trim();
+    if (!Array.isArray(c))
+        return '';
+    return c
+        .filter((b) => b !== null && typeof b === 'object' && b.type === 'text' && typeof b.text === 'string')
+        .map((b) => (b.text ?? '').trim())
+        .filter((t) => t !== '')
+        .join('\n')
+        .trim();
+}
+/** Concatenate the conversation's user + assistant literal text into a single
+ *  `User:`/`Agent:` transcript, keeping only the MOST-RECENT CONVO_CHAR_BUDGET
+ *  characters. Excludes tool calls/results (role toolResult, plus toolCall/
+ *  thinking content blocks dropped by messageText) and extension-injected
+ *  custom messages (entry.type !== 'message'). Returns '' when there is nothing
+ *  to summarize. */
+function buildConversation(sm) {
+    let entries;
+    try {
+        entries = sm.getEntries();
+    }
+    catch {
+        return '';
+    }
+    const parts = [];
+    for (const e of entries) {
+        if (e.type !== 'message' || e.message === undefined)
+            continue;
+        const role = e.message.role;
+        if (role !== 'user' && role !== 'assistant')
+            continue; // drop toolResult etc.
+        const text = messageText(e.message);
+        if (text === '')
+            continue;
+        parts.push(`${role === 'user' ? 'User' : 'Agent'}: ${text}`);
+    }
+    if (parts.length === 0)
+        return '';
+    const full = parts.join('\n\n');
+    return full.length > CONVO_CHAR_BUDGET ? full.slice(full.length - CONVO_CHAR_BUDGET) : full;
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+/**
+ * Register the inactivity-recap chrome on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent — a plain pi session
+ * or legacy job agent loads it as a no-op.
+ */
+export function registerCanvasRecap(pi) {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId.trim() === '')
+        return; // not a canvas node
+    // Captured on session_start; used by the timer and the message handlers.
+    let ui;
+    let sessionManager;
+    /** Wall-clock of the most recent user/assistant message. The idle clock. */
+    let lastMessageAt = Date.now();
+    /** True while a recap is currently shown (so we generate at most once per
+     *  idle window, and know whether a clear is needed on the next message). */
+    let recapShown = false;
+    /** True while a Haiku generation is in flight (so we don't fire a second). */
+    let generating = false;
+    const canPaint = () => ui !== undefined && typeof ui.setWidget === 'function';
+    const clearRecap = () => {
+        if (!canPaint())
+            return;
+        try {
+            ui.setWidget(WIDGET_KEY, undefined, { placement: 'aboveEditor' });
+        }
+        catch { /* best-effort */ }
+    };
+    /** Render the three fragments as the topmost above-editor card. */
+    const showRecap = (fragments) => {
+        if (!canPaint())
+            return;
+        const labels = ['◷ goal', '· now ', '→ next'];
+        const lines = fragments.slice(0, 3).map((f, i) => `${labels[i] ?? '    '}  ${f}`);
+        if (lines.length === 0)
+            return;
+        try {
+            ui.setWidget(WIDGET_KEY, lines, { placement: 'aboveEditor' });
+        }
+        catch { /* best-effort */ }
+        // Re-assert the manager line BELOW us (pi's widget store is insertion-
+        // ordered; re-setting crtr-managers drops it under crtr-recap).
+        requestNavRerender();
+    };
+    /** A user or assistant message landed: reset the idle clock and clear any
+     *  shown recap (the conversation has moved on). */
+    const onMessage = () => {
+        lastMessageAt = Date.now();
+        if (recapShown) {
+            recapShown = false;
+            clearRecap();
+            requestNavRerender();
+        }
+    };
+    // -------------------------------------------------------------------------
+    // Events
+    // -------------------------------------------------------------------------
+    pi.on('session_start', (_event, ctx) => {
+        ui = ctx.ui;
+        sessionManager = ctx.sessionManager;
+        // Fresh session / hot-swap: start the idle clock now and drop any stale
+        // recap that bled through a /reload.
+        lastMessageAt = Date.now();
+        recapShown = false;
+        generating = false;
+        clearRecap();
+    });
+    pi.on('input', (_event, _ctx) => {
+        // Every user message (any source) is activity — reset + clear.
+        onMessage();
+    });
+    pi.on('turn_end', (_event, _ctx) => {
+        // A completed assistant turn is activity — reset + clear.
+        onMessage();
+    });
+    // -------------------------------------------------------------------------
+    // The single low-rate idle poll — no busy-loop, mirrors canvas-nav's timer.
+    // -------------------------------------------------------------------------
+    if (liveTimer !== undefined)
+        clearInterval(liveTimer);
+    const timer = setInterval(() => {
+        try {
+            if (!canPaint() || sessionManager === undefined)
+                return;
+            if (recapShown || generating)
+                return;
+            if (Date.now() - lastMessageAt < idleMs())
+                return;
+            const convo = buildConversation(sessionManager);
+            if (convo === '')
+                return; // nothing to summarize yet
+            // Snapshot the clock: if a message arrives while Haiku runs, discard the
+            // (now-stale) result instead of painting over the live conversation.
+            const startedAt = lastMessageAt;
+            generating = true;
+            generateRecap(convo, (fragments) => {
+                generating = false;
+                if (lastMessageAt !== startedAt)
+                    return; // a message landed mid-flight
+                if (!canPaint())
+                    return;
+                recapShown = true;
+                showRecap(fragments);
+            });
+            // generateRecap is silent on failure (never calls back), so clear the
+            // in-flight flag after the timeout window even if no callback fires.
+            setTimeout(() => { generating = false; }, 30_000).unref?.();
+        }
+        catch {
+            /* timer is best-effort */
+        }
+    }, POLL_MS);
+    if (typeof timer.unref === 'function')
+        timer.unref();
+    liveTimer = timer;
+    pi.on('session_shutdown', () => {
+        clearInterval(timer);
+        if (liveTimer === timer)
+            liveTimer = undefined;
+    });
+}
+export default registerCanvasRecap;

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

@@ -27,6 +27,7 @@
 // inside crouter's own tsc build without a dep on the pi packages (mirrors
 // canvas-nav.ts / canvas-commands.ts).
 import { execFile } from 'node:child_process';
+import { surfaceTmuxStyleArgs } from '../core/runtime/surface-bg.js';
 /** Single-quote a string for safe interpolation into a `sh -c` command line —
  *  tmux runs the display-popup trailing string through the shell, so a cwd with
  *  spaces or quotes must be escaped. */
@@ -66,7 +67,7 @@ export function registerCanvasResume(pi) {
                 const cwd = shellQuote(process.cwd());
                 const cmd = `crtr canvas browse --return-pane ${origPane} --cwd ${cwd}`;
                 try {
-                    execFile('tmux', ['display-popup', '-E', '-w', '90%', '-h', '85%', cmd], () => { });
+                    execFile('tmux', ['display-popup', '-E', '-w', '90%', '-h', '85%', ...surfaceTmuxStyleArgs(), cmd], () => { });
                 }
                 catch { /* best-effort */ }
                 return;

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

@@ -6,20 +6,22 @@ interface PiLike {
     }) => void;
 }
 /** The nudge text for a crossed band, specialized to the node's (mode,
- *  lifecycle) persona + how far along the escalation it is.
+ *  lifecycle) persona + how far along the escalation it is. `crtr node yield` is
+ *  the single "keep going past this window" verb for every persona: it refreshes
+ *  the node into a clean window against a roadmap, and for a base node
+ *  auto-promotes transparently — so no persona is ever steered at a bare `node
+ *  promote` (which framed promotion as a heavy "become an orchestrator" step and
+ *  bred yield-avoidance).
  *
- *  - orchestrator (terminal OR resident): checkpoint its roadmap and yield
- *    (gently → firmly → pushy). It has a context/roadmap.md to yield against.
- *  - resident/base (root conversation): never promoted, so NO roadmap exists —
- *    steer it to PROMOTE if the chat is growing into a multi-phase job (which
- *    seeds a roadmap), else wrap up / start fresh. Never points at roadmap.md or
- *    a bare `node yield`, which for a roadmap-less root just drops context.
- *  - terminal/base (worker): PROMOTE itself — become an orchestrator — when
- *    work remains, with an "ignore if nearly done, finish with push final" once
- *    it's deeper in.
+ *  - orchestrator (terminal OR resident): checkpoint context/roadmap.md, then
+ *    yield (it already has a roadmap to bring current first).
+ *  - resident/base (root conversation): yield to continue in a fresh window if
+ *    the chat is growing into a job, else wrap up — a root can simply end.
+ *  - terminal/base (worker): yield to continue if work remains, or `push final`
+ *    when close.
  *
- *  At/past 185k every persona goes PUSHY: the context is long enough that
- *  drifting further risks an overflow. */
+ *  The wording strengthens with depth: gentle < 150k → firm < 185k → pushy at/
+ *  past 185k, where drifting further risks an overflow. */
 export declare function steerNote(at: number, lifecycle: string, mode: string): string;
 /**
  * Register the canvas turn_end / agent_end handlers on `pi`.