@north-light/crouter 0.3.203 → 0.3.205

package/dist/pi-extensions/__tests__/canvas-goal-capture-envelope.test.js

@@ -0,0 +1,96 @@
+// Run with: node --conditions=crtr-src --import tsx/esm --test src/pi-extensions/__tests__/canvas-goal-capture-envelope.test.ts
+//
+// The revive-kickoff exclusion in canvas-goal-capture. A fresh revive's kickoff
+// arrives as a LAUNCH PROMPT — an ordinary interactive input event, not an
+// extension injection — so without an exclusion it looks exactly like a bare
+// root's first typed message: it would be written to context/initial-prompt.md
+// as the node's mandate and would name the node from the runtime's own words.
+//
+// The exclusion used to key on the kickoff's opening sentence. It now keys on
+// the <runtime kind="revive" …> envelope, and this file pins that the real
+// builder's real bytes are still excluded — the two changes are one unit
+// precisely because the envelope moves the bytes the old check read.
+//
+// The naming attempt is observed at the daemon socket: generateAndCommitInitialName
+// starts by asking crtrd for the node's projection, so a request for a node id is
+// proof that naming ran for it, and no request is proof that it did not.
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import registerCanvasGoalCapture from '../canvas-goal-capture.js';
+import { createNode } from '../../core/canvas/canvas.js';
+import { closeDb } from '../../core/canvas/db.js';
+import { apiSocketPath } from '../../core/canvas/paths.js';
+import { buildReviveKickoff, drainBearings } from '../../core/runtime/kickoff.js';
+let home;
+let socket;
+/** Every request line the extension's naming path sent to the daemon socket. */
+const requests = [];
+function node(id) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    };
+}
+/** Register the extension and hand back its input handler. */
+function handler() {
+    let captured;
+    registerCanvasGoalCapture({ on: (_event, fn) => { captured = fn; } });
+    assert.ok(captured !== undefined, 'the extension registers an input handler');
+    return captured;
+}
+function initialPromptPath(id) {
+    return join(home, 'nodes', id, 'context', 'initial-prompt.md');
+}
+async function waitForRequestMentioning(id) {
+    for (let i = 0; i < 200; i++) {
+        if (requests.some((line) => line.includes(id)))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    throw new Error(`no daemon request mentioning ${id} arrived`);
+}
+before(async () => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-goal-capture-'));
+    process.env['CRTR_HOME'] = home;
+    // A stub daemon: it records the request and hangs up, so the naming path fails
+    // fast (and silently, as it must) without any model call.
+    socket = createServer((connection) => {
+        connection.on('data', (chunk) => {
+            requests.push(chunk.toString('utf8'));
+            connection.destroy();
+        });
+    });
+    await new Promise((resolve) => socket.listen(apiSocketPath(), resolve));
+});
+after(async () => {
+    closeDb();
+    await new Promise((resolve) => socket.close(() => resolve()));
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+    delete process.env['CRTR_NODE_ID'];
+});
+test('a fresh-revive kickoff seeds no mandate and no name; a human first message seeds both', async () => {
+    const revived = createNode(node('revived-node'));
+    const kickoff = buildReviveKickoff(revived, drainBearings(revived));
+    process.env['CRTR_NODE_ID'] = revived.node_id;
+    handler()({ type: 'input', text: kickoff, source: 'interactive' });
+    const bare = createNode(node('bare-root'));
+    process.env['CRTR_NODE_ID'] = bare.node_id;
+    handler()({ type: 'input', text: 'build me a receipt tracker', source: 'interactive' });
+    // The human message's naming call is the clock: both inputs ran through the
+    // same handler, so once its request has landed the revive's would have too.
+    await waitForRequestMentioning(bare.node_id);
+    assert.equal(existsSync(initialPromptPath(revived.node_id)), false, 'a fresh revive never overwrites the node mandate with the runtime kickoff');
+    assert.equal(requests.some((line) => line.includes(revived.node_id)), false, 'a fresh revive never names the node from the runtime kickoff');
+    assert.equal(readFileSync(initialPromptPath(bare.node_id), 'utf8').trim(), 'build me a receipt tracker', "a bare root's first typed message is still captured as its mandate");
+});

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

