@north-light/crouter 0.3.154

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

@@ -0,0 +1,230 @@
+// 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). EVERY node
+// also gets a `<memory kind="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. (Preferences surface as their own `<memory kind="preference">`
+// 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).
+//
+// IDEMPOTENT across resumes, but FORK-AWARE and BRANCH-AWARE: the idempotency
+// scan walks only the ACTIVE BRANCH (root-first from the current leaf), not
+// every entry in the file. A `--session` relaunch that is a true resume keeps
+// the same branch, so the scan finds OUR prior bearings (named by OUR node id)
+// and skips — it never accumulates. A post-yield CYCLE roots a fresh branch (the
+// `crtr-cycle` marker), so the scan correctly finds nothing on that fresh branch
+// and injects a new intro, even though an OLDER cycle's intro still sits
+// elsewhere in the same `.jsonl`. A `--fork-from` boot COPIES the source node's
+// whole conversation onto ITS OWN branch (bearings naming the SOURCE's node id,
+// not ours), 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 on the
+// active branch (exact `details.nodeId` stamp, content-match fallback),
+// otherwise it injects ours — whose identity assertion (leading the
+// <crtr-bearings> 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
+// 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, CONTEXT_INTRO_CUSTOM_TYPE } from '../core/runtime/bearings.js';
+import { isWarmSpare } from '../core/canvas/index.js';
+/** The `customType` stamped on the injected session message. Used both to write
+ *  the entry and to detect it on resume (the idempotency guard). Defined beside
+ *  the block builder in `core/runtime/bearings.ts` because the warm-pool claim's
+ *  live delivery needs it too; re-exported here as this module's own surface. */
+export { CONTEXT_INTRO_CUSTOM_TYPE };
+// ---------------------------------------------------------------------------
+// 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');
+}
+/** 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. */
+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
+            // An UNCLAIMED warm spare gets no bearings. Nobody owns this conversation
+            // yet, so a block built now would assert the spare's placeholder persona
+            // (always `general`/`base`) and snapshot the repo as it looks at MINT
+            // time. The claim builds and delivers the real one over the broker once
+            // the row wears its claimant's kind/mode/name (`deliver-live.ts`), which
+            // still lands first in this session because nobody has spoken in it. A
+            // later revive of the claimed node re-injects nothing: the delivered block
+            // carries the same `details.nodeId` stamp the guard below matches on.
+            if (isWarmSpare(nodeId))
+                return;
+            // Branch-aware idempotency: scan only the ACTIVE branch (root-first from
+            // the current leaf), not every entry in the file. A post-yield cycle roots a
+            // FRESH branch (the crtr-cycle marker), so scanning the whole file would
+            // find a PRIOR cycle's intro and wrongly skip injecting this cycle's own —
+            // the node's first turn would lack its crtr-context bearings entirely.
+            // Falls back to a whole-file scan only if the engine doesn't expose
+            // getBranch (older/degraded engine). Not fooled by a FORK either way: a
+            // `--fork-from` boot copies the source's whole conversation onto ITS OWN
+            // branch (bearings naming the SOURCE's 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 on the scanned
+            // branch. 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 scan = typeof ctx.sessionManager.getBranch === 'function'
+                ? ctx.sessionManager.getBranch()
+                : ctx.sessionManager.getEntries();
+            const ours = scan.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 `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 {
+            // Best-effort: a failure here must never break session startup.
+            return;
+        }
+    });
+}
+export default registerCanvasContextIntro;

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 pi hooks on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent — a non-canvas pi
+ * session gets no hooks. 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,151 @@
+// canvas-doc-substrate.ts — the document substrate's pi 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, src/core/runtime/launch.ts). 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 pi hooks:
+//
+//   1. before_agent_start — the BOOT system-prompt half. Splices the rendered
+//      `<memory kind="preference">` block (memory-usage guidance + preferences)
+//      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. (The `<memory kind="knowledge">`
+//      catalog rides the 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
+//      (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, } from '../core/substrate/index.js';
+import { clearSessionCache } from '../core/substrate/session-cache.js';
+import { loadInjectedDocs, saveInjectedDocs } from '../core/substrate/injected-store.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 memory docs/preferences must sit
+ *  there, not far below. Mirrors crouter-help.ts. Falls back to appending if absent. */
+const TOOLS_ANCHOR = '\n\nGuidelines:';
+const AUTO_CONTEXT_RE = /<auto-loaded-context(?:\s[^>]*)?>\n([\s\S]*?)\n<\/auto-loaded-context>/;
+function mergeAutoLoadedContext(injected, content) {
+    const match = injected.match(AUTO_CONTEXT_RE);
+    const inner = match?.[1]?.trim();
+    if (!inner)
+        return content;
+    const existingText = content.map((block) => block.text ?? '').join('\n');
+    if (existingText.includes(inner))
+        return content;
+    const existingIdx = content.findIndex((block) => typeof block.text === 'string' && AUTO_CONTEXT_RE.test(block.text));
+    if (existingIdx !== -1) {
+        return content.map((block, idx) => {
+            if (idx !== existingIdx || typeof block.text !== 'string')
+                return block;
+            return {
+                ...block,
+                text: block.text.replace(AUTO_CONTEXT_RE, (_whole, current) => {
+                    const trimmed = String(current).trim();
+                    return `<auto-loaded-context>\n${inner}${trimmed === '' ? '' : `\n${trimmed}`}\n</auto-loaded-context>`;
+                }),
+            };
+        });
+    }
+    return [{ type: 'text', text: `<auto-loaded-context>\n${inner}\n</auto-loaded-context>` }, ...content];
+}
+/**
+ * Register the document substrate's pi hooks on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent — a non-canvas pi
+ * session gets no hooks. 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-TRANSCRIPT set of injected doc realpaths → a doc surfaces at most once
+    // across the node's conversation, EVEN across a dormancy → revive(resume)
+    // 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 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
+        // corpus is re-scanned, picking up memory writes). injectedDocs is
+        // transcript-scoped, not session-scoped — deliberately NOT cleared here.
+        clearSessionCache();
+    });
+    // 1. BOOT system-prompt half — splice the `<memory kind="preference">` block
+    //    (memory-usage guidance + preferences). The guidance frame is always
+    //    present for a canvas node (the memory system always exists), so the block
+    //    is never empty even when no preference is eligible. (The knowledge catalog
+    //    no longer enters the system prompt — it rides the bearings message via
+    //    renderKnowledgeBlock.)
+    pi.on('before_agent_start', (event) => {
+        try {
+            const block = renderPreferencesSection(nodeId);
+            if (block === '')
+                return; // nothing eligible — leave the prompt untouched
+            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
+            // A doc surfaced → renderOnReadDocs grew injectedDocs; persist the set so
+            // the dedup survives a later dormancy → revive(resume).
+            saveInjectedDocs(nodeId, injectedDocs);
+            // Fold into any existing auto-loaded-context block from sibling read hooks;
+            // otherwise prepend one quiet block ahead of the file contents.
+            return { content: mergeAutoLoadedContext(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-goal-capture.d.ts

@@ -0,0 +1,21 @@
+interface InputEventLike {
+    type: 'input';
+    text: string;
+    images?: unknown[];
+    source: 'interactive' | 'rpc' | 'extension';
+}
+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`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent. The `input` handler
+ * is the whole extension: on the first interactive message of a goal-less node,
+ * persist it as the goal.
+ */
+export declare function registerCanvasGoalCapture(pi: PiLike): void;
+export default registerCanvasGoalCapture;

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

