@north-light/crouter 0.3.203 → 0.3.205

package/dist/core/runtime/broker/fault-retry.js

@@ -5,7 +5,7 @@ import { extractCoolingDeadline } from '../managed-provider-cooling.js';
 import { expandModelCandidates, modelRequestFromConfig, probeRouteAvailability } from '../../model-routes.js';
 import { operationIdContext } from '../../events/operation-id.js';
 import { emitEvent } from '../../events/emit.js';
-import { CONNECTION_FAULT_RECOVERY_BODY, PROVIDER_FAULT_RECOVERY_BODY, formatModelFallbackRecovery } from '../../../shared/generated-context.js';
+import { CONNECTION_FAULT_RECOVERY_BODY, PROVIDER_FAULT_RECOVERY_BODY, formatCard, formatModelFallbackRecovery } from '../../../shared/generated-context.js';
 import { markFatalOnExhaust, nextFaultRetry, policyFor } from '../fault-recovery.js';
 import { parseModelSpec } from '../model-selection.js';
 import { resolveProviderCandidates } from '../../subscription-state.js';
@@ -208,7 +208,12 @@ export class FaultRetry {
                 return;
             if (unconfigured)
                 clearFault(this.deps.nodeId, { link: 'pi→provider' });
-            await operationIdContext.fresh(() => candidateSession.prompt(formatModelFallbackRecovery(currentSpec, resolved, unconfigured ? 'credential' : 'not-found')));
+            await operationIdContext.fresh(() => candidateSession.prompt(formatCard('recovery', {
+                reason: 'model-fallback',
+                from: currentSpec,
+                to: resolved,
+                cause: unconfigured ? 'credential' : 'not-found',
+            }, formatModelFallbackRecovery(currentSpec, resolved, unconfigured ? 'credential' : 'not-found'))));
         })().catch((err) => {
             emitEvent({ level: 'debug', event: 'broker.runtime.diagnostic', fields: { message: `${unconfigured ? 'unconfigured-provider' : 'not_found'} fallback failed: ${err instanceof Error ? err.message : String(err)}` } });
         }).finally(() => {
@@ -295,6 +300,6 @@ export class FaultRetry {
         if (this.deps.installedGeneration() !== generation || this.deps.currentSession() !== candidateSession)
             return;
         recordFault(this.deps.nodeId, plan.fault);
-        await operationIdContext.fresh(() => candidateSession.prompt(fault.kind === 'connection' ? CONNECTION_FAULT_RECOVERY_BODY : PROVIDER_FAULT_RECOVERY_BODY));
+        await operationIdContext.fresh(() => candidateSession.prompt(formatCard('recovery', { reason: fault.kind === 'connection' ? 'connection' : 'provider' }, fault.kind === 'connection' ? CONNECTION_FAULT_RECOVERY_BODY : PROVIDER_FAULT_RECOVERY_BODY)));
     }
 }

package/dist/core/runtime/broker/frame-dispatch.d.ts

@@ -1,7 +1,7 @@
 import type { AgentSessionServices, ModelRegistry, PromptOptions } from '@earendil-works/pi-coding-agent';
 import type { ImageContent } from '@earendil-works/pi-ai';
 import { type BrokerSdkConfig } from '../launch.js';
-import type { ClientToBroker } from '../broker-protocol.js';
+import { type ClientToBroker } from '../broker-protocol.js';
 import type { BrokerClient, BrokerClientRegistry } from './client-registry.js';
 import { type BrokerSession } from './read-ops.js';
 import type { ToolGroupTracker } from './tool-groups.js';

package/dist/core/runtime/broker/frame-dispatch.js

@@ -3,7 +3,7 @@ import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { AUTH_FAULT_RECOVERY_BODY } from '../../../shared/generated-context.js';
+import { AUTH_FAULT_RECOVERY_BODY, formatCard } from '../../../shared/generated-context.js';
 import { emitEvent } from '../../events/emit.js';
 import { operationIdContext } from '../../events/operation-id.js';
 import { buildRefInventory } from '../../memory/inline-ref-inventory.js';
@@ -16,6 +16,7 @@ import { SessionListCache } from '../session-list-cache.js';
 import { sessionListCachePath } from '../../canvas/paths.js';
 import { isReviewBoundary } from '../session-visibility.js';
 import { isUnknownModel, parseModelSpec } from '../model-selection.js';
+import { normalizeSnapshotTail } from '../broker-protocol.js';
 import { buildCommandList, buildGetTreeData, buildListMemoryRefsData, buildListModelsData, buildScopedModelsData, buildSessionsData, buildSettingsData, modelKey, } from './read-ops.js';
 export const REVIEW_BOUNDARY_NAVIGATION_CODE = 'review_boundary_navigation';
 export class ReviewBoundaryNavigationError extends Error {
@@ -752,6 +753,7 @@ export function createFrameDispatchContext(deps) {
         // stated. A duplicate hello still re-sends the catch-up snapshot.
         const firstHello = !client.helloed;
         client.id = frame.client_id;
+        client.snapshotTail = normalizeSnapshotTail(frame.snapshot_tail);
         if (firstHello) {
             client.helloed = true;
             client.role = frame.role === 'controller' ? 'controller' : 'observer';
@@ -1431,7 +1433,7 @@ export function createFrameDispatchContext(deps) {
                             fresh.since !== authFault.since)
                             return;
                         clearFault(nodeId, { link: 'pi→provider' });
-                        await authFaultSession.prompt(AUTH_FAULT_RECOVERY_BODY);
+                        await authFaultSession.prompt(formatCard('recovery', { reason: 'auth' }, AUTH_FAULT_RECOVERY_BODY));
                     }
                     catch (err) {
                         emitEvent({

package/dist/core/runtime/broker/inbox.d.ts

@@ -8,11 +8,14 @@ export interface BrokerInboxEntry {
     operation_id: OperationId;
     ts: string;
     from: string | null;
+    from_name?: string;
     tier: 'critical' | 'urgent' | 'normal' | 'deferred';
     kind: 'update' | 'urgent' | 'final' | 'message' | 'completed';
     ref?: string;
     label: string;
     data?: Record<string, unknown>;
+    /** Set only by the human-ticket settlement paths; absent means an ordinary report. */
+    disposition?: 'human-answer' | 'human-canceled';
 }
 export declare function readBrokerCursor(nodeId: string): BrokerInboxEntryId | undefined;
 export declare function readBrokerInboxSince(nodeId: string, cursor?: string): BrokerInboxEntry[];
@@ -22,5 +25,14 @@ export declare function readBrokerCanceledEntryIds(nodeId: string): Set<BrokerIn
  *  absent, absolute, or not a report path. Callers use it to tell whether the
  *  report-node projection they hold can still resolve the ref. */
 export declare function reportRefNodeId(ref: string | undefined): string | undefined;
-/** Render the existing inbox digest wording with daemon-projected report existence. */
-export declare function coalesceBrokerInbox(entries: readonly BrokerInboxEntry[], reportNodes: ReadonlyMap<string, BrokerReportNodeDTO>): string;
+/** One deliverable user message: either a person's verbatim words or the whole
+ *  `<runtime kind="inbox">` envelope. Never both — a reader parses an envelope
+ *  only as a whole message, so mixing them attributes the card to the person. */
+export interface InboxDelivery {
+    kind: 'human' | 'card';
+    text: string;
+    entries: readonly BrokerInboxEntry[];
+}
+/** Split unread entries into ordered deliveries: each human entry verbatim, and
+ *  every node/system entry in one card landing where the first such sender fell. */
+export declare function coalesceBrokerInbox(entries: readonly BrokerInboxEntry[], reportNodes: ReadonlyMap<string, BrokerReportNodeDTO>): readonly InboxDelivery[];

package/dist/core/runtime/broker/inbox.js

@@ -2,6 +2,7 @@
 // broker only reads its own files and uses daemon-projected report senders.
 import { existsSync, readFileSync } from 'node:fs';
 import { inboxPath, nodeDir } from '../../canvas/paths.js';
+import { formatInboxCard } from '../../../shared/generated-context.js';
 const ENTRY_ID = /^(?!0{32}$)[0-9a-f]{32}$/;
 const BODY_MAX_LINES = 12;
 const BODY_MAX_CHARS = 1000;
@@ -115,40 +116,52 @@ export function reportRefNodeId(ref) {
         return undefined;
     return ref.slice(0, separator);
 }
+/** Reports are written with a YAML frontmatter block; only the body belongs in
+ *  the card, so a human answer's entry carries the person's words alone. */
+function stripFrontmatter(raw) {
+    if (!raw.startsWith('---\n'))
+        return raw;
+    const end = raw.indexOf('\n---\n', 4);
+    return end === -1 ? raw : raw.slice(end + 5);
+}
 function inlineReport(entry, reportNodes) {
     const nodeId = reportRefNodeId(entry.ref);
     if (nodeId === undefined || !reportNodes.has(nodeId))
         return null;
     const relpath = entry.ref.slice(entry.ref.indexOf(':') + 1);
-    const path = `${nodeDir(nodeId)}/${relpath}`;
     try {
-        const body = readFileSync(path, 'utf8');
-        return body.length >= INLINE_REPORT_MAX_CHARS ? null : { body, path };
+        const body = stripFrontmatter(readFileSync(`${nodeDir(nodeId)}/${relpath}`, 'utf8'));
+        return body.length >= INLINE_REPORT_MAX_CHARS ? null : body;
     }
     catch {
         return null;
     }
 }
-function renderEntry(entry, reportNodes) {
+/** One entry's card body: an inlined short report, a bounded inline message
+ *  body, or the label when the entry carries neither. */
+function entryBody(entry, reportNodes) {
     const report = inlineReport(entry, reportNodes);
-    if (report !== null) {
-        const indented = report.body.trimEnd().split('\n').map((line) => `    ${line}`).join('\n');
-        return { text: `  [${entry.kind}]\n${indented}\n    (report: ${report.path})`, hasCanonicalRef: false };
-    }
+    if (report !== null)
+        return report.trimEnd();
     const body = inlineBody(entry);
-    if (body === '') {
-        const hasCanonicalRef = entry.ref !== undefined && !entry.ref.startsWith('/');
-        return { text: entry.ref === undefined ? `  [${entry.kind}] ${entry.label}` : `  [${entry.kind}] ${entry.label}  (ref: ${entry.ref})`, hasCanonicalRef };
-    }
+    if (body === '')
+        return entry.label;
     const { text, clipped } = clipBody(body);
-    const indented = text.split('\n').map((line) => `    ${line}`).join('\n');
-    const more = entry.ref !== undefined ? `\n    … (full body: ${entry.ref})` : clipped ? '\n    … (body clipped)' : '';
-    return { text: `  [${entry.kind}]\n${indented}${more}`, hasCanonicalRef: false };
+    return clipped && entry.ref === undefined ? `${text}\n… (body clipped)` : text;
+}
+function cardEntry(entry, reportNodes) {
+    return {
+        kind: entry.kind,
+        body: entryBody(entry, reportNodes),
+        ...(entry.ref === undefined ? {} : { ref: entry.ref }),
+        ...(entry.disposition === undefined ? {} : { disposition: entry.disposition }),
+    };
 }
-/** Render the existing inbox digest wording with daemon-projected report existence. */
+/** Split unread entries into ordered deliveries: each human entry verbatim, and
+ *  every node/system entry in one card landing where the first such sender fell. */
 export function coalesceBrokerInbox(entries, reportNodes) {
     if (entries.length === 0)
-        return '(inbox empty)';
+        return [];
     const groups = new Map();
     for (const entry of entries) {
         const key = entry.from ?? 'system';
@@ -156,21 +169,35 @@ export function coalesceBrokerInbox(entries, reportNodes) {
             groups.set(key, []);
         groups.get(key).push(entry);
     }
-    let hasCanonicalRef = false;
+    const deliveries = [];
     const sections = [];
+    let cardSlot = -1;
     for (const [sender, items] of groups) {
         if (sender === 'human') {
             for (const entry of items) {
                 const body = inlineBody(entry);
-                sections.push(body === '' ? entry.label : body);
+                deliveries.push({ kind: 'human', text: body === '' ? entry.label : body, entries: [entry] });
             }
             continue;
         }
-        const lines = items.map((entry) => renderEntry(entry, reportNodes));
-        if (lines.some((line) => line.hasCanonicalRef))
-            hasCanonicalRef = true;
-        sections.push(`From ${sender} — ${items.length} update${items.length === 1 ? '' : 's'}:\n${lines.map((line) => line.text).join('\n')}`);
+        if (cardSlot < 0) {
+            cardSlot = deliveries.length;
+            deliveries.push({ kind: 'card', text: '', entries: [] });
+        }
+        // The fallback to a CURRENT projected name is correct only for legacy
+        // entries, which predate the producer's own `from_name` snapshot.
+        const name = items.map((item) => item.from_name).filter((value) => value !== undefined && value !== '').at(-1)
+            ?? reportNodes.get(sender)?.name;
+        sections.push({ id: sender, ...(name === undefined ? {} : { name }), entries: items.map((entry) => cardEntry(entry, reportNodes)) });
+    }
+    if (cardSlot >= 0) {
+        // Card sections group by sender, so its entry list comes from the input
+        // array instead: a delivery's entry ids must be in physical inbox order.
+        deliveries[cardSlot] = {
+            kind: 'card',
+            text: formatInboxCard(sections),
+            entries: entries.filter((entry) => (entry.from ?? 'system') !== 'human'),
+        };
     }
-    const digest = sections.join('\n\n');
-    return hasCanonicalRef ? `${digest}\n\nDereference a ref with \`crtr canvas history read <ref>\`.` : digest;
+    return deliveries;
 }

package/dist/core/runtime/broker/passive.d.ts

@@ -5,6 +5,7 @@ export interface BrokerPassiveEntry {
     operation_id: string;
     ts: string;
     from: string | null;
+    from_name?: string;
     tier: string;
     kind: string;
     ref?: string;

package/dist/core/runtime/broker/tool-groups.js

@@ -5,7 +5,7 @@ import { readConfig } from '../../config.js';
 import { emitEvent } from '../../events/emit.js';
 import { atomicWriteJson, readJsonIfExists } from '../../fs-utils.js';
 import { assistantVisibleText, isTrueUserMessage, normalizeToolGroupSummaryRecord, } from '../../../shared/tool-groups.js';
-import { generatedContextText } from '../../../shared/generated-context.js';
+import { generatedContextText, parseCard } from '../../../shared/generated-context.js';
 import { headlessToolGroupSummary, serializeToolGroup } from '../tool-group-summary.js';
 const PENDING_TOOL_SUMMARY_KEY_MAX_CHARS = 1_000;
 const PENDING_TOOL_SUMMARY_SEGMENT_MAX_CHARS = 10_000;
@@ -140,7 +140,8 @@ export class ToolGroupTracker {
         if (item.display === false)
             return;
         const text = generatedContextText(item);
-        const isBearingsOrRevive = item.customType === 'crtr-context' || (item.role === 'user' && text.startsWith('You have been revived fresh after a context refresh'));
+        const kind = parseCard(item)?.kind;
+        const isBearingsOrRevive = kind === 'bearings' || kind === 'revive';
         if (isBearingsOrRevive) {
             if (this.openToolGroup !== undefined && text !== '')
                 this.openToolGroup.pieces.push({ type: 'text', text });

package/dist/core/runtime/broker-protocol.d.ts

@@ -18,6 +18,9 @@ export type ClientRole = 'controller' | 'observer';
  *  import. */
 export interface BrokerSnapshot {
     messages: AgentSession['messages'];
+    /** Stable session-entry ids aligned 1:1 with `messages`. Absent when the
+     * session manager cannot expose its entry tree. */
+    messageIds?: string[];
     stats: SessionStats;
     /** pi's OWN `get_state` payload, verbatim — not a mirror. `buildSnapshot`
      *  fills it exactly as pi's `rpc-mode.js` does, from the same getters, so a
@@ -69,12 +72,18 @@ export interface BrokerSnapshot {
      *  `Working...` when it is absent. */
     workingActivity?: string;
 }
+/** Largest transcript window a client may request in its welcome snapshot. */
+export declare const SNAPSHOT_TAIL_MAX = 500;
+/** Invalid requests preserve the complete welcome; valid requests are capped. */
+export declare function normalizeSnapshotTail(value: unknown): number | undefined;
 /** Opens the connection and FIXES this client's role for its lifetime. A repeated
  *  `hello` on an already-helloed socket never changes the established role. */
 export interface HelloFrame {
     type: 'hello';
     role: ClientRole;
     client_id: string;
+    /** Per-attach welcome transcript bound; absent or invalid keeps the full history. */
+    snapshot_tail?: number;
     /** Terminal geometry of a tmux-pane viewer; absent for a headless client. */
     term?: {
         cols: number;

package/dist/core/runtime/broker-protocol.js

@@ -17,6 +17,17 @@
 // follow pi.
 import { StringDecoder } from 'node:string_decoder';
 // ---------------------------------------------------------------------------
+// Client → broker frames
+// ---------------------------------------------------------------------------
+/** Largest transcript window a client may request in its welcome snapshot. */
+export const SNAPSHOT_TAIL_MAX = 500;
+/** Invalid requests preserve the complete welcome; valid requests are capped. */
+export function normalizeSnapshotTail(value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1)
+        return undefined;
+    return Math.min(value, SNAPSHOT_TAIL_MAX);
+}
+// ---------------------------------------------------------------------------
 // Newline-delimited JSON codec (the framing pi solves with `jsonl`, reproduced
 // locally so the protocol module owns no transport dependency)
 // ---------------------------------------------------------------------------

package/dist/core/runtime/broker.d.ts

@@ -3,7 +3,7 @@ import { type BrokerSdkConfig } from './launch.js';
 import { type BrokerEngine } from './broker-sdk.js';
 import { type KnownStreamWaitControl } from './stream-watchdog.js';
 import { type BrokerClient } from './broker/client-registry.js';
-import { type BrokerSnapshot, type BrokerToClient, type RpcExtensionUIRequest, type RpcExtensionUIResponse } from './broker-protocol.js';
+import { type BrokerToClient, type RpcExtensionUIRequest, type RpcExtensionUIResponse } from './broker-protocol.js';
 /** A review companion may only navigate or fork within a branch whose ancestry
  * has crossed its durable transcript boundary. The broker sends this typed local
  * failure as a dedicated error frame without invoking pi's tree mutation. */
@@ -29,7 +29,7 @@ interface PendingDialog {
  *  bash children. No-op before the session is built or after a clean dispose. */
 export declare function disposeActiveSession(): void;
 export declare function runBroker(nodeId: string, startupAt?: bigint, startupTs?: string): Promise<void>;
-export declare function snapshotMessages(session: CreateAgentSessionResult['session'], boundaryReviewId?: string): BrokerSnapshot['messages'];
+export declare function snapshotMessages(session: CreateAgentSessionResult['session'], boundaryReviewId?: string): import("./session-cycles.js").IdentifiedMessage[] | undefined;
 export declare function buildBrokerSession(engine: BrokerEngine, cfg: BrokerSdkConfig): Promise<{
     session: CreateAgentSessionResult['session'];
     services: AgentSessionServices;

package/dist/core/runtime/broker.js

@@ -48,7 +48,7 @@ import { EventProjection } from './broker/event-projection.js';
 import { createFrameDispatchContext, handleFrame } from './broker/frame-dispatch.js';
 import { RebindDriver } from './broker/rebind.js';
 import { brokerExtensionState, commitBrokerModel } from './broker/daemon-ops.js';
-import { FrameOverflowError, } from './broker-protocol.js';
+import { FrameOverflowError, normalizeSnapshotTail, } from './broker-protocol.js';
 /** A review companion may only navigate or fork within a branch whose ancestry
  * has crossed its durable transcript boundary. The broker sends this typed local
  * failure as a dedicated error frame without invoking pi's tree mutation. */
@@ -355,10 +355,23 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
             disposeAndExit('daemon-state-read-failed', 1);
         },
     });
-    const buildSnapshot = () => {
+    const buildSnapshot = (client) => {
         const liveSession = rebind.session();
+        const identified = snapshotMessages(liveSession, boundaryReviewId);
+        const tail = normalizeSnapshotTail(client.snapshotTail);
+        const retained = identified === undefined || tail === undefined ? identified : identified.slice(-tail);
+        const messages = retained?.map(({ message }) => message)
+            ?? (tail === undefined
+                ? liveSession.sessionManager.buildSessionContext().messages
+                : liveSession.sessionManager.buildSessionContext().messages.slice(-tail));
+        const fullToolGroupSummaries = toolGroups.summaries();
+        const retainedToolCallIds = tail === undefined ? undefined : toolCallIds(messages);
+        const toolGroupSummaries = retainedToolCallIds === undefined
+            ? fullToolGroupSummaries
+            : Object.fromEntries(Object.entries(fullToolGroupSummaries).filter(([id]) => retainedToolCallIds.has(id)));
         return ({
-            messages: snapshotMessages(liveSession, boundaryReviewId),
+            messages,
+            ...(retained === undefined ? {} : { messageIds: retained.map(({ id }) => id) }),
             stats: liveSession.getSessionStats(),
             // pi's `get_state` (rpc-mode.js), field for field, from the same getters.
             // The ONE divergence: a model-less session (undefined OR the SDK
@@ -383,7 +396,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
             display: {
                 ...registry.displaySnapshot(),
             },
-            toolGroupSummaries: toolGroups.summaries(),
+            toolGroupSummaries,
             workingActivity: projection.currentWorkingActivity(),
             // The UNRUN queue's texts, read non-destructively (`clearQueue()` would
             // consume them). Same two arrays a live `queue_update` carries, so a client
@@ -404,7 +417,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         const first = client.role === 'controller' ? pendingDialogs.values().next().value : undefined;
         registry.sendFrame(client, {
             type: 'welcome',
-            snapshot: buildSnapshot(),
+            snapshot: buildSnapshot(client),
             role: client.role,
             pending_dialog: first !== undefined ? first.request : null,
             agentDir: getAgentDir(),
@@ -684,13 +697,25 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
 // conversation instead of just the post-yield window; single-cycle sessions and
 // the fake-engine fixture (no tree accessors) fall through to plain
 // `buildSessionContext().messages` unchanged.
+function toolCallIds(messages) {
+    const ids = new Set();
+    for (const message of messages) {
+        if (message.role !== 'assistant' || !Array.isArray(message.content))
+            continue;
+        for (const part of message.content) {
+            if (part !== null && typeof part === 'object' && part.type === 'toolCall' && typeof part.id === 'string')
+                ids.add(part.id);
+        }
+    }
+    return ids;
+}
 export function snapshotMessages(session, boundaryReviewId) {
     // Cast: the real SDK's `SessionEntry.data` is `unknown` (untyped custom-entry
     // payload), narrower than `CycleSessionManagerLike`'s structural read of the
     // `crtr-cycle` marker's `{cycle, fromLeaf}` shape — the fields we read off it
     // are ones ONLY this module's own `appendCustomEntry` call (above) ever writes.
     const messages = cycleAwareMessages(session.sessionManager);
-    return visibleMessages(messages, { boundaryReviewId });
+    return messages === undefined ? undefined : visibleMessages(messages, { boundaryReviewId });
 }
 // ---------------------------------------------------------------------------
 // resolveLaunchModel — the SOLE launch model-selection policy, module-scoped

package/dist/core/runtime/deliver-live.js

@@ -22,6 +22,7 @@ import { oneShotControllerRequest } from './broker-request.js';
 import { isBrokerLive } from './model-swap.js';
 import { buildContextBearings, CONTEXT_INTRO_CUSTOM_TYPE } from './bearings.js';
 import { loadInjectedDocs, saveInjectedDocs } from '../substrate/injected-store.js';
+import { formatCard } from '../../shared/generated-context.js';
 /** Deliver `message` into `nodeId`'s live session. Resolves without doing
  *  anything when the node has no live broker. Rejects when a live broker cannot
  *  be reached or refuses the frame — the caller decides what that means (for a
@@ -66,7 +67,7 @@ export async function deliverBearingsLive(nodeId) {
     const seen = loadInjectedDocs(nodeId);
     await deliverCustomMessageLive(nodeId, {
         customType: CONTEXT_INTRO_CUSTOM_TYPE,
-        content: buildContextBearings(nodeId, seen),
+        content: formatCard('bearings', {}, buildContextBearings(nodeId, seen)),
         details: { nodeId },
     });
     saveInjectedDocs(nodeId, seen);

package/dist/core/runtime/kickoff.d.ts

@@ -1,6 +1,8 @@
 import { type NodeMeta } from '../canvas/index.js';
 import { type WakeOrigin } from './bearings.js';
-export { REVIVE_KICKOFF_SENTINEL, RUNTIME_RESTART_CONTINUATION, } from '../../shared/generated-context.js';
+/** The runtime-restart continuation exactly as delivered. `revive.ts` injects
+ *  it as the prompt of a strict resume that follows a cleanly aborted turn. */
+export declare const RUNTIME_RESTART_CONTINUATION: string;
 /** The goal file — the prompt/task a node was spawned with, persisted at birth
  *  so a fresh revive can re-read its mandate. */
 export declare function goalPath(nodeId: string): string;
@@ -13,9 +15,6 @@ export declare function writeGoal(nodeId: string, text: string): void;
  *  goal. Returns true when it wrote one, false when a goal already existed or
  *  the text was empty. Guarded so a later message never clobbers the mandate. */
 export declare function captureGoalIfAbsent(nodeId: string, text: string): boolean;
-/** Sentinel opening the fresh-revive kickoff message (see buildReviveKickoff).
- *  The goal-capture extension and attached renderers share its pure definition,
- *  so the same exact contract controls both prompt exclusion and display. */
 /** The yield-message file — a short note `crtr node yield` records for the next
  *  fresh/cycling revive ("on wake, do X"). It remains durable through failed
  *  launch attempts and is cleared only when session_start confirms a boot. */

package/dist/core/runtime/kickoff.js

@@ -5,7 +5,8 @@
 // round-trip. Resuming a saved conversation needs none of this (the
 // conversation already holds the context).
 //
-// Layout (the framing a revived node sees):
+// Layout (the framing a revived node sees), all of it inside one
+// <runtime kind="revive" …> card envelope:
 //   <roadmap file=…>…</roadmap>            its evolving plan — the source of truth
 //   <context-dir path=…>…</context-dir>    what artifacts exist on disk
 //   <feed>Awaiting N nodes … digest</feed> live wait state + unread/catch-up feed
@@ -25,8 +26,10 @@ import { readRoadmap, roadmapPath } from './roadmap.js';
 import { buildWakeBearings } from './bearings.js';
 import { personaDrift, commitPersonaAck } from './persona.js';
 import { readInboxSince, readCursor, writeCursor, coalesce, } from '../feed/inbox.js';
-import { REVIVE_KICKOFF_SENTINEL } from '../../shared/generated-context.js';
-export { REVIVE_KICKOFF_SENTINEL, RUNTIME_RESTART_CONTINUATION, } from '../../shared/generated-context.js';
+import { formatCard } from '../../shared/generated-context.js';
+/** The runtime-restart continuation exactly as delivered. `revive.ts` injects
+ *  it as the prompt of a strict resume that follows a cleanly aborted turn. */
+export const RUNTIME_RESTART_CONTINUATION = formatCard('restart-continuation', {}, 'continue');
 // ---------------------------------------------------------------------------
 // Companion context files: the goal (the spawning mandate) and the one-shot
 // yield message (a note from the prior self to the revived self).
@@ -63,9 +66,6 @@ export function captureGoalIfAbsent(nodeId, text) {
     writeGoal(nodeId, body);
     return true;
 }
-/** Sentinel opening the fresh-revive kickoff message (see buildReviveKickoff).
- *  The goal-capture extension and attached renderers share its pure definition,
- *  so the same exact contract controls both prompt exclusion and display. */
 /** The yield-message file — a short note `crtr node yield` records for the next
  *  fresh/cycling revive ("on wake, do X"). It remains durable through failed
  *  launch attempts and is cleared only when session_start confirms a boot. */
@@ -115,7 +115,9 @@ export function drainBearings(meta) {
     let unreadDigest = null;
     if (entries.length > 0) {
         writeCursor(nodeId, entries.at(-1).entry_id);
-        unreadDigest = coalesce(entries);
+        // The launch-argv seam carries one message, so a mixed batch's split parts
+        // join back into this block's body; the kickoff is one whole envelope.
+        unreadDigest = coalesce(entries).map((delivery) => delivery.text).join('\n\n');
     }
     // Capture + commit any external persona drift (the second of the two delivery
     // sites). Committing the ack here is the mutation; the guidance is surfaced by
@@ -244,16 +246,15 @@ function backgroundJobsBlock(nodeId) {
 export function buildReviveKickoff(meta, bearings, wakeReason) {
     const nodeId = meta.node_id;
     const parts = [
-        `${REVIVE_KICKOFF_SENTINEL} — your previous in-memory ` +
+        'You have been revived fresh after a context refresh — your previous in-memory ' +
             'context is gone, by design. Everything below was just read from disk; it is your ' +
             'full bearings. Rebuild from it and continue toward your goal.',
     ];
     // Wake provenance (Invariant B/D): when a scheduled bare self-alarm fired this
     // revive, the <crtr-wake> block reframes the generic "you were revived" above
-    // into "a TIMER woke you" — placed right after the sentinel (so the kickoff
-    // still STARTS with REVIVE_KICKOFF_SENTINEL, which goal-capture keys on) and
-    // before the roadmap/disk bearings, so "why you woke" precedes "what to rebuild
-    // from". Only the daemon's bare-wake branch passes wakeReason.
+    // into "a TIMER woke you" — placed before the roadmap/disk bearings, so "why you
+    // woke" precedes "what to rebuild from". Only the daemon's bare-wake branch
+    // passes wakeReason.
     if (wakeReason !== undefined)
         parts.push(buildWakeBearings(wakeReason));
     // The roadmap is the source of truth on a fresh revive: its frozen core holds
@@ -316,5 +317,14 @@ export function buildReviveKickoff(meta, bearings, wakeReason) {
     if (bearings.driftGuidance !== null) {
         parts.push(`<persona-transition>\nYour role was changed while you were away. ${bearings.driftGuidance}\n</persona-transition>`);
     }
-    return parts.join('\n\n');
+    // The whole kickoff is one runtime card. Its facts are what this producer
+    // knows about the revive, and they are the ONLY thing a reader may classify or
+    // summarize on — the prose above stays free to be reworded. The envelope is
+    // also what keeps a fresh revive out of canvas-goal-capture's first-real-input
+    // path, which would otherwise overwrite a bare root's mandate and rename it.
+    return formatCard('revive', {
+        mode: meta.mode,
+        ...(meta.cycle_pending === true ? { cycle: true } : {}),
+        ...(wakeReason === undefined ? {} : { wake: wakeReason.kind }),
+    }, `\n${parts.join('\n\n')}\n`);
 }

package/dist/core/runtime/node-read.d.ts

@@ -30,6 +30,8 @@ export interface NodeSnapshotRead {
 }
 export interface NodeMessagesPageRead {
     messages: unknown[];
+    /** Stable session-entry ids aligned 1:1 with `messages`. */
+    messageIds?: string[];
     nextCursor: string | null;
 }
 export interface NodeMessagesPageOptions {

package/dist/core/runtime/node-read.js

@@ -153,10 +153,15 @@ async function reconstructVisibleMessages(nodeId) {
         copyFileSync(sessionFile, copy);
         const manager = SessionManager.open(copy);
         const context = manager.buildSessionContext();
-        const messages = visibleMessages(cycleAwareMessages(manager), { boundaryReviewId: node.review_binding?.review_id });
+        const reconstructed = cycleAwareMessages(manager);
+        const identified = reconstructed === undefined
+            ? undefined
+            : visibleMessages(reconstructed, { boundaryReviewId: node.review_binding?.review_id });
+        const messages = identified?.map(({ message }) => message) ?? context.messages;
         return {
             sessionFile,
             messages,
+            identified,
             model: context.model,
             thinkingLevel: context.thinkingLevel,
             sessionId: manager.getSessionId(),
@@ -208,6 +213,7 @@ export async function readNodeSnapshot(nodeId) {
     const read = await reconstructVisibleMessages(nodeId);
     const snapshot = {
         messages: read.messages,
+        ...(read.identified === undefined ? {} : { messageIds: read.identified.map(({ id }) => id) }),
         stats: statsFromMessages(read.messages, read.sessionId, read.sessionFile),
         // pi's `get_state` shape (RpcSessionState), reconstructed offline: the
         // live-only fields report their at-rest values (nothing is streaming or
@@ -255,11 +261,13 @@ export async function readNodeMessagesPage(nodeId, { cursor, limit = 200 }) {
             next: 'Use a limit from 1 through 500.',
         });
     }
-    const { messages } = await reconstructVisibleMessages(nodeId);
+    const { messages, identified } = await reconstructVisibleMessages(nodeId);
     const before = cursor === undefined ? messages.length : decodeMessagesCursor(cursor, messages.length);
     const start = Math.max(0, before - limit);
+    const page = identified?.slice(start, before);
     return {
-        messages: messages.slice(start, before),
+        messages: page?.map(({ message }) => message) ?? messages.slice(start, before),
+        ...(page === undefined ? {} : { messageIds: page.map(({ id }) => id) }),
         nextCursor: start === 0 ? null : encodeMessagesCursor(start),
     };
 }

package/dist/core/runtime/session-cycles.d.ts

@@ -8,6 +8,11 @@ export declare const CRTR_CYCLE_CUSTOM_TYPE = "crtr-cycle";
  *  snapshot rendering. Never persisted to the session file. */
 export declare const CRTR_CYCLE_DIVIDER_CUSTOM_TYPE = "crtr-cycle-divider";
 type SnapshotMessage = BrokerSnapshot['messages'][number];
+/** One reconstructed message and the durable session entry that produced it. */
+export type IdentifiedMessage = {
+    id: string;
+    message: SnapshotMessage;
+};
 /** The structural slice of pi's SessionManager cycle rendering needs. The
  *  broker's fake-engine test fixture implements only `buildSessionContext`, so
  *  the tree accessors are optional — absent ⇒ single-cycle behavior. */
@@ -36,5 +41,5 @@ export declare function withoutYieldAbort(message: SnapshotMessage): SnapshotMes
  *  the manager lacks tree accessors (fake engine), or when the current leaf was
  *  tree-navigated back into a pre-yield branch (pi's active-branch semantics
  *  then apply unchanged). */
-export declare function cycleAwareMessages(sm: CycleSessionManagerLike): SnapshotMessage[];
+export declare function cycleAwareMessages(sm: CycleSessionManagerLike): IdentifiedMessage[] | undefined;
 export {};