@north-light/crouter 0.3.154

package/dist/core/runtime/session-list-cache.d.ts

@@ -0,0 +1,53 @@
+import type { WireSessionInfo } from './broker-protocol.js';
+export declare function compactSessionSearchText(text: string): string;
+/** In-memory + file-backed cache keyed by absolute `.jsonl` path. One instance
+ *  per broker; the file is shared across brokers (last-writer-wins via atomic
+ *  rename — a lost update just costs one file's rebuild next open, never
+ *  corruption). */
+export declare class SessionListCache {
+    private readonly cacheFile;
+    private cache;
+    /** In-flight cwd scans keyed by normalized session dir, so an immediate
+     *  /resume that races the background prewarm (or a second identical open)
+     *  shares the one running jsonlFiles/stat/build pass instead of queueing a
+     *  redundant one behind it. */
+    private inflightDir;
+    private loadPromise;
+    private buildChain;
+    private persisting;
+    private persistAgain;
+    private persistTimer;
+    constructor(cacheFile: string);
+    /** Fire-and-forget warm of the cwd scope at broker start, so the first
+     *  `/resume` open after this broker launches is already warm. The cold scan
+     *  streams each file via readline (yields per chunk), so it never blocks the
+     *  broker loop — pre-warming beats worker threads here. Errors are swallowed
+     *  by the same paths that guard a normal open. */
+    prewarm(sessionDir: string): void;
+    /** Sessions for one cwd's session dir (the picker's default `cwd` scope).
+     *  Single-flight: an identical concurrent cwd open (prewarm ⇄ immediate
+     *  /resume) shares the in-flight promise rather than repeating the scan.
+     *  Incompatible cwd/all builds still serialize through the build chain. */
+    listDir(sessionDir: string): Promise<WireSessionInfo[]>;
+    private buildDir;
+    /** Sessions across every cwd's dir under the sessions root (`all` scope). */
+    listAll(sessionsRoot: string): Promise<WireSessionInfo[]>;
+    /** Serialize builds through a single chain: they mutate the shared cache map
+     *  and, cold, scan the same large corpus. Identical cwd opens are already
+     *  collapsed upstream by `listDir`'s in-flight sharing; chaining serializes
+     *  the remaining incompatible builds (a cwd scan vs an `all` scan) so they
+     *  never race map mutation or launch overlapping cold scans. */
+    private build;
+    private buildLocked;
+    /** Load the persisted cache exactly once, single-flight. Returns a shared
+     *  promise so a build that starts while the read is still in flight awaits the
+     *  same load rather than proceeding against a not-yet-populated map. */
+    private ensureLoaded;
+    private loadFromDisk;
+    /** Coalesce persists onto a single trailing timer so the tens-of-MB
+     *  `JSON.stringify` never runs on the reply path and rapid opens write once. */
+    private schedulePersist;
+    /** Atomic write (temp + rename) so a concurrent reader never sees a partial
+     *  file. Coalesces overlapping writes into one trailing flush. */
+    private persist;
+}

package/dist/core/runtime/session-list-cache.js

