@north-light/crouter 0.3.204 → 0.3.206

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
@@ -282,9 +283,10 @@ export function buildReviveKickoff(meta, bearings, wakeReason) {
     // Hidden applet/situation-origin ambient context (see situational-context.ts)
     // is deliberately NOT injected here — this kickoff is the VISIBLE revive prompt.
     // canvas-context-intro's session_start handler re-fires on every fresh/cycling
-    // revive (a new pi process boot) and re-injects buildContextIntro(), which
-    // already carries the sidecar as a hidden sibling of <crtr-bearings>; that seam
-    // covers this path, so duplicating it into the visible prompt would leak it.
+    // revive (a new pi process boot) and re-injects buildContextIntro(), whose
+    // bearings body already nests the stored situational card; that seam covers
+    // this path, so duplicating it here would both repeat the card and put hidden
+    // ambient context into a visible prompt.
     // Live background bash jobs sit beside the context-dir listing: both describe
     // this node's OWN in-flight state, and both precede <feed>, which is about the
     // other nodes it awaits. Absent when nothing is running.
@@ -316,5 +318,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 {};

package/dist/core/runtime/session-cycles.js

@@ -14,7 +14,7 @@
 // boundary, then the live cycle's context — so the broker welcome snapshot
 // (broker.ts) and the dormant snapshot (node-snapshot.ts) both render one
 // continuous conversation.
-import { buildSessionContext } from '@earendil-works/pi-coding-agent';
+import { buildContextEntries, sessionEntryToContextMessages, } from '@earendil-works/pi-coding-agent';
 /** customType of the persisted tree entry that ROOTS each post-yield cycle.
  *  Data payload: `{ cycle, fromLeaf }` — `cycle` is the node's cycle counter at
  *  relaunch, `fromLeaf` the previous cycle's leaf entry id. */
@@ -55,9 +55,14 @@ export function withoutYieldAbort(message) {
     const { stopReason: _stopReason, errorMessage: _errorMessage, ...visible } = message;
     return visible;
 }
+function identifiedContextMessages(entries, leafId, byId) {
+    return buildContextEntries(entries, leafId, byId).flatMap((entry) => sessionEntryToContextMessages(entry).map((message) => ({ id: entry.id, message: message })));
+}
 function priorCycleMessages(messages) {
     const last = messages.at(-1);
-    return last === undefined ? messages : [...messages.slice(0, -1), withoutYieldAbort(last)];
+    return last === undefined
+        ? messages
+        : [...messages.slice(0, -1), { ...last, message: withoutYieldAbort(last.message) }];
 }
 /** The full multi-cycle message history for display: prior cycles (oldest
  *  first, each closed by a divider), then the live cycle's context. Falls back
@@ -66,11 +71,13 @@ function priorCycleMessages(messages) {
  *  tree-navigated back into a pre-yield branch (pi's active-branch semantics
  *  then apply unchanged). */
 export function cycleAwareMessages(sm) {
-    const current = sm.buildSessionContext().messages;
     if (typeof sm.getEntries !== 'function' || typeof sm.getBranch !== 'function')
-        return current;
+        return undefined;
     // File order = append order = chronological cycle order.
     const entries = sm.getEntries();
+    const byId = new Map(entries.map((e) => [e.id, e]));
+    const currentBranch = sm.getBranch();
+    const current = identifiedContextMessages(entries, currentBranch.at(-1)?.id ?? null, byId);
     const markers = entries.filter((e) => e.type === 'custom' && e.customType === CRTR_CYCLE_CUSTOM_TYPE);
     if (markers.length === 0)
         return current;
@@ -78,14 +85,10 @@ export function cycleAwareMessages(sm) {
     // not a cycle marker, the leaf sits in the ORIGINAL (pre-yield) branch —
     // render just that branch. Otherwise replay every cycle up to and including
     // the one the marker closes.
-    const currentRootId = sm.getBranch()[0]?.id;
+    const currentRootId = currentBranch[0]?.id;
     const rootMarkerIndex = markers.findIndex((m) => m.id === currentRootId);
     if (rootMarkerIndex === -1)
         return current;
-    // Shared byId map — buildSessionContext would otherwise rebuild one from
-    // `entries` on every call; one pass here amortizes it across every replayed
-    // marker.
-    const byId = new Map(entries.map((e) => [e.id, e]));
     const out = [];
     for (let i = 0; i <= rootMarkerIndex; i++) {
         const marker = markers[i];
@@ -95,9 +98,12 @@ export function cycleAwareMessages(sm) {
             // builder — preserving compaction semantics (one compactionSummary +
             // kept + post-compaction messages only) exactly like the live cycle
             // below.
-            out.push(...priorCycleMessages(buildSessionContext(entries, fromLeaf, byId).messages));
+            out.push(...priorCycleMessages(identifiedContextMessages(entries, fromLeaf, byId)));
         }
-        out.push(cycleDivider(marker.data?.cycle, marker.timestamp));
+        out.push({
+            id: `${marker.id}~divider`,
+            message: cycleDivider(marker.data?.cycle, marker.timestamp),
+        });
     }
     out.push(...current);
     return out;

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

@@ -1,16 +1,11 @@
-import type { BrokerSnapshot, WireSessionTreeNode } from './broker-protocol.js';
-/** customType of the crtr-authored boundary marker that opens a review
- *  companion's visible transcript. Data payload: `{ reviewId, originNodeId,
- *  targetFile }` — per-review facts that complement the inheritance prefix.
- *
- *  The marker itself is a crtr-rendered divider shown to the person; everything
- *  above it in the inherited session is context they cannot see.
- */
-export declare const REVIEW_BOUNDARY_CUSTOM_TYPE = "crtr-review-boundary";
+import type { WireSessionTreeNode } from './broker-protocol.js';
+import type { IdentifiedMessage } from './session-cycles.js';
+import { REVIEW_BOUNDARY_CUSTOM_TYPE } from '../../shared/generated-context.js';
+export { REVIEW_BOUNDARY_CUSTOM_TYPE };
 /** True when an entry is a durable review boundary, optionally for one review. */
 export declare function isReviewBoundary(entry: unknown, reviewId?: string): boolean;
 /**
- * Project snapshot messages to the visible window for a review companion.
+ * Project identified snapshot messages to the visible window for a review companion.
  *
  * A companion passes its binding's review id so the slice starts at ITS OWN
  * boundary marker: a node forked from another companion inherits that
@@ -27,9 +22,9 @@ export declare function isReviewBoundary(entry: unknown, reviewId?: string): boo
  *    with a synthetic boundary while its retained tail remains visible. Every
  *    other markerless shape fails closed with the synthetic boundary alone.
  */
-export declare function visibleMessages(messages: BrokerSnapshot['messages'], opts: {
+export declare function visibleMessages(messages: IdentifiedMessage[], opts: {
     boundaryReviewId: string | undefined;
-}): BrokerSnapshot['messages'];
+}): IdentifiedMessage[];
 /**
  * Project a session tree to the review companion's visible transcript boundary.
  *

package/dist/core/runtime/session-visibility.js

@@ -9,14 +9,8 @@
 // Applied at the two BrokerSnapshot.messages producers (live broker and
 // dormant node read) so every presenter — attach, web node viewer, inspect — is
 // boundary-safe by construction with no presenter-side changes.
-/** customType of the crtr-authored boundary marker that opens a review
- *  companion's visible transcript. Data payload: `{ reviewId, originNodeId,
- *  targetFile }` — per-review facts that complement the inheritance prefix.
- *
- *  The marker itself is a crtr-rendered divider shown to the person; everything
- *  above it in the inherited session is context they cannot see.
- */
-export const REVIEW_BOUNDARY_CUSTOM_TYPE = 'crtr-review-boundary';
+import { REVIEW_BOUNDARY_CUSTOM_TYPE } from '../../shared/generated-context.js';
+export { REVIEW_BOUNDARY_CUSTOM_TYPE };
 /** True when an entry is a durable review boundary, optionally for one review. */
 export function isReviewBoundary(entry, reviewId) {
     if (entry === null || typeof entry !== 'object')
@@ -36,7 +30,7 @@ function syntheticBoundary(timestamp) {
     };
 }
 /**
- * Project snapshot messages to the visible window for a review companion.
+ * Project identified snapshot messages to the visible window for a review companion.
  *
  * A companion passes its binding's review id so the slice starts at ITS OWN
  * boundary marker: a node forked from another companion inherits that
@@ -54,16 +48,16 @@ function syntheticBoundary(timestamp) {
  *    other markerless shape fails closed with the synthetic boundary alone.
  */
 export function visibleMessages(messages, opts) {
-    const markerIndex = messages.findIndex((message) => isReviewBoundary(message, opts.boundaryReviewId));
+    const markerIndex = messages.findIndex(({ message }) => isReviewBoundary(message, opts.boundaryReviewId));
     if (markerIndex !== -1)
         return messages.slice(markerIndex);
     if (opts.boundaryReviewId === undefined)
         return messages;
     const [first, ...retainedTail] = messages;
-    if (first?.role === 'compactionSummary') {
-        return [syntheticBoundary(first.timestamp), ...retainedTail];
+    if (first?.message.role === 'compactionSummary') {
+        return [{ id: '~boundary', message: syntheticBoundary(first.message.timestamp) }, ...retainedTail];
     }
-    return [syntheticBoundary(first?.timestamp)];
+    return [{ id: '~boundary', message: syntheticBoundary(first?.message.timestamp) }];
 }
 /**
  * Project a session tree to the review companion's visible transcript boundary.

package/dist/core/runtime/situational-context.d.ts

@@ -1,12 +1,21 @@
 /** The `customType` stamped on the hidden custom message the inbox watcher
  *  sends for an existing node's situational-context update. */
 export { SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../../shared/generated-context.js';
+/** Render prose supplied through a `situational_context` string entry point
+ *  (`crtr node message --situational-context`, the node-create seed) as the
+ *  card the sidecar stores. Card-supplying callers pass their own rendered
+ *  envelope to `appendSituationalContext` instead. Blank prose renders as ''
+ *  so the sidecar write stays a no-op rather than storing an empty card. */
+export declare function formatSituationalProse(prose: string): string;
 /** Upsert the node's current situational context (replace, not append) — the
- *  one sanctioned writer for the sidecar. No-op for blank text, so a caller
- *  can pass through an optional/empty value with no guard at the call site. */
+ *  one sanctioned writer for the sidecar, taking an ALREADY-RENDERED envelope.
+ *  No-op for blank text, so a caller can pass through an optional/empty value
+ *  with no guard at the call site. */
 export declare function appendSituationalContext(nodeId: string, text: string): void;
 /** Read the current situational context, or null if none was ever set. */
 export declare function readSituationalContext(nodeId: string): string | null;
-/** The `<situational-context>` block for `nodeId`, or '' when none is set —
- *  callers append/filter this like any other optional sibling block. */
-export declare function situationalContextBlock(nodeId: string): string;
+/** The node's stored situational card, verbatim, or null when none is set.
+ *  The ONE read of the sidecar. A sidecar written before the card cut holds
+ *  bare prose; that single legacy branch lives here alone and self-clears on
+ *  the next situation change. */
+export declare function situationalContextEnvelope(nodeId: string): string | null;

package/dist/core/runtime/situational-context.js

@@ -1,30 +1,44 @@
 // situational-context.ts — the hidden ambient "current situation" sidecar.
 //
 // A node-owned runtime file (nodes/<id>/situational-context.md, NOT under
-// context/ — see `situationalContextPath`) carrying the LATEST applet/
-// situation-origin ambient text: current state (e.g. which applet/page a
-// concierge is attached to right now), not task history, and never the node's
-// goal or a visible chat message. Upserted (replace), never appended: only the
-// newest block is ever carried, so stale applet pages never accumulate across
-// concierge reuse.
+// context/ — see `situationalContextPath`) storing ONE rendered runtime-card
+// envelope describing the LATEST situation: current state (e.g. which applet
+// page a concierge is attached to right now), not task history, and never the
+// node's goal or a visible chat message. Upserted (replace), never appended, so
+// stale applet pages never accumulate across concierge reuse.
 //
-// Read at three injection seams, always rendered as a `<situational-context>`
-// block SIBLING to whatever bearings/kickoff frame is being built (never
-// nested inside it, and never routed through coalesce()'s visible digest
-// renderer):
-//   - buildContextBearings() — fresh node kickoff (canvas-context-intro).
-//   - buildReviveKickoff() — fresh/cycling revive.
-//   - canvas-inbox-watcher's flush() — a hidden pi.sendMessage custom message
-//     for an existing live/dormant node, delivered ahead of (and never as
-//     part of) the visible inbox digest.
+// `situationalContextEnvelope()` is the ONE read, and it yields the stored card
+// verbatim — no caller downstream has a shape to check. Its three callers use
+// it differently, and only the last nests:
+//   - canvas-inbox-watcher's context channel — delivered verbatim as a custom
+//     message's content, with SITUATIONAL_CONTEXT_CUSTOM_TYPE as delivery
+//     metadata only.
+//   - setSituationalContextLive() (warm-spare claim) — the same verbatim
+//     delivery, `deliverAs: 'nextTurn'`.
+//   - buildContextBearingsFromState() / buildForkBearingsFromState() — the card
+//     is placed in the bearings body, where it is deliberately a nested card
+//     inside the outer `bearings` card. The only nesting site in the system.
+//
+// The visible revive kickoff carries NO situational context: a fresh or cycling
+// revive receives it through the session-start bearings instead.
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { situationalContextPath, nodeDir } from '../canvas/paths.js';
+import { formatCard, parseCard } from '../../shared/generated-context.js';
 /** The `customType` stamped on the hidden custom message the inbox watcher
  *  sends for an existing node's situational-context update. */
 export { SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../../shared/generated-context.js';
+/** Render prose supplied through a `situational_context` string entry point
+ *  (`crtr node message --situational-context`, the node-create seed) as the
+ *  card the sidecar stores. Card-supplying callers pass their own rendered
+ *  envelope to `appendSituationalContext` instead. Blank prose renders as ''
+ *  so the sidecar write stays a no-op rather than storing an empty card. */
+export function formatSituationalProse(prose) {
+    return prose.trim() === '' ? '' : formatCard('situational', {}, prose);
+}
 /** Upsert the node's current situational context (replace, not append) — the
- *  one sanctioned writer for the sidecar. No-op for blank text, so a caller
- *  can pass through an optional/empty value with no guard at the call site. */
+ *  one sanctioned writer for the sidecar, taking an ALREADY-RENDERED envelope.
+ *  No-op for blank text, so a caller can pass through an optional/empty value
+ *  with no guard at the call site. */
 export function appendSituationalContext(nodeId, text) {
     const body = text.trim();
     if (body === '')
@@ -40,9 +54,13 @@ export function readSituationalContext(nodeId) {
     const body = readFileSync(p, 'utf8').trim();
     return body !== '' ? body : null;
 }
-/** The `<situational-context>` block for `nodeId`, or '' when none is set —
- *  callers append/filter this like any other optional sibling block. */
-export function situationalContextBlock(nodeId) {
+/** The node's stored situational card, verbatim, or null when none is set.
+ *  The ONE read of the sidecar. A sidecar written before the card cut holds
+ *  bare prose; that single legacy branch lives here alone and self-clears on
+ *  the next situation change. */
+export function situationalContextEnvelope(nodeId) {
     const text = readSituationalContext(nodeId);
-    return text === null ? '' : `<situational-context>\n${text}\n</situational-context>`;
+    if (text === null)
+        return null;
+    return parseCard({ content: text }) === null ? formatSituationalProse(text) : text;
 }

package/dist/core/runtime/situational-live.d.ts

@@ -1,5 +1,5 @@
-/** Write `text` to the node's sidecar and, when its broker is live, deliver the
- *  rendered block into the running session for the NEXT turn.
+/** Write `text` (prose) to the node's sidecar and, when its broker is live,
+ *  deliver the stored card into the running session for the NEXT turn.
  *
  *  Rejects when a live broker cannot be reached or refuses the frame — the
  *  caller decides what that means. For a warm claim it is fatal (a node holding

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

@@ -1,24 +1,25 @@
 // situational-live.ts — hand a node its situational context WITHOUT waking it.
 //
-// The sidecar (`situational-context.ts`) is the durable half: every kickoff and
-// revive path renders it as a `<situational-context>` block. This module is the
-// LIVE half for a node whose session has already passed `session_start` — the
-// warm-pool claim, where a spare booted with no situational context is handed
-// to a claimant that has one.
+// The sidecar (`situational-context.ts`) is the durable half: it stores one
+// rendered `situational` card, which every revive path nests into the bearings.
+// This module is the LIVE half for a node whose session has already passed
+// `session_start` — the warm-pool claim, where a spare booted with no
+// situational context is handed to a claimant that has one. The stored card is
+// delivered UNWRAPPED; the customType is delivery metadata only.
 //
 // It is deliberately NOT the inbox watcher's situational send. That seam exists
-// to WAKE a live node when its applet situation changes, so it delivers with
-// `triggerTurn: true`. A freshly-claimed spare must not run a turn before its
-// owner says anything, so this path uses `nextTurn` delivery: the block rides
-// the claimant's first real turn instead of starting one.
+// to WAKE a live node when its applet situation changes. A freshly-claimed
+// spare must not run a turn before its owner says anything, so this path uses
+// `nextTurn` delivery: the card rides the claimant's first real turn instead of
+// starting one.
 //
 // Everything below the sidecar write is the shared live-delivery path
 // (`deliver-live.ts`), which the claim's bearings delivery also rides.
 import { getNode } from '../canvas/index.js';
 import { deliverCustomMessageLive } from './deliver-live.js';
-import { appendSituationalContext, situationalContextBlock, SITUATIONAL_CONTEXT_CUSTOM_TYPE, } from './situational-context.js';
-/** Write `text` to the node's sidecar and, when its broker is live, deliver the
- *  rendered block into the running session for the NEXT turn.
+import { appendSituationalContext, formatSituationalProse, situationalContextEnvelope, SITUATIONAL_CONTEXT_CUSTOM_TYPE, } from './situational-context.js';
+/** Write `text` (prose) to the node's sidecar and, when its broker is live,
+ *  deliver the stored card into the running session for the NEXT turn.
  *
  *  Rejects when a live broker cannot be reached or refuses the frame — the
  *  caller decides what that means. For a warm claim it is fatal (a node holding
@@ -26,15 +27,15 @@ import { appendSituationalContext, situationalContextBlock, SITUATIONAL_CONTEXT_
  *  makes. A DORMANT node needs no delivery at all: its next revive renders the
  *  sidecar into the kickoff. */
 export async function setSituationalContextLive(nodeId, text) {
-    appendSituationalContext(nodeId, text);
+    appendSituationalContext(nodeId, formatSituationalProse(text));
     if (getNode(nodeId) === null)
         throw new Error(`setSituationalContextLive: unknown node ${nodeId}`);
-    const block = situationalContextBlock(nodeId);
-    if (block === '')
+    const envelope = situationalContextEnvelope(nodeId);
+    if (envelope === null)
         return; // blank text — appendSituationalContext no-ops, nothing to deliver
     await deliverCustomMessageLive(nodeId, {
         customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE,
-        content: block,
+        content: envelope,
         deliverAs: 'nextTurn',
     });
 }

package/dist/core/runtime/spawn.js

@@ -18,7 +18,7 @@ import { buildLaunchSpec, buildPiArgv } from './launch.js';
 import { createManagedWorktree, rollbackManagedWorktree } from '../worktree.js';
 import { usage, brokerLaunchFailed } from '../errors.js';
 import { writeGoal } from './kickoff.js';
-import { appendSituationalContext } from './situational-context.js';
+import { appendSituationalContext, formatSituationalProse } from './situational-context.js';
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
 import { buildWakeBearings } from './bearings.js';
 import { contextDir, getNode, fullName, recordPid } from '../canvas/index.js';
@@ -285,8 +285,9 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         writeGoal(meta.node_id, opts.prompt);
         // Hidden ambient context, written BEFORE the engine launches so canvas-
         // context-intro's session_start bearings carry it from the first turn.
-        if (opts.situationalContext !== undefined)
-            appendSituationalContext(meta.node_id, opts.situationalContext);
+        if (opts.situationalContext !== undefined) {
+            appendSituationalContext(meta.node_id, formatSituationalProse(opts.situationalContext));
+        }
         // Compound births such as `node fork` may need durable state in place after
         // the row and context directory exist but before the broker can observe it.
         // A preparation failure leaves the row crashed and never launches a partial

package/dist/core/runtime/stop-guard.js

@@ -23,16 +23,16 @@
 //                      final pushed. Re-prompt it to finish or escalate.
 import { hasActiveLiveSubscription, hasLiveMessageWait, hasPendingCancelOnWakeCron, getNode, contextDir } from '../canvas/index.js';
 import { activeBackgroundBashJobs } from '../bash-jobs.js';
-import { formatStructuredOutputReprompt, STALL_REPROMPT } from '../../shared/generated-context.js';
+import { formatCard, formatStructuredOutputReprompt, STALL_REPROMPT } from '../../shared/generated-context.js';
 import { readOutputRequest } from './structured-output.js';
 export { STALL_REPROMPT } from '../../shared/generated-context.js';
 /** Format the stop guard's reprompt for a valid structured-output request. */
 function formatValidStructuredOutputReprompt(schema) {
-    return formatStructuredOutputReprompt(JSON.stringify(schema, null, 2));
+    return formatCard('stop-guard', { reason: 'structured-output' }, formatStructuredOutputReprompt(JSON.stringify(schema, null, 2)));
 }
 /** Format the stop guard's reprompt for an invalid structured-output request file. */
 function formatInvalidStructuredOutputReprompt(error) {
-    return (`Structured-output request file is invalid and cannot be used: ${error}\n\n` +
+    return formatCard('stop-guard', { reason: 'structured-output' }, `Structured-output request file is invalid and cannot be used: ${error}\n\n` +
         `You have two options:\n` +
         `1. Remove the invalid file (the output-schema.json in your node directory has been corrupted)\n` +
         `2. Fix the corruption if you know the original request schema\n\n` +
@@ -96,5 +96,9 @@ export function evaluateStop(nodeId, signals, backgroundJobsRunning = activeBack
         || backgroundJobsRunning)
         return { action: 'allow', reason: 'awaiting' };
     // A terminal node with nothing live and no final pushed has stalled.
-    return { action: 'reprompt', reason: 'stalled', message: STALL_REPROMPT };
+    return {
+        action: 'reprompt',
+        reason: 'stalled',
+        message: formatCard('stop-guard', { reason: 'stalled' }, STALL_REPROMPT),
+    };
 }

package/dist/core/runtime/warm-pool.d.ts

@@ -17,7 +17,7 @@ export interface WarmRequest {
     kind: string;
     mode: Mode;
     /** Where the node runs — already resolved by the create handler (pin >
-     *  spawner > profile home), never a raw caller directory. */
+     *  spawner > launch cwd > profile home). */
     cwd: string;
     /** The RESOLVED profile id, or null for explicitly no profile. */
     profileId: string | null;

package/dist/core/runtime/warm-pool.js

@@ -47,10 +47,9 @@
 // and at daemon start for the most recently used profiles, so the FIRST node
 // after sitting down is warm too.
 //
-// The pool does not fan out per directory: a node runs in its profile's home
-// (`resolveNodeCwd` in the create handler), so the cwd a spare freezes is a
-// function of its profile, and "which spare serves this create" is in practice
-// a question about the profile alone.
+// A spare freezes the directory it was booted in, so a create launched from a
+// different directory than the last one simply misses and cold-spawns — the
+// pool serves the common case of returning to the same working directory.
 //
 // Nothing ever RESUMES a spare: the daemon's recovery sweep reads `listNodes`,
 // which hides the pool, so a spare whose broker dies (every daemon handover
@@ -63,7 +62,6 @@ import { claimWarmSpare, deleteNode, getNode, listNodes, listWarmSpares, registe
 import { recordedPidLiveness } from '../canvas/pid.js';
 import { nowIso } from '../fs-utils.js';
 import { spawnChildPrepared } from './spawn.js';
-import { profileHome } from '../profiles/manifest.js';
 import { buildLaunchSpec } from './launch.js';
 import { setModelLive } from './model-swap.js';
 import { setSituationalContextLive } from './situational-live.js';
@@ -335,10 +333,9 @@ export function prewarmRecentRecipes() {
             if (seen.has(profileId ?? ''))
                 continue;
             seen.add(profileId ?? '');
-            // The profile's home is where its next node will land. A profile without
-            // one (root, or a home since deleted) still gets a spare, keyed on the
-            // directory its last root actually ran in.
-            candidates.push({ cwd: profileHome(profileId) ?? row.cwd, profileId });
+            // A node lands in the directory its launch names, so the profile's last
+            // root predicts the next one better than the profile's home does.
+            candidates.push({ cwd: row.cwd, profileId });
             if (candidates.length >= PREWARM_PROFILES)
                 break;
         }