@@ -0,0 +1,83 @@
+// canvas-goal-capture.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).
+//
+// Two first-message jobs, both keyed off the node's first real `input` event:
+//
+//   1. Goal capture (bare roots). A node spawned with a prompt has its goal
+//      persisted at birth (writeGoal in spawn.ts). A bare root (`crtr` with no
+//      prompt) starts goal-less — its mandate only arrives when the human types
+//      their first message; this persists that as context/initial-prompt.md.
+//      Guarded so later messages never clobber it.
+//
+//   2. Naming (every node). Naming is async + event-driven — it does NOT run on
+//      the spawn path (that blocking LLM call froze the caller's terminal for
+//      2-3s on every spawn). On the first real message, if the node has no name
+//      yet, ask pi headlessly (async, non-blocking) for a kebab-case name and
+//      live-update the editor label. The first message may be a human's line OR
+//      a delegated child's kickoff task — naming off the agent prompt is fine.
+//
+// Both skip extension-injected messages (inbox wakes, steering) and the
+// fresh-revive kickoff (its sentinel), so neither is mistaken for a first input.
+//
+// Pure observation — it writes the goal file as a side effect and always lets
+// the message through unchanged (returns nothing ⇒ continue). Registered before
+// canvas-passive-context so it reads the raw user text, not a backlog-prepended
+// transform.
+//
+// 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-persist.js';
+import { editorLabel, getNode } from '../core/canvas/index.js';
+/**
+ * Register the goal-capture handler on `pi`.
+ *
+ * Returns immediately (inert) when CRTR_NODE_ID is absent. The `input` handler
+ * is the whole extension: on the first interactive message of a goal-less node,
+ * persist it as the goal.
+ */
+export function registerCanvasGoalCapture(pi) {
+    pi.on('input', (event) => {
+        try {
+            const nodeId = process.env['CRTR_NODE_ID'];
+            if (nodeId === undefined || nodeId.trim() === '')
+                return; // not a canvas node
+            const text = (event.text ?? '').trim();
+            if (text === '')
+                return;
+            // Never seed a mandate or a name from an extension-injected message (inbox
+            // wakes, steering nudges) or a fresh-revive kickoff (the node is already
+            // named). Both would otherwise masquerade as the node's first real input.
+            if (event.source === 'extension')
+                return;
+            if (text.startsWith(REVIVE_KICKOFF_SENTINEL))
+                return;
+            // Goal capture is bare-root only: a delegated child already had its goal
+            // persisted at birth (writeGoal), so only a genuine human-typed prompt
+            // seeds a mandate here.
+            if (event.source === 'interactive')
+                captureGoalIfAbsent(nodeId, text);
+            // Naming: name the node from its FIRST real message — a human's first line
+            // OR a delegated child's kickoff task (naming off the agent prompt is
+            // fine) — whenever it has no name yet. Async headless `pi -p` with no
+            // canvas extensions, so it never recurses into another spawn/name. The
+            // onNamed callback live-updates THIS session's label instead of waiting
+            // for the next cycle. The unnamed-guard keeps it to one call per node.
+            const meta = getNode(nodeId);
+            if (meta !== null && (meta.description ?? '').trim() === '') {
+                generateAndPersistName(nodeId, text, (named) => {
+                    try {
+                        pi.setSessionName?.(editorLabel(named));
+                    }
+                    catch { /* best-effort */ }
+                });
+            }
+        }
+        catch {
+            // Best-effort: a capture failure must never drop or alter the message.
+        }
+    });
+}
+export default registerCanvasGoalCapture;