@@ -0,0 +1,406 @@
+// Broker-side cache for the `/resume` session picker's `list_sessions` reply.
+//
+// pi's `SessionManager.list()` reads EVERY `.jsonl` in a cwd's session dir in
+// full, line-by-line, to build each session's `allMessagesText` search field.
+// On a large corpus (3.3k files / 1.1 GiB here) that is ~3.6s of CPU-bound
+// JSON.parse on EVERY picker open — pi exposes no per-file entry point and no
+// cache. This module keeps a `(mtimeMs, size)`-keyed cache of the already-wire-
+// shaped, search-text-bounded `WireSessionInfo`: on each open it stats every
+// file (cheap — ~260ms for 3.3k) and rebuilds info ONLY for new/changed files,
+// reusing cached entries for the rest and dropping deleted ones. The cache is
+// persisted to one global JSON file so the first open after a broker restart is
+// also fast.
+//
+// `buildWireSessionInfo` below is a faithful mirror of pi's private
+// `buildSessionInfo` (node_modules/@earendil-works/pi-coding-agent/dist/core/
+// session-manager.js) — it is not exported, so the only way to rebuild a single
+// file's info without re-reading the whole corpus is to reproduce its parse.
+// Keep it in sync with pi's session-file format (CURRENT_SESSION_VERSION).
+import { createReadStream } from 'node:fs';
+import { readFile, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import { dirname, join, normalize } from 'node:path';
+/** Search-text bound: `allMessagesText` is searched on every query edit; pi's
+ *  unbounded value retains gigabytes in the viewer and turns key-repeat into GC
+ *  jitter. The opening and latest text keep search useful. */
+const SESSION_SEARCH_TEXT_CHARS = 1024;
+export function compactSessionSearchText(text) {
+    if (text.length <= SESSION_SEARCH_TEXT_CHARS)
+        return text;
+    const half = SESSION_SEARCH_TEXT_CHARS / 2;
+    return `${text.slice(0, half)} … ${text.slice(-half)}`;
+}
+const MAX_CONCURRENT_INFO_LOADS = 10;
+/** Persisted-file schema version. Bump whenever `CacheEntry`'s shape (or
+ *  `WireSessionInfo`'s) changes: on a version mismatch the whole file is
+ *  discarded and rebuilt from disk — no per-entry migration, no lenient
+ *  recovery (the cache is fully derivable). */
+const CACHE_SCHEMA_VERSION = 1;
+/** The full map is tens of MB (~15 MB for one cwd, ~46 MB for `all`); a
+ *  synchronous `JSON.stringify` of it must never sit on the reply path. Persists
+ *  are coalesced onto this trailing timer so rapid opens write at most once per
+ *  window, off the hot path. */
+const PERSIST_DEBOUNCE_MS = 2000;
+function isFiniteNonNeg(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0;
+}
+/** An optional field is valid iff absent/undefined or a string. */
+function isOptionalString(v) {
+    return v === undefined || typeof v === 'string';
+}
+/** Validate the full persisted `WireSessionInfo` shape. A same-version file whose
+ *  entry drifts from the current wire schema (any required field missing or
+ *  mistyped, any optional field the wrong type, non-finite/negative metadata)
+ *  must discard the whole cache and rebuild rather than feed a malformed entry to
+ *  the viewer or the sort. */
+function isValidWireInfo(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const i = v;
+    return (typeof i['path'] === 'string' &&
+        typeof i['id'] === 'string' &&
+        typeof i['cwd'] === 'string' &&
+        typeof i['created'] === 'string' &&
+        typeof i['modified'] === 'string' &&
+        isFiniteNonNeg(i['messageCount']) &&
+        typeof i['firstMessage'] === 'string' &&
+        typeof i['allMessagesText'] === 'string' &&
+        isOptionalString(i['name']) &&
+        isOptionalString(i['parentSessionPath']));
+}
+/** Shape-check a loaded entry — a well-formed-JSON file with the right version
+ *  but a stale entry shape would otherwise feed a malformed `WireSessionInfo` to
+ *  the viewer/sort. Any failure discards the whole file (rebuild). */
+function isValidEntry(e) {
+    if (typeof e !== 'object' || e === null)
+        return false;
+    const c = e;
+    return isFiniteNonNeg(c['mtimeMs']) && isFiniteNonNeg(c['size']) && isValidWireInfo(c['info']);
+}
+// ---- faithful mirror of pi's private buildSessionInfo -----------------------
+function parseLine(line) {
+    if (!line.trim())
+        return null;
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+}
+function extractTextContent(message) {
+    const content = message['content'];
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join(' ');
+}
+function messageActivityTime(entry) {
+    const message = entry['message'];
+    if (!message || !('content' in message))
+        return undefined;
+    const role = message['role'];
+    if (role !== 'user' && role !== 'assistant')
+        return undefined;
+    const ts = message['timestamp'];
+    if (typeof ts === 'number')
+        return ts;
+    const t = new Date(entry['timestamp']).getTime();
+    return Number.isNaN(t) ? undefined : t;
+}
+/** Build one session's wire info by streaming the file. Returns null for a
+ *  malformed/headerless file (matches pi, which drops those from the list). */
+async function buildWireSessionInfo(filePath) {
+    try {
+        const stats = await stat(filePath);
+        let header = null;
+        let messageCount = 0;
+        let firstMessage = '';
+        const allMessages = [];
+        let name;
+        let lastActivityTime;
+        const rl = createInterface({
+            input: createReadStream(filePath, { encoding: 'utf8' }),
+            crlfDelay: Infinity,
+        });
+        for await (const line of rl) {
+            const entry = parseLine(line);
+            if (!entry)
+                continue;
+            if (!header) {
+                if (entry['type'] !== 'session')
+                    return null;
+                header = entry;
+                continue;
+            }
+            if (entry['type'] === 'session_info') {
+                name = entry['name']?.trim() || undefined;
+            }
+            if (entry['type'] !== 'message')
+                continue;
+            messageCount++;
+            const activityTime = messageActivityTime(entry);
+            if (typeof activityTime === 'number') {
+                lastActivityTime = Math.max(lastActivityTime ?? 0, activityTime);
+            }
+            const message = entry['message'];
+            if (!message || !('content' in message))
+                continue;
+            const role = message['role'];
+            if (role !== 'user' && role !== 'assistant')
+                continue;
+            const textContent = extractTextContent(message);
+            if (!textContent)
+                continue;
+            allMessages.push(textContent);
+            if (!firstMessage && role === 'user')
+                firstMessage = textContent;
+        }
+        if (!header)
+            return null;
+        const cwd = typeof header['cwd'] === 'string' ? header['cwd'] : '';
+        const headerTime = typeof header['timestamp'] === 'string' ? new Date(header['timestamp']).getTime() : NaN;
+        const modified = typeof lastActivityTime === 'number' && lastActivityTime > 0
+            ? new Date(lastActivityTime)
+            : !Number.isNaN(headerTime)
+                ? new Date(headerTime)
+                : stats.mtime;
+        return {
+            path: filePath,
+            id: header['id'],
+            cwd,
+            name,
+            parentSessionPath: header['parentSession'],
+            created: new Date(header['timestamp']).toISOString(),
+            modified: modified.toISOString(),
+            messageCount,
+            firstMessage: firstMessage || '(no messages)',
+            // Cache the already-bounded wire form (the selector searches this field).
+            allMessagesText: compactSessionSearchText(allMessages.join(' ')),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ---- the cache ---------------------------------------------------------------
+/** In-memory + file-backed cache keyed by absolute `.jsonl` path. One instance
+ *  per broker; the file is shared across brokers (last-writer-wins via atomic
+ *  rename — a lost update just costs one file's rebuild next open, never
+ *  corruption). */
+export class SessionListCache {
+    cacheFile;
+    cache = new Map();
+    /** In-flight cwd scans keyed by normalized session dir, so an immediate
+     *  /resume that races the background prewarm (or a second identical open)
+     *  shares the one running jsonlFiles/stat/build pass instead of queueing a
+     *  redundant one behind it. */
+    inflightDir = new Map();
+    loadPromise = null;
+    buildChain = Promise.resolve();
+    persisting = false;
+    persistAgain = false;
+    persistTimer = null;
+    constructor(cacheFile) {
+        this.cacheFile = cacheFile;
+    }
+    /** Fire-and-forget warm of the cwd scope at broker start, so the first
+     *  `/resume` open after this broker launches is already warm. The cold scan
+     *  streams each file via readline (yields per chunk), so it never blocks the
+     *  broker loop — pre-warming beats worker threads here. Errors are swallowed
+     *  by the same paths that guard a normal open. */
+    prewarm(sessionDir) {
+        void this.listDir(sessionDir);
+    }
+    /** Sessions for one cwd's session dir (the picker's default `cwd` scope).
+     *  Single-flight: an identical concurrent cwd open (prewarm ⇄ immediate
+     *  /resume) shares the in-flight promise rather than repeating the scan.
+     *  Incompatible cwd/all builds still serialize through the build chain. */
+    listDir(sessionDir) {
+        const key = normalize(sessionDir);
+        const existing = this.inflightDir.get(key);
+        if (existing)
+            return existing;
+        const op = this.buildDir(key);
+        this.inflightDir.set(key, op);
+        // Attach both settlement handlers so the slot is cleared on success OR
+        // rejection, a rejected scan can never poison the next open, and a
+        // discarded prewarm rejection never becomes unhandled.
+        const clear = () => {
+            if (this.inflightDir.get(key) === op)
+                this.inflightDir.delete(key);
+        };
+        op.then(clear, clear);
+        return op;
+    }
+    buildDir(sessionDir) {
+        // Prune only keys directly in this cwd's dir. A cwd-scope open must not evict
+        // other cwds' cached entries: they weren't rescanned, so their absence from
+        // `files` says nothing about whether they still exist on disk.
+        return jsonlFiles(sessionDir).then((files) => this.build(files, (key) => dirname(key) === sessionDir));
+    }
+    /** Sessions across every cwd's dir under the sessions root (`all` scope). */
+    async listAll(sessionsRoot) {
+        let dirEntries;
+        try {
+            dirEntries = (await readdir(sessionsRoot, { withFileTypes: true }))
+                .filter((e) => e.isDirectory())
+                .map((e) => join(sessionsRoot, e.name));
+        }
+        catch {
+            return [];
+        }
+        const files = [];
+        for (const dir of dirEntries)
+            files.push(...(await jsonlFiles(dir)));
+        // Prune every cached key that is a direct grandchild of the sessions root
+        // (`<root>/<cwd-dir>/<file>.jsonl`). Using the path boundary rather than the
+        // set of dirs that still exist means a wholly-deleted cwd dir — absent from
+        // this scan — also has its stale entries evicted, so the persisted file never
+        // accumulates bloat from removed cwds.
+        return this.build(files, (key) => dirname(dirname(key)) === sessionsRoot);
+    }
+    /** Serialize builds through a single chain: they mutate the shared cache map
+     *  and, cold, scan the same large corpus. Identical cwd opens are already
+     *  collapsed upstream by `listDir`'s in-flight sharing; chaining serializes
+     *  the remaining incompatible builds (a cwd scan vs an `all` scan) so they
+     *  never race map mutation or launch overlapping cold scans. */
+    build(files, shouldPrune) {
+        const run = this.buildChain.then(() => this.buildLocked(files, shouldPrune));
+        // Keep the chain alive past a rejected build without leaking the rejection.
+        this.buildChain = run.then(() => { }, () => { });
+        return run;
+    }
+    async buildLocked(files, shouldPrune) {
+        await this.ensureLoaded();
+        const present = new Set(files);
+        let changed = false;
+        for (const key of this.cache.keys()) {
+            if (!present.has(key) && shouldPrune(key)) {
+                this.cache.delete(key);
+                changed = true;
+            }
+        }
+        // Positioned by file index so equal-`modified` ties keep readdir order
+        // deterministically (workers finish out of order); a stable sort preserves it.
+        const infos = new Array(files.length);
+        let next = 0;
+        const worker = async () => {
+            for (;;) {
+                const i = next++;
+                if (i >= files.length)
+                    return;
+                const file = files[i];
+                if (file === undefined)
+                    return;
+                const st = await stat(file).catch(() => null);
+                if (!st) {
+                    if (this.cache.delete(file))
+                        changed = true;
+                    continue;
+                }
+                const cached = this.cache.get(file);
+                if (cached && cached.mtimeMs === st.mtimeMs && cached.size === st.size) {
+                    infos[i] = cached.info;
+                    continue;
+                }
+                const info = await buildWireSessionInfo(file);
+                changed = true;
+                if (!info) {
+                    this.cache.delete(file);
+                    continue;
+                }
+                this.cache.set(file, { mtimeMs: st.mtimeMs, size: st.size, info });
+                infos[i] = info;
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(MAX_CONCURRENT_INFO_LOADS, files.length) }, () => worker()));
+        if (changed)
+            this.schedulePersist();
+        const result = infos.filter((x) => x !== undefined);
+        result.sort((a, b) => new Date(b.modified).getTime() - new Date(a.modified).getTime());
+        return result;
+    }
+    /** Load the persisted cache exactly once, single-flight. Returns a shared
+     *  promise so a build that starts while the read is still in flight awaits the
+     *  same load rather than proceeding against a not-yet-populated map. */
+    ensureLoaded() {
+        if (!this.loadPromise)
+            this.loadPromise = this.loadFromDisk();
+        return this.loadPromise;
+    }
+    async loadFromDisk() {
+        try {
+            const raw = JSON.parse(await readFile(this.cacheFile, 'utf8'));
+            // Version mismatch or shape drift → discard and rebuild. No lenient
+            // multi-path recovery: the cache is derivable, so a bad file is just
+            // overwritten on the next persist.
+            if (raw?.version !== CACHE_SCHEMA_VERSION || typeof raw.entries !== 'object')
+                return;
+            for (const [path, entry] of Object.entries(raw.entries)) {
+                if (!isValidEntry(entry)) {
+                    this.cache.clear();
+                    return;
+                }
+                this.cache.set(path, entry);
+            }
+        }
+        catch {
+            // Missing or corrupt cache file → start empty and rebuild.
+            this.cache.clear();
+        }
+    }
+    /** Coalesce persists onto a single trailing timer so the tens-of-MB
+     *  `JSON.stringify` never runs on the reply path and rapid opens write once. */
+    schedulePersist() {
+        if (this.persistTimer)
+            return;
+        this.persistTimer = setTimeout(() => {
+            this.persistTimer = null;
+            void this.persist();
+        }, PERSIST_DEBOUNCE_MS);
+        this.persistTimer.unref?.();
+    }
+    /** Atomic write (temp + rename) so a concurrent reader never sees a partial
+     *  file. Coalesces overlapping writes into one trailing flush. */
+    async persist() {
+        if (this.persisting) {
+            this.persistAgain = true;
+            return;
+        }
+        this.persisting = true;
+        const tmp = `${this.cacheFile}.${process.pid}.tmp`;
+        try {
+            const entries = {};
+            for (const [path, entry] of this.cache)
+                entries[path] = entry;
+            const payload = { version: CACHE_SCHEMA_VERSION, entries };
+            await writeFile(tmp, JSON.stringify(payload));
+            await rename(tmp, this.cacheFile);
+        }
+        catch {
+            // Best-effort: a failed persist only costs a rebuild next open. Clean up
+            // the temp file so a failed write never leaks it.
+            await unlink(tmp).catch(() => { });
+        }
+        finally {
+            this.persisting = false;
+            if (this.persistAgain) {
+                this.persistAgain = false;
+                void this.persist();
+            }
+        }
+    }
+}
+async function jsonlFiles(dir) {
+    try {
+        return (await readdir(dir)).filter((f) => f.endsWith('.jsonl')).map((f) => join(dir, f));
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,12 @@
+/** The `customType` stamped on the hidden custom message the inbox watcher
+ *  sends for an existing node's situational-context update. */
+export declare const SITUATIONAL_CONTEXT_CUSTOM_TYPE = "crtr-situational-context";
+/** 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. */
+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;

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

@@ -0,0 +1,48 @@
+// 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.
+//
+// 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.
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { situationalContextPath, nodeDir } from '../canvas/paths.js';
+/** The `customType` stamped on the hidden custom message the inbox watcher
+ *  sends for an existing node's situational-context update. */
+export const SITUATIONAL_CONTEXT_CUSTOM_TYPE = 'crtr-situational-context';
+/** 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. */
+export function appendSituationalContext(nodeId, text) {
+    const body = text.trim();
+    if (body === '')
+        return;
+    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) {
+    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) {
+    const text = readSituationalContext(nodeId);
+    return text === null ? '' : `<situational-context>\n${text}\n</situational-context>`;
+}

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

@@ -0,0 +1,9 @@
+/** 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.
+ *
+ *  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
+ *  the wrong situation is worse than a slow one), the same call the model swap
+ *  makes. A DORMANT node needs no delivery at all: its next revive renders the
+ *  sidecar into the kickoff. */
+export declare function setSituationalContextLive(nodeId: string, text: string): Promise<void>;

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

@@ -0,0 +1,40 @@
+// 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.
+//
+// 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.
+//
+// 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.
+ *
+ *  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
+ *  the wrong situation is worse than a slow one), the same call the model swap
+ *  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);
+    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
+    await deliverCustomMessageLive(nodeId, {
+        customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE,
+        content: block,
+        deliverAs: 'nextTurn',
+    });
+}

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

@@ -0,0 +1,31 @@
+import type { PiInvocation } from './launch.js';
+/** Sources A–C: the operational base shared by the broker boundary (this
+ *  module's `buildBrokerEnv`) and cron executor — the single shared definition
+ *  of "non-secret host state the runtime exposes to any spawned shell." Does not include
+ *  `inv.env`/`FRONT_DOOR_ENV` (source D), which is broker-specific. */
+export declare function buildOperationalEnvBase(opts: {
+    /** The TARGET node's cwd — never the calling/daemon process's own ambient
+     *  `process.cwd()`. Threaded into `readMergedLaunchConfig` so source C
+     *  (`spawnEnv.allow`) resolves from the TARGET's own project-scope config,
+     *  not whichever cwd happened to launch the process that builds this env. */
+    targetCwd: string;
+    /** The TARGET node's profile id — never the calling process's own ambient
+     *  `CRTR_PROFILE_ID`. `null`/`''` for no profile. */
+    targetProfileId: string | null;
+    host?: NodeJS.ProcessEnv;
+}): NodeJS.ProcessEnv;
+/** The one authoritative broker child env: sources A–C (the operational
+ *  base, resolved from the TARGET node's own cwd/profile — `inv.env`'s
+ *  `CRTR_NODE_CWD`/`CRTR_PROFILE_ID`, never this process's ambient
+ *  `process.cwd()`/`CRTR_PROFILE_ID`, which may be a launcher's or the
+ *  daemon's own and belong to an unrelated scope), E — the TARGET profile's
+ *  own `profile env` store (`readProfileEnvVars`, `core/profiles/env-store.ts`)
+ *  read directly off disk and injected regardless of the host env or any
+ *  `spawnEnv.allow` entry (setting a value there IS the consent to cross this
+ *  boundary), plus D — the trusted, crtr-constructed `inv.env` overlay and the
+ *  fork-bomb recursion guard `FRONT_DOOR_ENV=1`. D is layered last so crtr's
+ *  own constructed env always wins a name collision with a stored profile
+ *  value. Every broker launch (front-door root, managed child, `--root`,
+ *  every revive/daemon relaunch) funnels through `headlessBrokerHost.launch()`,
+ *  which calls this. */
+export declare function buildBrokerEnv(inv: PiInvocation): NodeJS.ProcessEnv;