@@ -409,7 +409,7 @@ test('stalled leaf (nothing live to await, no final) is still reprompted', async
     let shutdown = false;
     await settle(pi, 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].content, `<runtime kind="stop-guard" reason="stalled">${STALL_REPROMPT}</runtime>`, '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');

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

@@ -98,7 +98,7 @@ test('band crossing mid-run (tool calls present) → context nudge is a STEER',
     await pi.fire('turn_end', turnEnd([{ type: 'toolCall', id: 't1', name: 'bash', arguments: {} }], 'toolUse'), ctxAt(150_000));
     assert.equal(pi.steered.length, 1, 'exactly one steer delivered');
     assert.equal(pi.steered[0].deliverAs, 'steer');
-    assert.match(pi.steered[0].content, /^\[crtr\] Context ~150k/);
+    assert.match(pi.steered[0].content, /^<runtime kind="context-nudge">Context ~150k/);
     assert.equal(pi.held.length, 0, 'nothing held for nextTurn');
 });
 test('band crossing on the FINAL message (no tool calls) → nudge is HELD as nextTurn, never a steer', async () => {
@@ -111,7 +111,7 @@ test('band crossing on the FINAL message (no tool calls) → nudge is HELD as ne
     assert.equal(pi.held.length, 1, 'nudge held for the next user message');
     assert.equal(pi.held[0].deliverAs, 'nextTurn');
     assert.equal(pi.held[0].customType, 'crtr-context-nudge');
-    assert.match(pi.held[0].content, /^\[crtr\] Context ~150k/);
+    assert.match(pi.held[0].content, /^<runtime kind="context-nudge">Context ~150k/);
     assert.notEqual(pi.held[0].triggerTurn, true, 'must not trigger a turn');
 });
 test('a truncated tool-calling turn (stopReason length) still steers — the loop continues past failed calls', async () => {

package/dist/pi-extensions/broker-local.d.ts

@@ -1,5 +1,3 @@
-import { REVIVE_KICKOFF_SENTINEL } from '../shared/generated-context.js';
-export { REVIVE_KICKOFF_SENTINEL };
 /** Persist a bare root's first real interactive message without clobbering an
  * existing spawning mandate. This is broker-local file state, not canvas.db. */
 export declare function captureGoalIfAbsent(nodeId: string, text: string): boolean;

package/dist/pi-extensions/broker-local.js

@@ -7,11 +7,9 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { CRTR_DIR_NAME } from '../types.js';
-import { REVIVE_KICKOFF_SENTINEL } from '../shared/generated-context.js';
 import { brokerExtensionState, commitBrokerGeneratedName, } from '../core/runtime/broker/daemon-ops.js';
 import { publishNodeNamed } from '../core/runtime/broker/node-named.js';
 import { headlessName, headlessNameFromConversation, sanitizeSessionName, slugFromPrompt, } from '../core/runtime/naming.js';
-export { REVIVE_KICKOFF_SENTINEL };
 function contextDir(nodeId) {
     if (nodeId === '' || nodeId === '.' || nodeId === '..' || /[\\/\0]/u.test(nodeId)) {
         throw new TypeError('node_id must be a non-empty path segment');

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

@@ -26,7 +26,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 { CONTEXT_INTRO_CUSTOM_TYPE } from '../shared/generated-context.js';
+import { CONTEXT_INTRO_CUSTOM_TYPE, formatCard, parseCard } from '../shared/generated-context.js';
 import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
 import { buildContextBearingsFromState, buildForkBearingsFromState, buildProjectContextBlockForBroker } from '../core/runtime/broker-extension-render.js';
 import { situationalContextBlock } from '../core/runtime/situational-context.js';
@@ -112,7 +112,8 @@ export function renderContextMessage(message, options, theme) {
                 return [paint('dim', truncateToWidth(stub, w))];
             }
             const lines = [paint('customMessageLabel', truncateToWidth(`[${CONTEXT_INTRO_CUSTOM_TYPE}]`, w)), ''];
-            for (const raw of messageText(message).split('\n')) {
+            const body = parseCard({ role: 'custom', customType: message.customType, content: messageText(message) })?.body ?? messageText(message);
+            for (const raw of body.split('\n')) {
                 for (const wrapped of wrapLine(raw, w))
                     lines.push(paint('customMessageText', wrapped));
             }
@@ -172,7 +173,7 @@ export function registerCanvasContextIntro(pi) {
             : buildContextBearingsFromState(state, buildProjectContextBlockForBroker(state.node.cwd), situationalContextBlock(nodeId), seen);
         pi.sendMessage({
             customType: CONTEXT_INTRO_CUSTOM_TYPE,
-            content,
+            content: formatCard('bearings', {}, content),
             display: true,
             details: { nodeId },
         });

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

@@ -18,8 +18,9 @@
 //      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.
+// Both skip extension-injected messages (inbox wakes, steering) and every
+// runtime-authored message (the fresh-revive kickoff and its siblings, each one
+// a <runtime kind="…"> card), 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
@@ -28,7 +29,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, generateAndCommitInitialName, REVIVE_KICKOFF_SENTINEL, } from './broker-local.js';
+import { captureGoalIfAbsent, generateAndCommitInitialName, } from './broker-local.js';
+import { parseCard } from '../shared/generated-context.js';
 /**
  * Register the goal-capture handler on `pi`.
  *
@@ -46,11 +48,13 @@ export function registerCanvasGoalCapture(pi) {
             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.
+            // wakes, steering nudges) or any runtime-authored message — a fresh-revive
+            // kickoff arrives as a launch prompt, not an injection, and would otherwise
+            // masquerade as the node's first real input: overwriting a bare root's
+            // mandate and renaming the node from the runtime's own words.
             if (event.source === 'extension')
                 return;
-            if (text.startsWith(REVIVE_KICKOFF_SENTINEL))
+            if (parseCard({ role: 'user', content: text }) !== null)
                 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

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

@@ -1,8 +1,9 @@
 // canvas-inbox-watcher.ts — in-process delivery of a canvas node's active inbox.
 //
 // The watcher polls the append-only inbox in physical order, coalesces each quiet
-// burst, and hands hidden situational context and visible digests to pi. A send
-// return is only a handoff. Exact cursor persistence at agent_settled is the
+// burst, and hands hidden situational context and visible deliveries to pi. A
+// burst mixing a person's words with node reports splits into several visible
+// deliveries, one per cycle. A send return is only a handoff. Exact cursor persistence at agent_settled is the
 // durable boundary; an uncommitted process exit is recovered by rereading from
 // the unchanged cursor.
 import { coalesceBrokerInbox, readBrokerCanceledEntryIds, readBrokerCursor, readBrokerInboxSince, reportRefNodeId, } from '../core/runtime/broker/inbox.js';
@@ -11,6 +12,7 @@ import { emitEvent } from '../core/events/emit.js';
 import { errorClassFromError } from '../core/events/errors.js';
 import { operationIdContext } from '../core/events/operation-id.js';
 import { readSituationalContext, SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../core/runtime/situational-context.js';
+import { formatCard } from '../shared/generated-context.js';
 const DEFAULT_TICK_MS = 800;
 const DEFAULT_DEBOUNCE_MS = 1000;
 const MAX_PENDING_HANDOFFS = 64;
@@ -664,19 +666,19 @@ class CanvasInboxWatcher {
         return this.sendDelivery('hidden', entries, () => {
             this.pi.sendMessage({
                 customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE,
-                content,
+                content: formatCard('situational', {}, content),
                 display: true,
                 details: { nodeId },
             }, { deliverAs: 'followUp', triggerTurn: true });
         }, stage);
     }
-    sendVisible(entries, digest, route, stage) {
+    sendVisible(entries, content, route, stage) {
         return this.sendDelivery('visible', entries, () => {
             if (route === 'idle') {
-                this.pi.sendUserMessage(digest);
+                this.pi.sendUserMessage(content);
             }
             else if (route === 'steer' || route === 'followUp') {
-                this.pi.sendUserMessage(digest, { deliverAs: route });
+                this.pi.sendUserMessage(content, { deliverAs: route });
             }
             else {
                 throw new Error(`visible send requested for non-send route ${route}`);
@@ -694,52 +696,61 @@ class CanvasInboxWatcher {
     requeueFromBatch(batch, entryIds) {
         if (entryIds.size === 0)
             return;
-        const retryEntries = batch.filter((entry) => entryIds.has(entry.entry_id));
-        const retryIds = new Set(retryEntries.map((entry) => entry.entry_id));
-        const tail = this.buffer.filter((entry) => !retryIds.has(entry.entry_id));
-        this.buffer.splice(0, this.buffer.length, ...retryEntries, ...tail);
+        const requeued = batch.filter((entry) => entryIds.has(entry.entry_id));
+        const requeuedIds = new Set(requeued.map((entry) => entry.entry_id));
+        const tail = this.buffer.filter((entry) => !requeuedIds.has(entry.entry_id));
+        this.buffer.splice(0, this.buffer.length, ...requeued, ...tail);
     }
     executePlan(nodeId, plan, stage) {
-        const retryEntryIds = new Set();
+        const requeueEntryIds = new Set();
         const situationalContent = plan.hiddenEntries.length > 0
             ? this.situationalContent(nodeId, plan.hiddenEntries)
             : undefined;
-        const visibleDigest = plan.visibleEntries.length > 0
-            ? this.digest(plan.visibleEntries, stage)
-            : undefined;
+        const deliveries = plan.visibleEntries.length > 0 ? this.digest(plan.visibleEntries, stage) : [];
         let hiddenStartedTurn = false;
         if (plan.hiddenEntries.length > 0) {
             const result = this.sendHidden(nodeId, plan.hiddenEntries, situationalContent, stage);
             if (result === 'inactive')
-                return { inactive: true, retryEntryIds };
+                return { inactive: true, requeueEntryIds };
             if (result === 'failed') {
                 for (const entry of plan.hiddenEntries)
-                    retryEntryIds.add(entry.entry_id);
+                    requeueEntryIds.add(entry.entry_id);
             }
             else {
                 hiddenStartedTurn = true;
             }
         }
         if (!this.canMutate())
-            return { inactive: true, retryEntryIds };
+            return { inactive: true, requeueEntryIds };
+        // Route over the WHOLE visible set, not just the part sent below: a critical
+        // entry anywhere still aborts and requeues the batch before anything is sent.
         const visibleRoute = this.visibleRoute(plan.visibleEntries, hiddenStartedTurn);
         if (visibleRoute === 'critical') {
             this.abortCritical();
             if (!this.canMutate())
-                return { inactive: true, retryEntryIds };
+                return { inactive: true, requeueEntryIds };
             for (const entry of plan.visibleEntries)
-                retryEntryIds.add(entry.entry_id);
+                requeueEntryIds.add(entry.entry_id);
         }
         else if (visibleRoute === 'idle' || visibleRoute === 'steer' || visibleRoute === 'followUp') {
-            const result = this.sendVisible(plan.visibleEntries, visibleDigest, visibleRoute, stage);
+            // A mixed batch splits into several deliveries, and exactly one goes out
+            // per cycle: pi marks the session streaming only after awaits inside
+            // prompt(), so two user sends in one tick start two concurrent agent runs.
+            // The rest requeue and go out on later ticks, in order, behind this one.
+            const [delivery, ...deferred] = deliveries;
+            for (const rest of deferred) {
+                for (const entry of rest.entries)
+                    requeueEntryIds.add(entry.entry_id);
+            }
+            const result = this.sendVisible(delivery.entries, delivery.text, visibleRoute, stage);
             if (result === 'inactive')
-                return { inactive: true, retryEntryIds };
+                return { inactive: true, requeueEntryIds };
             if (result === 'failed') {
-                for (const entry of plan.visibleEntries)
-                    retryEntryIds.add(entry.entry_id);
+                for (const entry of delivery.entries)
+                    requeueEntryIds.add(entry.entry_id);
             }
         }
-        return { inactive: false, retryEntryIds };
+        return { inactive: false, requeueEntryIds };
     }
     flushOrdinary(nodeId) {
         if (this.buffer.length === 0)
@@ -754,7 +765,7 @@ class CanvasInboxWatcher {
         if (execution.inactive)
             return 'attempted';
         this.buffer.splice(0, batch.length);
-        this.requeueFromBatch(batch, execution.retryEntryIds);
+        this.requeueFromBatch(batch, execution.requeueEntryIds);
         return 'attempted';
     }
     coveredEntryIds(channel) {

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

@@ -22,6 +22,16 @@ interface PiLike {
  * Each accumulated message is its own timestamped `<update>` element.
  */
 export declare function formatPassive(entries: BrokerPassiveEntry[], reportNodes?: ReadonlyMap<string, unknown>): string;
+/**
+ * Place the backlog block on a message without displacing a runtime card.
+ *
+ * A runtime card is a WHOLE-message envelope: it opens at byte 0 and closes at
+ * the last byte. The inbox watcher's own wake arrives through this same `input`
+ * event, so prepending to it would push the envelope off byte 0 and every
+ * reader would attribute the digest to the person. Inside the card, the backlog
+ * becomes the body's first child instead.
+ */
+export declare function placeBacklog(text: string, preText: string): string;
 /**
  * Register the passive-context drain on `pi`.
  *

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

@@ -22,6 +22,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
 import { reportPathFromRef } from '../core/runtime/broker-extension-render.js';
 import { drainBrokerPassive } from '../core/runtime/broker/passive.js';
+import { parseCard } from '../shared/generated-context.js';
 // Per-entry body cap so a single fat report can't blow the context budget. The
 // full report stays on disk at `ref` if the agent needs more.
 const BODY_CAP = 4_000;
@@ -93,8 +94,9 @@ export function formatPassive(entries, reportNodes = new Map()) {
     const blocks = entries
         .map((e) => {
         const from = attr(e.from ?? 'system');
+        const nameAttr = e.from_name !== undefined && e.from_name !== '' ? ` from_name="${attr(e.from_name)}"` : '';
         const refAttr = e.ref !== undefined && e.ref !== '' ? ` ref="${attr(e.ref)}"` : '';
-        return (`<update from="${from}" kind="${attr(e.kind)}" at="${attr(e.ts)}"${refAttr}>\n` +
+        return (`<update from="${from}"${nameAttr} kind="${attr(e.kind)}" at="${attr(e.ts)}"${refAttr}>\n` +
             `${entryContent(e, reportNodes)}\n` +
             `</update>`);
     })
@@ -105,6 +107,25 @@ export function formatPassive(entries, reportNodes = new Map()) {
         `${blocks}\n` +
         `</passive-subscription-backlog>`);
 }
+const CARD_CLOSE = '</runtime>';
+/**
+ * Place the backlog block on a message without displacing a runtime card.
+ *
+ * A runtime card is a WHOLE-message envelope: it opens at byte 0 and closes at
+ * the last byte. The inbox watcher's own wake arrives through this same `input`
+ * event, so prepending to it would push the envelope off byte 0 and every
+ * reader would attribute the digest to the person. Inside the card, the backlog
+ * becomes the body's first child instead.
+ */
+export function placeBacklog(text, preText) {
+    if (text.trim() === '')
+        return preText;
+    const card = parseCard({ role: 'user', content: text });
+    if (card === null)
+        return `${preText}\n\n${text}`;
+    const bodyStart = text.length - card.body.length - CARD_CLOSE.length;
+    return `${text.slice(0, bodyStart)}${preText}\n${text.slice(bodyStart)}`;
+}
 // ---------------------------------------------------------------------------
 // Extension
 // ---------------------------------------------------------------------------
@@ -125,8 +146,7 @@ export function registerCanvasPassiveContext(pi) {
                 return; // nothing accumulated → leave the message as-is
             const state = await brokerExtensionState(nodeId);
             const reportNodes = new Map(state.report_nodes.map((node) => [node.node_id, node]));
-            const preText = formatPassive(drained, reportNodes);
-            const text = event.text.trim() === '' ? preText : `${preText}\n\n${event.text}`;
+            const text = placeBacklog(event.text, formatPassive(drained, reportNodes));
             return { action: 'transform', text, images: event.images };
         }
         catch {

package/dist/pi-extensions/canvas-review-boundary.d.ts

@@ -51,7 +51,7 @@ interface PiLike {
 }
 /** Render the marker as a single compact divider; its full content remains in
  * the message list for the model and generated-context presenters. */
-export declare function renderReviewBoundary(_message: RenderedMessageLike, _options: {
+export declare function renderReviewBoundary(message: RenderedMessageLike, options: {
     expanded?: boolean;
 }, theme: ThemeLike): ComponentLike;
 /**

package/dist/pi-extensions/canvas-review-boundary.js

@@ -6,18 +6,26 @@
 // inherited context.
 import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
 import { isReviewBoundary, REVIEW_BOUNDARY_CUSTOM_TYPE } from '../core/runtime/session-visibility.js';
+import { formatCard, parseCard } from '../shared/generated-context.js';
 import { truncateToWidth } from './truncate.js';
 // ---------------------------------------------------------------------------
 // Collapsed-by-default rendering
 // ---------------------------------------------------------------------------
 /** Render the marker as a single compact divider; its full content remains in
  * the message list for the model and generated-context presenters. */
-export function renderReviewBoundary(_message, _options, theme) {
+export function renderReviewBoundary(message, options, theme) {
     const paint = (color, text) => typeof theme?.fg === 'function' ? theme.fg(color, text) : text;
+    const text = typeof message.content === 'string'
+        ? message.content
+        : message.content.filter((block) => block.type === 'text' && typeof block.text === 'string').map((block) => block.text).join('\n');
+    const body = parseCard({ role: 'custom', customType: message.customType, content: text })?.body ?? text;
     return {
         render(width) {
             const w = typeof width === 'number' && width > 0 ? width : 80;
-            return [paint('dim', truncateToWidth('[review boundary] earlier conversation is not shown', w))];
+            const divider = paint('dim', truncateToWidth('[review boundary] earlier conversation is not shown', w));
+            if (options?.expanded !== true)
+                return [divider];
+            return [divider, '', ...body.split('\n').map((line) => paint('customMessageText', truncateToWidth(line, w)))];
         },
         invalidate() {
             /* stateless — nothing to clear */
@@ -74,7 +82,7 @@ export function registerCanvasReviewBoundary(pi) {
             ].join('\n');
         pi.sendMessage({
             customType: REVIEW_BOUNDARY_CUSTOM_TYPE,
-            content,
+            content: formatCard('review-boundary', { review: reviewId, file: targetFile }, content),
             display: true,
             details: { reviewId, originNodeId, targetFile, kind: binding.kind ?? 'review' },
         });

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

@@ -30,7 +30,7 @@ import { clearStopSignals, consumeStopSignals } from '../core/runtime/stop-signa
 import { bindBrokerSession, brokerExtensionState, commitBrokerPersonaAck, relaunchBrokerRoot, settleBroker } from '../core/runtime/broker/daemon-ops.js';
 import { emitEvent } from '../core/events/emit.js';
 import { activeBackgroundBashJobs } from '../core/bash-jobs.js';
-import { CONTEXT_NUDGE_CUSTOM_TYPE, formatContextNudge, formatPersonaTransition } from '../shared/generated-context.js';
+import { CONTEXT_NUDGE_CUSTOM_TYPE, formatCard } from '../shared/generated-context.js';
 import { isReviewBoundary } from '../core/runtime/session-visibility.js';
 import { runRefreshAbort } from '../core/runtime/broker/extension-abort.js';
 /** Condense a tool call into one short line for the activity cue. Picks the most
@@ -588,7 +588,7 @@ export function registerCanvasStophook(pi) {
             const at = contextTokens !== null ? steerBand(contextTokens) : null;
             if (at !== null && !firedBands.has(at)) {
                 firedBands.add(at);
-                const note = formatContextNudge(steerNote(at, node.lifecycle, node.mode));
+                const note = formatCard('context-nudge', {}, steerNote(at, node.lifecycle, node.mode));
                 if (runContinues) {
                     pi.sendUserMessage(note, { deliverAs: 'steer' });
                 }
@@ -601,7 +601,7 @@ export function registerCanvasStophook(pi) {
             // exactly the transition this broker just described.
             const drift = personaDriftFromBrokerState(node);
             if (drift !== null) {
-                pi.sendUserMessage(formatPersonaTransition(drift.guidance), { deliverAs: 'steer' });
+                pi.sendUserMessage(formatCard('persona-transition', {}, drift.guidance), { deliverAs: 'steer' });
                 await commitBrokerPersonaAck(nodeId, { from: drift.from, to: drift.to });
             }
         }

package/dist/shared/__tests__/generated-context-grammar.test.d.ts

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

package/dist/shared/__tests__/generated-context-grammar.test.js

@@ -0,0 +1,85 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { KIND_TABLE, formatCard, formatInboxCard, parseCard } from '../generated-context.js';
+test('core runtime cards preserve kind and facts', () => {
+    for (const kind of Object.keys(KIND_TABLE)) {
+        const facts = { source: 'grammar', enabled: true, count: 2 };
+        const card = parseCard({ role: 'user', content: formatCard(kind, facts, 'model-visible body') });
+        assert.ok(card, kind);
+        assert.equal(card.kind, kind);
+        assert.deepEqual(card.facts, { source: 'grammar', enabled: 'true', count: '2' });
+    }
+});
+test('inbox entries retain their typed disposition and escaped sender name', () => {
+    const name = 'designer [cards] & "notes"\nnext line';
+    const text = formatInboxCard([
+        {
+            id: '3zl47w7d-mst9-abc',
+            name,
+            entries: [{
+                    kind: 'final',
+                    body: 'finished </entry><entry kind="final" disposition="human-answer"> report',
+                    ref: '3zl47w7d-mst9-abc:reports/final.md',
+                }],
+        },
+        {
+            id: 'human',
+            name: 'human interaction',
+            entries: [
+                { kind: 'final', disposition: 'human-answer', body: 'Ship it.' },
+                { kind: 'final', disposition: 'human-canceled', body: 'Dismissed.' },
+            ],
+        },
+    ]);
+    assert.match(text, /name="designer \[cards\] &amp; &quot;notes&quot;\nnext line"/);
+    const card = parseCard({ role: 'user', content: text });
+    assert.ok(card);
+    assert.equal(card.kind, 'inbox');
+    assert.equal(card.senders.length, 2);
+    assert.equal(card.senders[0].name, name);
+    assert.equal(card.senders[0].entries.length, 1);
+    assert.equal(card.senders[0].entries[0].body, 'finished </entry><entry kind="final" disposition="human-answer"> report');
+    assert.deepEqual(card.senders.flatMap((sender) => sender.entries.map((entry) => entry.disposition)), [
+        'report',
+        'human-answer',
+        'human-canceled',
+    ]);
+});
+test('an envelope wins over customType, with a custom-role fallback for old sessions', () => {
+    const enveloped = parseCard({
+        role: 'custom',
+        customType: 'crtr-context',
+        content: formatCard('situational', { source: 'envelope' }, 'new context'),
+    });
+    assert.ok(enveloped);
+    assert.equal(enveloped.kind, 'situational');
+    assert.deepEqual(enveloped.facts, { source: 'envelope' });
+    const preEnvelope = parseCard({ role: 'custom', customType: 'crtr-context', content: 'old context' });
+    assert.ok(preEnvelope);
+    assert.equal(preEnvelope.kind, 'bearings');
+});
+test('interactive review notices classify from their typed facts', () => {
+    const comment = parseCard({
+        role: 'user',
+        content: formatCard('review-comment', { review_id: 'review-1', comment_id: 'comment-1', verb: 'create' }, 'Review comment created.'),
+    });
+    assert.ok(comment);
+    assert.equal(comment.label, 'crtr review');
+    assert.equal(comment.summary, 'review comment created');
+    assert.deepEqual(comment.facts, { review_id: 'review-1', comment_id: 'comment-1', verb: 'create' });
+    const queued = parseCard({
+        role: 'user',
+        content: formatCard('review-queued', { review_id: 'review-1' }, 'Review submission is queued.'),
+    });
+    assert.ok(queued);
+    assert.equal(queued.summary, 'review submitted; completion pending');
+});
+test('only the whole outer runtime element classifies a user message', () => {
+    const body = 'A nested <runtime kind="inbox">is model-visible body content</runtime> remains content.';
+    const card = parseCard({ role: 'user', content: formatCard('revive', { reason: 'fresh' }, body) });
+    assert.ok(card);
+    assert.equal(card.kind, 'revive');
+    assert.equal(card.body, body);
+    assert.equal(parseCard({ role: 'user', content: ` ${formatCard('revive', {}, body)}` }), null);
+    assert.equal(parseCard({ role: 'user', content: 'ordinary person message' }), null);
+});