package/dist/pi-extensions/canvas-inbox-watcher.d.ts

@@ -0,0 +1,25 @@
+type PiEvents = 'session_start' | 'turn_end' | 'agent_start' | 'agent_end' | 'agent_settled' | 'session_shutdown';
+interface PiLike {
+    on: (event: PiEvents, handler: (event: any, ctx: any) => void | Promise<void>) => void;
+    sendUserMessage: (content: string, options?: {
+        deliverAs?: 'steer' | 'followUp';
+    }) => void;
+    sendMessage: (message: {
+        customType: string;
+        content: string;
+        display?: boolean;
+        details?: Record<string, unknown>;
+    }, options?: {
+        deliverAs?: 'steer' | 'followUp' | 'nextTurn';
+        triggerTurn?: boolean;
+    }) => void;
+}
+/** Register one current watcher. `start()` only wires up pi's event handlers —
+ *  it calls no Pi action, so this is safe to run during extension factory
+ *  execution, before Pi has bound its action methods (sendUserMessage /
+ *  sendMessage throw until then). The watcher only starts polling and sending
+ *  once its own `session_start` handler fires and arms it — the first event
+ *  Pi emits once actions are bound. The returned disposer owns only this
+ *  registration's generation. */
+export declare function registerCanvasInboxWatcher(pi: PiLike): () => void;
+export default registerCanvasInboxWatcher;