@north-light/crouter 0.3.205 → 0.3.207

package/dist/core/__tests__/canvas-inbox-watcher.test.js

@@ -272,7 +272,7 @@ describe('canvas inbox watcher — hidden situational-context delivery', () => {
         await waitFor(() => pi.sentMessages.length >= 1);
         assert.equal(pi.injected.length, 0, 'a situational-only entry never triggers a visible digest');
         assert.equal(pi.sentMessages.length, 1, 'exactly one hidden custom message sent');
-        assert.match(pi.sentMessages[0].content, /<situational-context>/);
+        assert.match(pi.sentMessages[0].content, /<runtime kind="situational">/);
         assert.match(pi.sentMessages[0].content, /the user is mid-checkout on the store applet/);
         // Pins the seam the attach viewer keys its collapsed-rendering dispatch off
         // (src/clients/attach/render/chat-view.ts): a regression here (e.g. someone routing
@@ -299,7 +299,7 @@ describe('canvas inbox watcher — hidden situational-context delivery', () => {
         assert.match(pi.injected[0].content, /the visible message body/);
         assert.doesNotMatch(pi.injected[0].content, /hidden ambient checkout state/, 'ambient text never rides the visible digest');
         assert.equal(pi.sentMessages.length, 1, 'exactly one hidden custom message sent');
-        assert.match(pi.sentMessages[0].content, /<situational-context>/);
+        assert.match(pi.sentMessages[0].content, /<runtime kind="situational">/);
         assert.match(pi.sentMessages[0].content, /the hidden ambient checkout state/);
     });
     test('a situational-only entry survives a transient sendMessage failure — retried, not dropped', async () => {

package/dist/core/__tests__/context-intro.test.js

@@ -14,7 +14,7 @@ import { join } from 'node:path';
 import { closeDb } from '../canvas/db.js';
 import { apiSocketPath } from '../canvas/paths.js';
 import { spawnNode } from '../runtime/nodes.js';
-import { appendSituationalContext, situationalContextBlock } from '../runtime/situational-context.js';
+import { appendSituationalContext, formatSituationalProse, situationalContextEnvelope, } from '../runtime/situational-context.js';
 import registerCanvasContextIntro, { renderContextMessage, CONTEXT_INTRO_CUSTOM_TYPE, } from '../../pi-extensions/canvas-context-intro.js';
 import { buildContextBearings as buildContextIntro } from '../runtime/bearings.js';
 import { createApiServer } from '../../daemon/api/server.js';
@@ -48,15 +48,14 @@ after(() => {
     delete process.env['CRTR_HOME'];
     delete process.env['CRTR_NODE_ID'];
 });
-test('situational context rides the bearings as a sibling <situational-context> block; empty when unset', () => {
+test('the stored situational card rides the bearings body; absent when unset', () => {
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
-    assert.equal(situationalContextBlock(meta.node_id), '', 'no block until something is set');
-    assert.doesNotMatch(buildContextIntro(meta.node_id), /<situational-context>/, 'bearings carry no block when unset');
-    appendSituationalContext(meta.node_id, 'user is looking at the billing applet');
+    assert.equal(situationalContextEnvelope(meta.node_id), null, 'no card until something is set');
+    assert.doesNotMatch(buildContextIntro(meta.node_id), /kind="situational"/, 'bearings carry no card when unset');
+    appendSituationalContext(meta.node_id, formatSituationalProse('user is looking at the billing applet'));
     const block = buildContextIntro(meta.node_id);
-    assert.match(block, /<situational-context>/, 'block present once situational context is set');
-    assert.match(block, /user is looking at the billing applet/, 'block carries the ambient text');
-    assert.ok(!/<situational-context>[\s\S]*<\/crtr-bearings>/.test(block), 'the block is a sibling of <crtr-bearings>, not nested inside it');
+    assert.match(block, /<runtime kind="situational">/, 'card present once situational context is set');
+    assert.match(block, /user is looking at the billing applet/, 'card carries the ambient text');
 });
 function makeFakePi() {
     return {

package/dist/core/__tests__/kickoff.test.js

@@ -112,18 +112,18 @@ test('a fresh revive kickoff never carries situational context — it rides the
     // fresh/cycling revive kickoff prompt. It is still delivered on this path, but
     // hidden — canvas-context-intro's session_start handler re-fires on every
     // fresh/cycling revive (a new pi process boot rooting a fresh branch) and
-    // re-injects buildContextIntro(), which already carries the sidecar's
-    // <situational-context> block as a sibling of <crtr-bearings> (see
-    // context-intro.test.ts for that seam's own coverage). buildReviveKickoff must
-    // never duplicate it into the visible prompt.
+    // re-injects buildContextIntro(), which already carries the sidecar's stored
+    // situational card alongside <crtr-bearings> (see context-intro.test.ts for
+    // that seam's own coverage). buildReviveKickoff must never duplicate it into
+    // the visible prompt.
     const id = 'n3';
     const meta = createNode(node(id));
     appendSituationalContext(id, 'user is mid-checkout on the store applet');
     const kickoff = buildReviveKickoff(meta, drainBearings(meta));
-    assert.doesNotMatch(kickoff, /<situational-context>/, 'visible kickoff never carries the ambient block');
+    assert.doesNotMatch(kickoff, /kind="situational"/, 'visible kickoff never carries the ambient card');
     assert.doesNotMatch(kickoff, /mid-checkout on the store applet/, 'visible kickoff never carries the ambient text');
     const hidden = buildContextIntro(id);
-    assert.match(hidden, /<situational-context>/, 'delivered instead via the hidden bearings/context-intro seam');
+    assert.match(hidden, /<runtime kind="situational">/, 'delivered instead via the hidden bearings/context-intro seam');
     assert.match(hidden, /mid-checkout on the store applet/, 'hidden delivery carries the ambient text');
 });
 test('buildReviveKickoff is pure — building twice eats nothing', () => {

package/dist/core/canvas/paths.d.ts

@@ -59,8 +59,8 @@ export declare function reportsDir(nodeId: string): string;
 export declare function messagesDir(nodeId: string): string;
 export declare function nodeMetaPath(nodeId: string): string;
 export declare function inboxPath(nodeId: string): string;
-/** The node-owned ambient "current situation" sidecar — the latest hidden
- *  `<situational-context>` text injected into bearings/kickoff (see
+/** The node-owned ambient "current situation" sidecar — ONE rendered runtime
+ *  card, restated by the session-start bearings (see
  *  `runtime/situational-context.ts`), upserted in place rather than appended so
  *  only the newest applet/situation state is ever carried. Lives beside
  *  meta.json/inbox.jsonl (node-runtime state) rather than under context/ (the

package/dist/core/canvas/paths.js

@@ -137,8 +137,8 @@ export function nodeMetaPath(nodeId) {
 export function inboxPath(nodeId) {
     return join(nodeDir(nodeId), 'inbox.jsonl');
 }
-/** The node-owned ambient "current situation" sidecar — the latest hidden
- *  `<situational-context>` text injected into bearings/kickoff (see
+/** The node-owned ambient "current situation" sidecar — ONE rendered runtime
+ *  card, restated by the session-start bearings (see
  *  `runtime/situational-context.ts`), upserted in place rather than appended so
  *  only the newest applet/situation state is ever carried. Lives beside
  *  meta.json/inbox.jsonl (node-runtime state) rather than under context/ (the

package/dist/core/runtime/bearings.js

@@ -18,7 +18,7 @@ import { hostname } from 'node:os';
 import { cadenceDisplay } from '../wake.js';
 import { renderKnowledgeBlock, renderWorkspaceOpenDocs } from '../substrate/index.js';
 import { loadProfileManifest } from '../profiles/manifest.js';
-import { situationalContextBlock } from './situational-context.js';
+import { situationalContextEnvelope } from './situational-context.js';
 import { statusRank } from '../canvas/node-order.js';
 /** The bearings custom type is shared with every attached renderer. */
 export { CONTEXT_INTRO_CUSTOM_TYPE } from '../../shared/generated-context.js';
@@ -369,9 +369,10 @@ export function buildContextBearings(nodeId, seen) {
     // A workspace mount is the initial read of its root (`applies-to: "."`).
     const workspaceContext = renderWorkspaceOpenDocs(nodeId, seen);
     // Hidden applet/situation-origin ambient context (see situational-context.ts)
-    // — a SIBLING block, never nested under <crtr-bearings>, and never routed
-    // through the visible chat/digest path. '' when nothing was ever set.
-    const situational = situationalContextBlock(nodeId);
+    // — the stored `situational` card, placed in the bearings BODY, so it is a
+    // nested card inside the outer envelope. Never routed through the visible
+    // chat/digest path. '' when nothing was ever set.
+    const situational = situationalContextEnvelope(nodeId) ?? '';
     const projectCtx = node?.cwd !== undefined ? buildProjectContextBlock(node.cwd) : '';
     return [bearings.join('\n'), knowledge, workspaceContext, situational, projectCtx]
         .filter((s) => s !== '')

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, formatCard } from '../../../shared/generated-context.js';
+import { AUTH_FAULT_RECOVERY_BODY, formatCard, SITUATIONAL_CONTEXT_CUSTOM_TYPE, } 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';
@@ -794,6 +794,15 @@ export function createFrameDispatchContext(deps) {
         if (notWritable(client, 'drive the engine', frame.id))
             return;
         const via = currentSession().isStreaming ? 'steer' : 'prompt';
+        // Ordered context cards ahead of the body, inside this ONE frame handling,
+        // so no other client's send can interleave between a card and its body.
+        // Nothing is awaited: `sendCustomMessage` completes synchronously on both
+        // branches that apply here — idle appends to the session and starts NO turn
+        // (the body is the sole trigger), streaming queues on the same steer queue
+        // the body's `prompt({streamingBehavior:'steer'})` uses, preserving order.
+        for (const card of frame.cards ?? []) {
+            void currentSession().sendCustomMessage({ customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE, content: card, display: true }, via === 'steer' ? { deliverAs: 'steer' } : undefined).catch((error) => emitEvent({ level: 'error', event: 'broker.deliver.card_failed', error }));
+        }
         let delivered = false;
         const ackAccepted = () => {
             if (delivered)

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

@@ -25,12 +25,18 @@ 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;
+/** One-shot runtime cards an entry carries (rendered envelopes written by the
+ *  message API). They ride the delivery their own entry belongs to, so a note
+ *  can never land ahead of an unrelated person's message. */
+export declare function entryCards(entry: BrokerInboxEntry): readonly 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. */
+ *  only as a whole message, so mixing them attributes the card to the person.
+ *  `cards` are the one-shot context envelopes that go out ahead of `text`. */
 export interface InboxDelivery {
     kind: 'human' | 'card';
     text: string;
+    cards: readonly string[];
     entries: readonly BrokerInboxEntry[];
 }
 /** Split unread entries into ordered deliveries: each human entry verbatim, and

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

@@ -157,6 +157,15 @@ function cardEntry(entry, reportNodes) {
         ...(entry.disposition === undefined ? {} : { disposition: entry.disposition }),
     };
 }
+/** One-shot runtime cards an entry carries (rendered envelopes written by the
+ *  message API). They ride the delivery their own entry belongs to, so a note
+ *  can never land ahead of an unrelated person's message. */
+export function entryCards(entry) {
+    const cards = entry.data?.['cards'];
+    if (!Array.isArray(cards))
+        return [];
+    return cards.filter((card) => typeof card === 'string');
+}
 /** 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) {
@@ -176,13 +185,18 @@ export function coalesceBrokerInbox(entries, reportNodes) {
         if (sender === 'human') {
             for (const entry of items) {
                 const body = inlineBody(entry);
-                deliveries.push({ kind: 'human', text: body === '' ? entry.label : body, entries: [entry] });
+                deliveries.push({
+                    kind: 'human',
+                    text: body === '' ? entry.label : body,
+                    cards: entryCards(entry),
+                    entries: [entry],
+                });
             }
             continue;
         }
         if (cardSlot < 0) {
             cardSlot = deliveries.length;
-            deliveries.push({ kind: 'card', text: '', entries: [] });
+            deliveries.push({ kind: 'card', text: '', cards: [], entries: [] });
         }
         // The fallback to a CURRENT projected name is correct only for legacy
         // entries, which predate the producer's own `from_name` snapshot.
@@ -193,10 +207,12 @@ export function coalesceBrokerInbox(entries, 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.
+        const cardEntries = entries.filter((entry) => (entry.from ?? 'system') !== 'human');
         deliveries[cardSlot] = {
             kind: 'card',
             text: formatInboxCard(sections),
-            entries: entries.filter((entry) => (entry.from ?? 'system') !== 'human'),
+            cards: cardEntries.flatMap((entry) => entryCards(entry)),
+            entries: cardEntries,
         };
     }
     return deliveries;

package/dist/core/runtime/broker-extension-render.d.ts

@@ -3,6 +3,9 @@ export declare function editorLabelForBrokerNode(node: BrokerExtensionNodeDTO):
 /** Same environment-only project context rendered at normal boot, without a
  * canvas import. */
 export declare function buildProjectContextBlockForBroker(cwd: string): string;
+/** `situational` is the node's stored situational card, placed in the bearings
+ *  BODY — the one place in the system where a runtime card nests inside
+ *  another (see situational-context.ts). '' when none is set. */
 export declare function buildContextBearingsFromState(state: BrokerExtensionStateDTO, projectContext: string, situational?: string, seen?: Set<string>): string;
 export declare function buildForkBearingsFromState(state: BrokerExtensionStateDTO, situational?: string): string;
 export declare function renderPreferencesFromState(state: BrokerExtensionStateDTO): string;

package/dist/core/runtime/broker-extension-render.js

@@ -139,6 +139,9 @@ function reviewNote(node) {
     }
     return `You exist for one human review of \`${review.target_file}\`. The inherited conversation belongs to the origin node, not you — carry only the context needed for this review. The person's visible transcript begins at the boundary marker above; everything earlier is context they cannot see.`;
 }
+/** `situational` is the node's stored situational card, placed in the bearings
+ *  BODY — the one place in the system where a runtime card nests inside
+ *  another (see situational-context.ts). '' when none is set. */
 export function buildContextBearingsFromState(state, projectContext, situational = '', seen) {
     const { node } = state;
     const bearings = ['<crtr-bearings>', identity(state)];

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

@@ -134,6 +134,11 @@ export interface DeliverFrame {
     id: string;
     text: string;
     images?: ImageContent[];
+    /** Rendered runtime-card envelopes delivered ahead of `text`, in order, in
+     *  this ONE frame handling — so no other client's send can interleave
+     *  between a card and the body it belongs to. Each is its own custom
+     *  message and none triggers a turn; the body is the sole trigger. */
+    cards?: string[];
 }
 /** Run a `!` bash command — writable clients only. Maps to `session.executeBash()`,
  *  which runs the command, records a `bashExecution` message in context, and

package/dist/core/runtime/interactive-deliver.d.ts

@@ -6,8 +6,9 @@ export type LiveDeliverRoute = 'prompt' | 'steer';
 export type LiveInterruptOutcome = 'turn' | 'bash' | 'idle';
 /** Deliver `text` to a LIVE node's engine on its serialized frame loop. The
  *  broker routes it itself (idle → prompt, streaming → steer) and acks once
- *  routed; resolves with the route taken. */
-export declare function deliverLive(nodeId: string, text: string): Promise<LiveDeliverRoute>;
+ *  routed; resolves with the route taken. `cards` are rendered runtime-card
+ *  envelopes placed ahead of the body inside that same frame handling. */
+export declare function deliverLive(nodeId: string, text: string, cards?: readonly string[]): Promise<LiveDeliverRoute>;
 /** Abort whatever a LIVE node's engine is doing (turn or `!` bash). Resolves
  *  once the broker has PROCESSED the abort — which, on the single frame loop,
  *  also implies every earlier-accepted deliver was already routed (so a

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

@@ -14,14 +14,15 @@
 import { oneShotControllerRequest } from './broker-request.js';
 /** Deliver `text` to a LIVE node's engine on its serialized frame loop. The
  *  broker routes it itself (idle → prompt, streaming → steer) and acks once
- *  routed; resolves with the route taken. */
-export function deliverLive(nodeId, text) {
+ *  routed; resolves with the route taken. `cards` are rendered runtime-card
+ *  envelopes placed ahead of the body inside that same frame handling. */
+export function deliverLive(nodeId, text, cards = []) {
     return oneShotControllerRequest({
         nodeId,
         what: 'the interactive delivery',
         ackFor: 'deliver',
         correlated: true,
-        frame: (id) => ({ type: 'deliver', id, text }),
+        frame: (id) => ({ type: 'deliver', id, text, ...(cards.length > 0 ? { cards: [...cards] } : {}) }),
         result: (detail) => (detail === 'steer' ? 'steer' : 'prompt'),
     });
 }

package/dist/core/runtime/kickoff.js

@@ -283,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.

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

@@ -1,12 +1,19 @@
 /** 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 === '')
@@ -32,17 +46,22 @@ export function appendSituationalContext(nodeId, text) {
     mkdirSync(nodeDir(nodeId), { recursive: true });
     writeFileSync(situationalContextPath(nodeId), body + '\n', 'utf8');
 }
-/** Read the current situational context, or null if none was ever set. */
-export function readSituationalContext(nodeId) {
+/** Read the stored text, or null if none was ever set. Module-private:
+ *  `situationalContextEnvelope` is the one read, and it shape-checks. */
+function readSituationalContext(nodeId) {
     const p = situationalContextPath(nodeId);
     if (!existsSync(p))
         return null;
     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,25 +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 { formatCard } from '../../shared/generated-context.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
@@ -27,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 === '')
-        return; // blank text — appendSituationalContext no-ops, nothing to deliver
+    const envelope = situationalContextEnvelope(nodeId);
+    if (envelope === null)
+        return; // no sidecar at all — blank text on a node that never had one
     await deliverCustomMessageLive(nodeId, {
         customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE,
-        content: formatCard('situational', {}, block),
+        content: envelope,
         deliverAs: 'nextTurn',
     });
 }

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

@@ -67,10 +67,10 @@ export interface SpawnChildOpts {
     /** Preallocated node id, used when a managed worktree must be named before birth. */
     nodeId?: string;
     /** Hidden ambient "current situation" text — NOT the visible prompt/body.
-     *  Persisted via `appendSituationalContext` BEFORE launch so canvas-context-
-     *  intro's session_start bearings carry it as a `<situational-context>`
-     *  sibling from the node's very first turn. Passed through unchanged into a
-     *  scheduled node-birth command. Omit for no ambient context. */
+     *  Stored as a `situational` card BEFORE launch so canvas-context-intro's
+     *  session_start bearings nest it from the node's very first turn. Passed
+     *  through unchanged into a scheduled node-birth command. Omit for no
+     *  ambient context. */
     situationalContext?: string;
 }
 /** Resolve a `--fork-from` value to an ABSOLUTE `.jsonl` source path for the

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