@crouton-kit/crouter 0.3.60 → 0.3.62

package/dist/commands/node-worktree.js

@@ -29,24 +29,24 @@ function mapWorktreeError(err) {
 const worktreeClose = defineLeaf({
     name: 'close',
     description: 'land and close the current node-managed worktree',
-    whenToUse: 'you are inside the node that owns an open managed worktree and are ready to rebase it onto origin/main, push it to main, and (best-effort) remove the worktree and delete the branch before finishing',
+    whenToUse: 'you are inside the node that owns an open managed worktree and are ready to rebase it onto local main, fast-forward local main onto it, and (best-effort) remove the worktree and delete the branch before finishing',
     help: {
         name: 'node worktree close',
         summary: 'land and close the current node-managed worktree',
         params: [],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The caller node id whose managed worktree was closed.' },
-            { name: 'branch', type: 'string', required: true, constraint: 'The worktree branch that was fast-forwarded into main.' },
-            { name: 'pushed_sha', type: 'string', required: true, constraint: 'The landed commit SHA that was pushed to origin/main.' },
+            { name: 'branch', type: 'string', required: true, constraint: 'The worktree branch that was fast-forwarded into local main.' },
+            { name: 'landed_sha', type: 'string', required: true, constraint: 'The commit SHA that local main was fast-forwarded onto.' },
             { name: 'worktree_path', type: 'string', required: true, constraint: 'The managed worktree path that was closed (best-effort removed; see worktree_removed).' },
-            { name: 'worktree_removed', type: 'boolean', required: true, constraint: 'True when the worktree directory was removed; false means the push still landed (the close is done) but automatic removal failed and needs a manual follow-up.' },
+            { name: 'worktree_removed', type: 'boolean', required: true, constraint: 'True when the worktree directory was removed; false means the landing still happened (the close is done) but automatic removal failed and needs a manual follow-up.' },
             { name: 'worktree_remove_error', type: 'string', required: false, constraint: 'Present only when worktree_removed is false: the manual cleanup command to run.' },
-            { name: 'branch_deleted', type: 'boolean', required: true, constraint: 'True when the local branch was deleted; false means the push still landed (the close is done) but the local branch cleanup failed and needs a manual follow-up.' },
+            { name: 'branch_deleted', type: 'boolean', required: true, constraint: 'True when the local branch was deleted; false means the landing still happened (the close is done) but the local branch cleanup failed and needs a manual follow-up.' },
             { name: 'branch_delete_error', type: 'string', required: false, constraint: 'Present only when branch_deleted is false: the manual cleanup command to run.' },
         ],
         outputKind: 'object',
         effects: [
-            'Fetches origin/main, rebases the worktree onto it, fast-forwards origin/main, marks the node-managed worktree closed, then attempts (best-effort) to remove the worktree and delete the local branch.',
+            'Rebases the worktree onto local main, fast-forwards local main onto it (never pushes to origin), marks the node-managed worktree closed, then attempts (best-effort) to remove the worktree and delete the local branch.',
         ],
     },
     run: async () => {
@@ -63,9 +63,9 @@ const worktreeClose = defineLeaf({
     },
     render: (r) => {
         const branch = String(r['branch'] ?? '');
-        const sha = String(r['pushed_sha'] ?? '');
+        const sha = String(r['landed_sha'] ?? '');
         const path = String(r['worktree_path'] ?? '');
-        let base = `Managed worktree landed — branch ${branch} pushed as ${sha}.`;
+        let base = `Managed worktree landed — local main fast-forwarded to ${branch} at ${sha}.`;
         const notes = [];
         if (r['worktree_removed'] === false) {
             notes.push(String(r['worktree_remove_error'] ?? `worktree checkout at ${path} could not be removed automatically.`));
@@ -84,7 +84,7 @@ const worktreeClose = defineLeaf({
 export const nodeWorktreeBranch = defineBranch({
     name: 'worktree',
     description: 'manage a node-owned git worktree — close the one born by `node new --worktree`',
-    whenToUse: 'you are inside a node that was spawned with `node new --worktree` and are ready to land it: rebase onto origin/main, push, and close the worktree. Symmetric with `node new --worktree`, which births it',
+    whenToUse: 'you are inside a node that was spawned with `node new --worktree` and are ready to land it: rebase onto local main, fast-forward local main onto it, and close the worktree. Symmetric with `node new --worktree`, which births it',
     help: {
         name: 'node worktree',
         summary: 'manage a node-owned git worktree — birth is `node new --worktree`; this branch closes it',

package/dist/commands/node.js

@@ -32,10 +32,12 @@ import { WorktreeError } from '../core/worktree.js';
 import { closeNode } from '../core/runtime/close.js';
 import { isBrokerLive, setModelLive, persistDormantModel } from '../core/runtime/model-swap.js';
 import { appendInbox } from '../core/feed/inbox.js';
+import { appendSituationalContext } from '../core/runtime/situational-context.js';
 import { readMergedLaunchConfig } from '../core/config.js';
 import { listProfiles } from '../core/profiles/manifest.js';
 import { stateBlock } from '../core/help.js';
-import { getNode, updateNode, listNodes, subscribe, unsubscribe, subscriptionsOf, subscribersOf, contextDir, reportsDir, nodeArtifacts, readContextTokens, view, armTrigger, listTriggers, cancelTrigger, TriggerArmError, fullName, } from '../core/canvas/index.js';
+import { getNode, updateNode, listNodes, subscribe, unsubscribe, contextDir, reportsDir, nodeArtifacts, readContextTokens, armTrigger, listTriggers, cancelTrigger, TriggerArmError, fullName, } from '../core/canvas/index.js';
+import { localCanvasSource } from '../core/canvas/source.js';
 // Past this much context, an ORCHESTRATOR that spawns a managed child is better
 // off yielding than holding its fat window open for the child's result: the
 // child's finish revives it fresh against its roadmap, so a clean window absorbs
@@ -132,10 +134,11 @@ const nodeNew = defineLeaf({
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name (tmux window + resume picker). Defaults to the kind.' },
             { kind: 'flag', name: 'parent', type: 'string', required: false, constraint: 'Parent node id. Defaults to the calling node (CRTR_NODE_ID).' },
             { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an INDEPENDENT root instead of a managed child: no parent (top-level on the canvas), NO subscription back to you (you are NOT woken by it), resident lifecycle. It records spawned_by=you for provenance and is brought forefront so it can be driven directly. Use for a node you hand off and do not manage (e.g. a sub-orchestrator a human will discuss with). Mutually exclusive with --worktree.' },
-            { kind: 'flag', name: 'worktree', type: 'bool', required: false, constraint: 'Use when the child will COMMIT to the repo while you or other agents may also be editing it — the worktree isolates its work so nothing collides; skip it for read-only work or when the child is the sole writer. Creates a crouter-managed git worktree for the spawned child, keyed by the child node id, at `~/.crouter/canvas/worktrees/<node-id>/` on branch `crtr/<node-id>` based on `origin/main`; the child\'s cwd is pinned there, and it lands the work serially onto origin/main later with `crtr node worktree close`. Mutually exclusive with --root.' },
+            { kind: 'flag', name: 'worktree', type: 'bool', required: false, constraint: 'Use when the child will COMMIT to the repo while you or other agents may also be editing it — the worktree isolates its work so nothing collides; skip it for read-only work or when the child is the sole writer. Creates a crouter-managed git worktree for the spawned child, keyed by the child node id, at `~/.crouter/canvas/worktrees/<node-id>/` on branch `crtr/<node-id>` based on local `main`; the child\'s cwd is pinned there, and it lands the work serially onto local main later with `crtr node worktree close`. Mutually exclusive with --root.' },
             { kind: 'flag', name: 'fork-from', type: 'string', required: false, constraint: 'FORK the new node from an existing pi conversation instead of starting it fresh: pass a node id (forks from that node\'s session), an absolute session `.jsonl` path, or a partial pi session uuid. pi copies that whole history into a NEW session for the child (the source is untouched), then the prompt is delivered as the next message — i.e. the child wakes up as a continuation of that conversation. Use to branch exploratory work off a node that already built up the context you need, instead of re-deriving it. One-shot at birth: the fork resumes its own session thereafter.' },
             { kind: 'flag', name: 'model', type: 'string', required: false, constraint: 'Override the model the node runs on: exact `provider/id` (e.g. openai-codex/gpt-5.5), a `provider/tier` (anthropic|openai + ultra|strong|medium|light, e.g. openai/ultra — pin a specific model family, useful for spawning cross-family children), a bare capability TIER (ultra|strong|medium|light), or a family alias (opus|sonnet|haiku). Must resolve to a concrete model OFFLINE — unlike `node config --model`, no live broker exists yet at spawn to free-text substring-search a registry. Omit to use the kind\'s persona default (advisor=ultra, explore=light, most other builtins=strong). The override is durable — it survives revives and polymorphs (promote/demote).' },
-            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Select the profile this node runs under — an exact profile id or a unique manifest name (see the <profiles> list below, or `crtr profile list`). Omit to INHERIT the calling node\'s current profile (root has none, so an uninherited child has none either). --root does NOT reset this — it only means top-level, still inherits/uses the selected profile unless this overrides it.' },
+            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Select the profile this node runs under — an exact profile id or a unique manifest name (see the <profiles> list below, or `crtr profile list`). Omit to INHERIT the calling node\'s current profile (which may be none, e.g. a historical null-profile parent). A shell/no-spawner root with no profile coverage instead runs the startup selector and can persist the stable root profile. --root does NOT reset this — it only means top-level, still inherits/uses the selected profile unless this overrides it.' },
+            { kind: 'flag', name: 'situational-context', type: 'string', required: false, constraint: 'Hidden ambient context — current situation (e.g. which applet/page spawned this), NOT the visible prompt. Appended as a `<situational-context>` sibling block in the injected bearings, never as visible chat. Preserved unchanged into a deferred --at/--every/--when node_birth recipe.' },
             { kind: 'flag', name: 'output-schema', type: 'string', required: false, constraint: 'Path to a JSON Schema file, or inline JSON beginning with `{`. The spawned node gets a `submit` tool shaped by this schema, must call it to finish, and the submitted JSON is written to the final report and context/result.json. Rejected with trigger flags in this version.' },
             { kind: 'flag', name: 'at', type: 'string', required: false, constraint: 'DEFER the birth to a one-shot clock trigger at this future time instead of spawning now — a duration ("5m","1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00", host-local or in --tz). Required unless --every is given (the cadence then sets the first fire). Mutually exclusive with --when.' },
             { kind: 'flag', name: 'every', type: 'string', required: false, constraint: 'SPAWN-CRON: re-birth a fresh node on this cadence — a duration ("6h","30m") or a 5-field cron / @alias ("0 9 * * *","@daily"). Combine with --at to anchor the first fire, then recur normally. Min cadence 60s. With --when, this instead sets the PREDICATE EVALUATION cadence (required), not a repeating birth.' },
@@ -161,7 +164,7 @@ const nodeNew = defineLeaf({
         dynamicState: () => [kindsStateBlock(), profilesStateBlock()].join('\n'),
         outputKind: 'object',
         effects: [
-            'Spawning now: creates a node under ~/.crouter/canvas/nodes/<id>/ and indexes it in canvas.db. Default (managed child): parent auto-subscribes (active) and is woken on the child\'s pushes. With --root: no subscription — records a spawned_by edge for provenance only. With --worktree: also creates a managed git worktree at ~/.crouter/canvas/worktrees/<node-id>/ on branch crtr/<node-id> based on origin/main; the child closes it later with `crtr node worktree close` before finishing. With --output-schema: writes nodes/<id>/output-schema.json in terminal mode; the node must call submit, which writes context/result.json and pushes final. Launches the node\'s engine as a detached broker (the only host); a managed child opens NO viewer, a --root opens one in your current tmux session.',
+            'Spawning now: creates a node under ~/.crouter/canvas/nodes/<id>/ and indexes it in canvas.db. Default (managed child): parent auto-subscribes (active) and is woken on the child\'s pushes. With --root: no subscription — records a spawned_by edge for provenance only. With --worktree: also creates a managed git worktree at ~/.crouter/canvas/worktrees/<node-id>/ on branch crtr/<node-id> based on local main; the child closes it later with `crtr node worktree close` before finishing. With --output-schema: writes nodes/<id>/output-schema.json in terminal mode; the node must call submit, which writes context/result.json and pushes final. Launches the node\'s engine as a detached broker (the only host); a managed child opens NO viewer, a --root opens one in your current tmux session.',
             'Armed (--at/--every/--when): inserts one detached `new`/`node_birth` triggers row (node_id NULL, owner=you, parent/cwd resolved now); NO node and NO window exist until fire time. The daemon spawns from the stored recipe at fire time, re-deriving the launch spec live.',
         ],
     },
@@ -189,6 +192,8 @@ const nodeNew = defineLeaf({
         }
         const model = modelSpec;
         const profile = input['profile'];
+        const situationalContextRaw = input['situationalContext']?.trim();
+        const situationalContext = situationalContextRaw !== undefined && situationalContextRaw !== '' ? situationalContextRaw : undefined;
         const outputSchema = parseOutputSchemaValue(input['outputSchema']);
         const at = input['at']?.trim();
         const every = input['every']?.trim();
@@ -215,7 +220,7 @@ const nodeNew = defineLeaf({
         }
         if (!triggered) {
             try {
-                const res = await spawnChild({ kind, mode, cwd, name, prompt, parent, root, worktree, forkFrom, model, profile });
+                const res = await spawnChild({ kind, mode, cwd, name, prompt, parent, root, worktree, forkFrom, model, profile, situationalContext });
                 if (outputSchema !== null)
                     writeOutputSchema(res.node.node_id, 'terminal', outputSchema);
                 return {
@@ -263,6 +268,7 @@ const nodeNew = defineLeaf({
             ...(forkFrom !== undefined ? { forkFrom } : {}),
             ...(model !== undefined ? { model } : {}),
             ...(profile !== undefined ? { profile } : {}),
+            ...(situationalContext !== undefined ? { situationalContext } : {}),
         };
         const id = `tr-${newNodeId()}`;
         if (hasWhen) {
@@ -404,14 +410,15 @@ const nodeList = defineLeaf({
         const hangingOnly = input['hanging'] === true;
         // Graph scope (--under): self + subscription descendants. Validate the anchor
         // so a typo'd id is a structured error, not a silently-empty roster.
+        const canvasSource = localCanvasSource;
         let scope;
         if (under !== undefined && under !== '') {
-            if (getNode(under) === null) {
+            if (await canvasSource.getNode(under) === null) {
                 throw new InputError({ error: 'not_found', message: `no node: ${under}`, next: 'List nodes with `crtr node inspect list`, then pass a real id to --under.' });
             }
-            scope = new Set([under, ...view(under)]);
+            scope = new Set([under, ...(await canvasSource.view(under))]);
         }
-        const rows = listNodes(status !== undefined ? { status } : undefined).filter((row) => {
+        const rows = (await canvasSource.listNodes(status !== undefined ? { status } : undefined)).filter((row) => {
             if (scope !== undefined && !scope.has(row.node_id))
                 return false;
             if (kinds !== undefined && !kinds.includes(row.kind))
@@ -439,8 +446,8 @@ const nodeList = defineLeaf({
 // ---------------------------------------------------------------------------
 // Enrich a bare subscription edge with the neighbor's name/kind/status so a
 // debugger reads who a report/manager IS without a second `show` per id.
-function enrichNeighbor(ref) {
-    const n = getNode(ref.node_id);
+async function enrichNeighborFromSource(source, ref) {
+    const n = await source.getNode(ref.node_id);
     return {
         node_id: ref.node_id,
         name: n ? fullName(n) : '(missing)',
@@ -478,12 +485,13 @@ const nodeShow = defineLeaf({
     },
     run: async (input) => {
         const id = input['node'];
-        const node = getNode(id);
+        const canvasSource = localCanvasSource;
+        const node = await canvasSource.getNode(id);
         if (node === null) {
             throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
         }
-        const reports = subscriptionsOf(id).map(enrichNeighbor);
-        const managers = subscribersOf(id).map(enrichNeighbor);
+        const reports = await Promise.all((await canvasSource.subscriptionsOf(id)).map((ref) => enrichNeighborFromSource(canvasSource, ref)));
+        const managers = await Promise.all((await canvasSource.subscribersOf(id)).map((ref) => enrichNeighborFromSource(canvasSource, ref)));
         const arts = nodeArtifacts(id, ['report', 'doc', 'roadmap']);
         const artifacts = {
             report: arts.filter((a) => a.source === 'report').length,
@@ -1138,6 +1146,7 @@ const nodeMsg = defineLeaf({
             { kind: 'flag', name: 'until', type: 'string', required: false, constraint: 'Self-only: bind a deadline that decides your next action — you wake on the first inbox message, or at this time if none arrives (whichever fires first cancels the other), and the body is the policy to follow in the no-message case. One-shot, urgent tier, ≤ 1 per node (a new --until replaces any prior). Mutually exclusive with --at, --every, --when, --fresh, --tier, and --timeout. Requires --self and a body.' },
             { kind: 'flag', name: 'timeout', type: 'string', required: false, constraint: 'Wall-clock bound for a --when predicate — a duration or absolute time after which the trigger is consumed and the owner gets one urgent notice. Required with --when; rejected otherwise.' },
             { kind: 'flag', name: 'tz', type: 'string', required: false, constraint: 'IANA zone for a calendar --every, a bare-ISO --at, or a bare-ISO --until (default: host-local). Valid only alongside --at/--every/--until; rejected with --when, and rejected when acting immediately (no trigger flags) since none of those have anything to parse it against.' },
+            { kind: 'flag', name: 'situational-context', type: 'string', required: false, constraint: 'Hidden ambient context — current situation, NOT the visible message body. Upserted onto the target\'s node-owned sidecar and delivered as a `<situational-context>` sibling block, never as visible chat/digest. Valid with a body, with --fresh, or alone (then no body is required). Immediate delivery only — rejected with --at, --every, --when, or --until.' },
         ],
         output: [
             { name: 'mode', type: 'string', required: true, constraint: '"inbox_message", "fresh_revive", or "deadline_message" — what this message enacts.' },
@@ -1181,7 +1190,12 @@ const nodeMsg = defineLeaf({
         const hasAt = at !== undefined && at !== '';
         const hasEvery = every !== undefined && every !== '';
         const outputSchema = parseOutputSchemaValue(input['outputSchema']);
+        const situationalContextRaw = input['situationalContext']?.trim();
+        const hasSituational = situationalContextRaw !== undefined && situationalContextRaw !== '';
         // --- Validation per the approved flag matrix ---
+        if (hasSituational && (hasAt || hasEvery || hasWhen || hasUntil)) {
+            throw new InputError({ error: 'situational_context_immediate_only', message: '--situational-context is only valid for immediate delivery (no --at, --every, --when, or --until)', field: 'situational-context', next: 'Drop the trigger flag(s), or drop --situational-context.' });
+        }
         if (hasUntil && !isSelf) {
             throw new InputError({ error: 'until_self_only', message: '--until is self-only', field: 'until', next: 'Use --self, or drop --until.' });
         }
@@ -1374,6 +1388,10 @@ const nodeMsg = defineLeaf({
                     next: 'Seed a goal/roadmap first, or drop --fresh so the woken context carries a message.',
                 });
             }
+            // Update the sidecar BEFORE the revive so buildReviveKickoff's disk read
+            // picks up this update on the fresh kickoff it is about to assemble.
+            if (hasSituational)
+                appendSituationalContext(targetId, situationalContextRaw);
             reviveNode(targetId, { resume: false });
             return {
                 mode: 'fresh_revive',
@@ -1383,8 +1401,8 @@ const nodeMsg = defineLeaf({
                 guidance: `Fresh-revived ${isSelf ? 'yourself' : targetId} now — it resumes a clean window re-reading its roadmap/disk.`,
             };
         }
-        if (!hasBody && outputSchema === null) {
-            throw new InputError({ error: 'empty_body', message: 'a message body is required (or --fresh / --when / --output-schema)', field: 'body', next: 'Pass the message after the target flags or on stdin, or pass --output-schema to grant a one-off structured-output request.' });
+        if (!hasBody && !hasSituational && outputSchema === null) {
+            throw new InputError({ error: 'empty_body', message: 'a message body is required (or --fresh / --when / --output-schema / --situational-context)', field: 'body', next: 'Pass the message after the target flags or on stdin, pass --output-schema to grant a one-off structured-output request, or pass --situational-context alone for a hidden-only update.' });
         }
         const targetMeta = getNode(targetId);
         if (targetMeta === null) {
@@ -1392,15 +1410,42 @@ const nodeMsg = defineLeaf({
         }
         if (outputSchema !== null)
             writeOutputSchema(targetId, 'oneoff', outputSchema);
+        // Update the sidecar BEFORE appending the inbox entry that will wake the
+        // watcher's flush() — it reads the sidecar fresh on delivery.
+        if (hasSituational)
+            appendSituationalContext(targetId, situationalContextRaw);
         const tier = (hasTier ? tierRaw : 'normal');
         const from = process.env['CRTR_NODE_ID'] ?? 'human';
-        const messageBody = hasBody
-            ? body
-            : 'A one-off structured-output request has been granted. Call the `submit` tool with a result matching the requested schema before you stop; after submit succeeds, continue normally.';
-        // A body over the preview bound spills to a ref file; appendInbox clips the
-        // inline preview and the receiver dereferences the ref for the full text,
-        // same as any other report.
-        appendInbox(targetId, { from, tier, kind: 'message', label: messageBody.split('\n')[0].slice(0, 120), data: { body: messageBody } });
+        if (hasBody || outputSchema !== null) {
+            const messageBody = hasBody
+                ? body
+                : 'A one-off structured-output request has been granted. Call the `submit` tool with a result matching the requested schema before you stop; after submit succeeds, continue normally.';
+            // A body over the preview bound spills to a ref file; appendInbox clips the
+            // inline preview and the receiver dereferences the ref for the full text,
+            // same as any other report. `situational: true` tells the inbox watcher's
+            // flush() to ALSO deliver the hidden <situational-context> custom message
+            // ahead of this visible digest — the ambient TEXT itself never rides here.
+            appendInbox(targetId, {
+                from,
+                tier,
+                kind: 'message',
+                label: messageBody.split('\n')[0].slice(0, 120),
+                data: { body: messageBody, ...(hasSituational ? { situational: true } : {}) },
+            });
+        }
+        else {
+            // Situational context alone: a hidden-only wake marker. `situationalOnly`
+            // tells the inbox watcher to exclude this entry from the visible digest
+            // entirely — it exists purely to trigger flush() into delivering the hidden
+            // custom message, never as a chat line.
+            appendInbox(targetId, {
+                from,
+                tier,
+                kind: 'message',
+                label: '(ambient context updated)',
+                data: { situational: true, situationalOnly: true },
+            });
+        }
         // A direct message wakes any node: if the target has no live window
         // (done/dead/idle-released), revive it so its inbox-watcher delivers this.
         let woke = false;
@@ -1413,7 +1458,10 @@ const nodeMsg = defineLeaf({
                 /* best-effort wake */
             }
         }
-        return { mode: 'inbox_message', armed: false, target, delivered: true, revived: woke, guidance: woke ? 'Delivered — the dormant target was revived to receive it.' : 'Delivered.' };
+        const guidance = !hasBody && hasSituational
+            ? (woke ? 'Situational context delivered as hidden context — the dormant target was revived to receive it; no visible message was sent.' : 'Situational context delivered as hidden context; no visible message was sent.')
+            : (woke ? 'Delivered — the dormant target was revived to receive it.' : 'Delivered.');
+        return { mode: 'inbox_message', armed: false, target, delivered: true, revived: woke, guidance };
     },
     render: (r) => {
         if (r['armed'] === true) {

package/dist/commands/sys/doctor.js

@@ -72,6 +72,7 @@ function faultRemediation(fault) {
         protocol: 'fix the protocol mismatch',
         other: 'fix the underlying issue',
         wedged: 'read `crtr memory read wedged-child-on-runaway-bash` — if a runaway subprocess is to blame, kill it (not the node); if the broker had no subprocess, the daemon already SIGTERM-kicked it to resume on its own (recheck node status; nudge it if it came back idle)',
+        'model-not-found': 'pass a valid `--model provider/id` or configure credentials for an authenticated provider, then revive the node (`crtr node lifecycle revive <id>`)',
     };
     const progress = fault.retry.disposition === 'auto'
         ? fault.retry.by === 'client'

package/dist/core/__tests__/broker-fork-seam.test.js

@@ -31,9 +31,19 @@ import { test, before, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION, } from '../runtime/broker-sdk.js';
 import { buildBrokerSession } from '../runtime/broker.js';
+// M-9 (broker.ts fault-and-die model gate): buildBrokerSession with no cfg.model
+// now calls the REAL SDK's modelRegistry.getAvailable() and faults if it's empty
+// — which it always is on a host/CI runner with no authenticated provider. This
+// test drives the fork branch only, so it registers the SAME hermetic
+// fake-but-authenticated model the C3 wiring tests use, rather than depending on
+// ambient host credentials (which don't exist in CI — see broker-sdk-wiring's
+// c3-custom-provider-ext.ts fixture).
+const HERE = dirname(fileURLToPath(import.meta.url));
+const C3_EXT = join(HERE, 'fixtures', 'c3-custom-provider-ext.ts');
 // The REAL engine — bypasses the CRTR_BROKER_ENGINE fake entirely (the whole
 // point: the fake omits forkFrom, so only the real SDK can prove the branch).
 const realEngine = {
@@ -70,7 +80,12 @@ test('D2 broker fork branch: buildBrokerSession(cfg.forkFrom) yields a NEW id +
     //    the same recipe a `node new --fork-from <id>` boot produces. The OLD broker
     //    THREW in this branch ("--fork is not supported by the headless broker"), so
     //    if broker.ts:~1106 reverts to that throw, this rejects and the test goes RED.
-    const cfg = { cwd: dir, extensionPaths: [], forkFrom: srcFile };
+    const cfg = {
+        cwd: dir,
+        extensionPaths: [C3_EXT],
+        forkFrom: srcFile,
+        model: 'c3prov/c3model',
+    };
     let session;
     let resuming;
     await assert.doesNotReject(async () => {

package/dist/core/__tests__/broker-snapshot-history.test.js

@@ -27,9 +27,18 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION, } from '../runtime/broker-sdk.js';
 import { buildBrokerSession, snapshotMessages } from '../runtime/broker.js';
+// M-9 (broker.ts fault-and-die model gate): a boot with no cfg.model now calls
+// the REAL SDK's modelRegistry.getAvailable() and faults if it's empty, which it
+// always is on a host/CI runner with no authenticated provider. This test only
+// exercises snapshot/history reconstruction, so it registers the same hermetic
+// fake-but-authenticated model the C3 wiring tests use instead of depending on
+// ambient host credentials (see broker-sdk-wiring's c3-custom-provider-ext.ts).
+const HERE = dirname(fileURLToPath(import.meta.url));
+const C3_EXT = join(HERE, 'fixtures', 'c3-custom-provider-ext.ts');
 const realEngine = {
     createAgentSessionServices,
     createAgentSessionFromServices,
@@ -73,8 +82,9 @@ test('broker welcome snapshot serves the persisted history, not pi\u2019s sliced
         // 2. Revive: the broker resumes the closed session via the SERVICES path.
         const { session } = await buildBrokerSession(realEngine, {
             cwd,
-            extensionPaths: [],
+            extensionPaths: [C3_EXT],
             resumeSessionPath: sessionFile,
+            model: 'c3prov/c3model',
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
         });
         try {

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

@@ -13,6 +13,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import registerCanvasInboxWatcher from '../../pi-extensions/canvas-inbox-watcher.js';
 import { appendInbox } from '../feed/inbox.js';
+import { appendSituationalContext, SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../runtime/situational-context.js';
 // Drive the watcher's injectable cadence seam (CRTR_WATCHER_TICK_MS /
 // CRTR_WATCHER_DEBOUNCE_MS) at a fast tempo so the test sleeps milliseconds, not
 // seconds. SETTLE_MS still allows a resolve+seed tick, a read tick, and the
@@ -36,8 +37,10 @@ function makeFakePi() {
     const handlers = {};
     return {
         injected: [],
+        sentMessages: [],
         on(e, h) { handlers[e] = h; },
         sendUserMessage(content, options) { this.injected.push({ content, deliverAs: options?.deliverAs }); },
+        sendMessage(message) { this.sentMessages.push(message); },
         fire(e, ev, ctx) { handlers[e]?.(ev, ctx); },
     };
 }
@@ -105,3 +108,79 @@ describe('canvas inbox watcher — finished-node delivery', () => {
         assert.equal(pi.injected[0].deliverAs, 'followUp', 'a normal update is not urgent → followUp');
     });
 });
+describe('canvas inbox watcher — hidden situational-context delivery', () => {
+    test('a situational-only entry (no visible body) never reaches the visible digest, only the hidden sendMessage', async () => {
+        freshNode('node-situational-only');
+        appendSituationalContext('node-situational-only', 'the user is mid-checkout on the store applet');
+        const pi = makeFakePi();
+        disposers.push(registerCanvasInboxWatcher(pi));
+        appendInbox('node-situational-only', {
+            from: null,
+            tier: 'normal',
+            kind: 'message',
+            label: '(ambient context updated)',
+            data: { situational: true, situationalOnly: true },
+        });
+        await wait(SETTLE_MS);
+        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, /the user is mid-checkout on the store applet/);
+        // Pins the seam the attach viewer keys its collapsed-rendering dispatch off
+        // (src/clients/attach/chat-view.ts): a regression here (e.g. someone routing
+        // the situational update through a different/generic customType) would make
+        // the viewer fall through to the prominent, uncollapsed CustomMessageComponent.
+        assert.equal(pi.sentMessages[0].customType, SITUATIONAL_CONTEXT_CUSTOM_TYPE);
+    });
+    test('a combined entry (visible body + situational flag) puts the body in the digest and the ambient text ONLY in the hidden sendMessage', async () => {
+        freshNode('node-situational-combined');
+        appendSituationalContext('node-situational-combined', 'the hidden ambient checkout state');
+        const pi = makeFakePi();
+        disposers.push(registerCanvasInboxWatcher(pi));
+        appendInbox('node-situational-combined', {
+            from: 'child-3',
+            tier: 'normal',
+            kind: 'message',
+            label: 'visible update',
+            data: { body: 'the visible message body', situational: true },
+        });
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 1, 'the visible body still reaches the digest');
+        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, /the hidden ambient checkout state/);
+    });
+    test('a situational-only entry survives a transient sendMessage failure — retried, not dropped', async () => {
+        // Durability regression: the cursor advances past a situational-only entry
+        // BEFORE flush() runs, so a swallowed sendMessage failure with no re-queue
+        // would drop the hidden wake permanently (never re-read from the inbox,
+        // never retried) — unlike the visible digest path, which already re-queues
+        // on failure. This pins the same durability contract for the hidden path.
+        freshNode('node-situational-retry');
+        appendSituationalContext('node-situational-retry', 'retry me please');
+        const pi = makeFakePi();
+        let calls = 0;
+        const realSendMessage = pi.sendMessage.bind(pi);
+        pi.sendMessage = (message, options) => {
+            calls += 1;
+            if (calls === 1)
+                throw new Error('transient failure');
+            realSendMessage(message, options);
+        };
+        disposers.push(registerCanvasInboxWatcher(pi));
+        appendInbox('node-situational-retry', {
+            from: null,
+            tier: 'normal',
+            kind: 'message',
+            label: '(ambient context updated)',
+            data: { situational: true, situationalOnly: true },
+        });
+        await wait(SETTLE_MS * 3);
+        assert.ok(calls >= 2, 'sendMessage retried after the first failure instead of being swallowed once');
+        assert.equal(pi.injected.length, 0, 'still never reaches the visible digest');
+        assert.equal(pi.sentMessages.length, 1, 'eventually delivered exactly once after the retry succeeds');
+        assert.match(pi.sentMessages[0].content, /retry me please/);
+    });
+});

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

@@ -18,6 +18,7 @@ import { spawnNode } from '../runtime/nodes.js';
 import { promote } from '../runtime/promote.js';
 import { personaDrift } from '../runtime/persona.js';
 import { memoryDir } from '../runtime/memory.js';
+import { appendSituationalContext, situationalContextBlock } from '../runtime/situational-context.js';
 import registerCanvasContextIntro, { buildContextIntro, renderContextMessage, CONTEXT_INTRO_CUSTOM_TYPE, } from '../../pi-extensions/canvas-context-intro.js';
 let home;
 before(() => {
@@ -69,6 +70,16 @@ test('worker bearings: base framing + <knowledge> block, NO across-cycles framin
     assert.doesNotMatch(block, /refresh cycles/, 'no across-cycles framing for a terminal worker');
     assert.match(block, /<\/crtr-bearings>/);
 });
+test('situational context rides the bearings as a sibling <situational-context> block; empty 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');
+    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');
+});
 test('node-local doc identity honors explicit frontmatter `name`, not the physical filename', () => {
     // node-local docs follow the one substrate identity rule (resolveDocName):
     // an explicit `name:` renders and dedups under that name, not the filename.

package/dist/core/__tests__/fixtures/fake-engine.d.ts

@@ -173,13 +173,18 @@ declare class FakeSession {
     private dispatch;
     private runDialog;
 }
+interface FakeModel {
+    provider: string;
+    id: string;
+}
 interface FakeServices {
     resourceLoader: ResourceLoader;
     modelRegistry: {
-        find: (provider: string, id: string) => {
-            provider: string;
-            id: string;
-        } | undefined;
+        find: (provider: string, id: string) => FakeModel | undefined;
+        getAvailable: () => FakeModel[];
+        getAll: () => FakeModel[];
+        hasConfiguredAuth: (model: FakeModel) => boolean;
+        refresh: () => void;
     };
 }
 export declare function createAgentSessionServices(options: {

package/dist/core/__tests__/fixtures/fake-engine.js

@@ -757,6 +757,7 @@ class FakeSession {
         }
     }
 }
+const FAKE_AVAILABLE_MODEL = { provider: 'fake', id: 'fake-model' };
 export async function createAgentSessionServices(options) {
     const loader = new DefaultResourceLoader({
         cwd: options.cwd,
@@ -767,10 +768,17 @@ export async function createAgentSessionServices(options) {
     await loader.reload();
     return {
         resourceLoader: loader,
-        // A minimal model stub for any spec: the lifecycle harness passes no boot
-        // model (so this is never hit at boot), but the set_model regression test
-        // drives the broker's findModelSpec → session.setModel path through it.
-        modelRegistry: { find: (provider, id) => ({ provider, id }) },
+        modelRegistry: {
+            // A minimal model stub for any spec — the set_model regression test drives
+            // the broker's findModelSpec → session.setModel path through it.
+            find: (provider, id) => ({ provider, id }),
+            // Always-authenticated single fake model — the M-9 no-boot-model branch
+            // (broker.ts) picks `available[0]` and must never see an empty list here.
+            getAvailable: () => [FAKE_AVAILABLE_MODEL],
+            getAll: () => [FAKE_AVAILABLE_MODEL],
+            hasConfiguredAuth: () => true,
+            refresh: () => { },
+        },
     };
 }
 export async function createAgentSessionFromServices(options) {

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

@@ -15,6 +15,8 @@ import { reportsDir } from '../canvas/paths.js';
 import { closeDb } from '../canvas/db.js';
 import { drainBearings, buildReviveKickoff, writeYieldMessage, yieldMessagePath, } from '../runtime/kickoff.js';
 import { appendInbox, readCursor } from '../feed/inbox.js';
+import { appendSituationalContext } from '../runtime/situational-context.js';
+import { buildContextIntro } from '../../pi-extensions/canvas-context-intro.js';
 let home;
 function node(id) {
     return {
@@ -103,6 +105,25 @@ test('a fresh revive is pointed at its subscriptions\' on-disk report history (c
     assert.ok(/node inspect artifacts <node-id> --type report/.test(msg), 'points at full per-node expansion');
     assert.ok(/node inspect artifacts <node-id> --type inbox/.test(msg), 'points at the cursor-independent full-history replay');
 });
+test('a fresh revive kickoff never carries situational context — it rides the hidden bearings seam instead', () => {
+    // Hiddenness regression: situational context must stay OUT of the visible
+    // 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.
+    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, /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, /mid-checkout on the store applet/, 'hidden delivery carries the ambient text');
+});
 test('buildReviveKickoff is pure — building twice eats nothing', () => {
     const id = 'n2';
     const meta = createNode(node(id));