@crouton-kit/crouter 0.3.60 → 0.3.62

package/dist/core/__tests__/spawn-root.test.js

@@ -12,6 +12,7 @@ import { nodeDir } from '../canvas/paths.js';
 import { spawnNode } from '../runtime/nodes.js';
 import { spawnChild, resolveSpawner } from '../runtime/spawn.js';
 import { headlessBrokerHost } from '../runtime/host.js';
+import { ROOT_PROFILE_ID } from '../profiles/manifest.js';
 let home;
 function spawner(id) {
     return {
@@ -104,3 +105,62 @@ test('spawnChild crashes the node when launch/preflight throws', async () => {
         rmSync(home, { recursive: true, force: true });
     }
 });
+test('spawnChild: a root from a shell gets the stable root profile id', async () => {
+    const previousHome = process.env.HOME;
+    const previousNodeId = process.env.CRTR_NODE_ID;
+    const previousTmux = process.env.TMUX;
+    const previousTmuxPane = process.env.TMUX_PANE;
+    const env = process.env;
+    const localHome = mkdtempSync(join(tmpdir(), 'crtr-spawn-root-home-'));
+    const localCwd = mkdtempSync(join(tmpdir(), 'crtr-spawn-root-cwd-'));
+    const originalLaunch = headlessBrokerHost.launch;
+    const previousStdinTty = Object.getOwnPropertyDescriptor(process.stdin, 'isTTY');
+    const previousStdoutTty = Object.getOwnPropertyDescriptor(process.stdout, 'isTTY');
+    try {
+        process.env.HOME = localHome;
+        Object.defineProperty(process.stdin, 'isTTY', { value: false, configurable: true, writable: true });
+        Object.defineProperty(process.stdout, 'isTTY', { value: false, configurable: true, writable: true });
+        Reflect.deleteProperty(env, 'CRTR_NODE_ID');
+        delete process.env.TMUX;
+        delete process.env.TMUX_PANE;
+        headlessBrokerHost.launch = (_nodeId, _inv, _opts) => ({
+            pid: 4242,
+            exited: Promise.resolve(),
+        });
+        const result = await spawnChild({ kind: 'developer', cwd: localCwd, root: true, prompt: 'task' });
+        const node = getNode(result.node.node_id);
+        assert.equal(node.profile_id, ROOT_PROFILE_ID, 'the root spawn persists the stable root profile id');
+        assert.equal(node.parent, null, 'a shell root has no spine parent');
+        assert.equal(node.lifecycle, 'resident', 'a shell root stays resident');
+        assert.equal(result.node.profile_id, ROOT_PROFILE_ID, 'the returned node view carries the stable root profile id');
+    }
+    finally {
+        headlessBrokerHost.launch = originalLaunch;
+        if (previousHome === undefined)
+            delete process.env.HOME;
+        else
+            process.env.HOME = previousHome;
+        if (previousNodeId === undefined)
+            Reflect.deleteProperty(env, 'CRTR_NODE_ID');
+        else
+            env.CRTR_NODE_ID = previousNodeId;
+        if (previousTmux === undefined)
+            delete process.env.TMUX;
+        else
+            process.env.TMUX = previousTmux;
+        if (previousTmuxPane === undefined)
+            delete process.env.TMUX_PANE;
+        else
+            process.env.TMUX_PANE = previousTmuxPane;
+        if (previousStdinTty === undefined)
+            Reflect.deleteProperty(process.stdin, 'isTTY');
+        else
+            Object.defineProperty(process.stdin, 'isTTY', previousStdinTty);
+        if (previousStdoutTty === undefined)
+            Reflect.deleteProperty(process.stdout, 'isTTY');
+        else
+            Object.defineProperty(process.stdout, 'isTTY', previousStdoutTty);
+        rmSync(localHome, { recursive: true, force: true });
+        rmSync(localCwd, { recursive: true, force: true });
+    }
+});

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

@@ -32,7 +32,8 @@ function node(id, over = {}) {
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-worktree-home-'));
     process.env['CRTR_HOME'] = home;
-    // Bare "remote" the source repo pushes to, so `origin/main` resolves.
+    // Bare "remote" wired up as origin so the test can prove landing NEVER pushes
+    // to it (managed worktrees are based on and land onto local `main` only).
     remoteDir = mkdtempSync(join(tmpdir(), 'crtr-worktree-remote-'));
     run(['init', '--bare'], remoteDir);
     sourceDir = mkdtempSync(join(tmpdir(), 'crtr-worktree-source-'));
@@ -83,3 +84,25 @@ test('closeManagedWorktree recreates the worktree path as a tombstone dir so the
     const meta = getNode(nodeId);
     assert.equal(meta?.managed_worktree?.state, 'closed');
 });
+// Landing is purely local: a commit made in the managed worktree must advance
+// the source repo's LOCAL main to that commit, and origin/main must stay put
+// (close never pushes to origin).
+test('closeManagedWorktree fast-forwards local main to the worktree tip without touching origin', () => {
+    const nodeId = 'wt-close-2';
+    const originMainBefore = gitSync(['rev-parse', 'origin/main'], sourceDir).stdout.trim();
+    const wt = createManagedWorktree(sourceDir, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    // Commit real work inside the managed worktree.
+    writeFileSync(join(wt.path, 'feature.txt'), 'work\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'feature'], wt.path);
+    const workSha = gitSync(['rev-parse', 'HEAD'], wt.path).stdout.trim();
+    const result = closeManagedWorktree(nodeId);
+    assert.equal(result.landed_sha, workSha, 'landed_sha should be the committed work');
+    // Local main in the source (primary) checkout advanced to the work.
+    const localMainAfter = gitSync(['rev-parse', 'main'], sourceDir).stdout.trim();
+    assert.equal(localMainAfter, workSha, 'local main must fast-forward to the worktree tip');
+    // origin/main is untouched — nothing was pushed.
+    const originMainAfter = gitSync(['rev-parse', 'origin/main'], sourceDir).stdout.trim();
+    assert.equal(originMainAfter, originMainBefore, 'origin/main must not move — landing is local-only');
+});

package/dist/core/canvas/browse/app.d.ts

@@ -1,4 +1,6 @@
+import { type CanvasSource } from '../source.js';
 export declare function runBrowse(opts?: {
     returnPane?: string;
     cwd?: string;
+    source?: CanvasSource;
 }): Promise<void>;

package/dist/core/canvas/browse/app.js

@@ -9,8 +9,8 @@
 // `pi --session` directly (see reviveNode() in revive.ts for the desync hazard).
 import { execFileSync } from 'node:child_process';
 import { resolve } from 'node:path';
-import { dashboardRowsAll, enrichRows, loadPreview, renderForest } from '../render.js';
-import { listNodes, subscriptionsOf, getNode } from '../canvas.js';
+import { dashboardRowsAllFromSource, enrichRowsFromSource, loadPreviewFromSource, renderForestFromSource } from '../render.js';
+import { localCanvasSource } from '../source.js';
 import { closeNode } from '../../runtime/close.js';
 import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from '../../tui/terminal.js';
 import { buildTree, flatten, pruneNode, TABS } from './model.js';
@@ -27,19 +27,25 @@ function viewportHeight(rowsTotal, search, previewOn) {
     return Math.max(1, rows - headerHeight(search) - 1 /* footer */ - previewH);
 }
 export async function runBrowse(opts = {}) {
+    const source = opts.source ?? localCanvasSource;
     // No TTY → print the static forest and exit 0 (no raw mode).
     if (!process.stdin.isTTY) {
-        process.stdout.write(renderForest() + '\n');
+        process.stdout.write(await renderForestFromSource(source) + '\n');
         return;
     }
     // Snapshot the canvas. Drop kind:'human' control-plane decks — they have no pi
     // session, so `node focus` refuses them; they are never a navigation/resume
     // target (mirrors the node focus guard).
-    const rows = dashboardRowsAll().filter((r) => r.kind !== 'human');
-    const rootIds = listNodes()
+    const rows = (await dashboardRowsAllFromSource(source)).filter((r) => r.kind !== 'human');
+    const nodeRows = await source.listNodes();
+    const rootIds = nodeRows
         .filter((n) => n.parent === null && n.kind !== 'human')
         .map((n) => n.node_id);
-    const tree = buildTree(rows, rootIds, (id) => subscriptionsOf(id).map((s) => s.node_id));
+    const childIds = new Map();
+    await Promise.all(nodeRows.map(async (n) => {
+        childIds.set(n.node_id, (await source.subscriptionsOf(n.node_id).catch(() => [])).map((s) => s.node_id));
+    }));
+    const tree = buildTree(rows, rootIds, (id) => childIds.get(id) ?? []);
     const totalNodes = tree.nodes.size;
     // Default cwd scope = the dir browse was launched from (the request). The popup
     // / command passes --cwd; resolve it so it compares cleanly against stored cwds.
@@ -80,6 +86,9 @@ export async function runBrowse(opts = {}) {
     // Safety net: an uncaught throw in the (un-unit-tested) keystroke path must
     // never strand the tty in raw + alt-screen + hidden-cursor.
     process.once('exit', cleanup);
+    const logAsyncFailure = (label, err) => {
+        process.stderr.write(`[crtr browse] ${label}: ${String(err?.message ?? err)}\n`);
+    };
     /** On-demand kick of a hanging node: shell `node lifecycle revive <id> --now`
      *  (which SIGTERMs the live broker — the daemon resumes it). Synchronous +
      *  quiet (stdio ignored) so it never takes over the TUI; best-effort. */
@@ -123,7 +132,7 @@ export async function runBrowse(opts = {}) {
         if (state.cursor < 0)
             state.cursor = 0;
     };
-    const flush = () => {
+    const flush = async () => {
         const size = getTerminalSize();
         const previewOn = state.preview && visible.length > 0;
         const viewport = viewportHeight(size.rows, state.search, previewOn);
@@ -145,12 +154,12 @@ export async function runBrowse(opts = {}) {
             if (r !== undefined)
                 slice.push(r);
         }
-        enrichRows(slice);
+        await enrichRowsFromSource(source, slice);
         const cur = curRow();
         if (cur !== undefined) {
             const r = rowOf(cur.id);
             if (r !== undefined)
-                loadPreview(r);
+                await loadPreviewFromSource(source, r);
         }
         const frame = renderFrame({
             tree, visible, tab: state.tab, cursor: state.cursor, scrollOffset: state.scrollOffset,
@@ -189,7 +198,7 @@ export async function runBrowse(opts = {}) {
     // subtree, tear down each engine, and detach every attached viewer. Then reflect
     // the new terminal statuses back into the live snapshot so the row updates in
     // place (no re-snapshot). Best-effort: a teardown failure never wedges the picker.
-    const doClose = (id) => {
+    const doClose = async (id) => {
         state.pendingClose = null;
         let closed = [];
         try {
@@ -199,7 +208,7 @@ export async function runBrowse(opts = {}) {
             return; // unknown/already-gone node — nothing to reflect
         }
         for (const cid of closed) {
-            const m = getNode(cid);
+            const m = await source.getNode(cid);
             if (m === null) {
                 // Reaped, not parked: an EMPTY node (0k ctx, no assistant message) is
                 // hard-deleted by closeNode (row + dir gone). Splice it out of the tree so
@@ -258,6 +267,30 @@ export async function runBrowse(opts = {}) {
     // phase) has appended its chars, so N rapid keys collapse to ONE recompute+paint
     // and no keystroke is ignored. The sort may still take a moment — that's fine.
     let searchRepaintScheduled = false;
+    let flushInFlight = false;
+    let flushQueued = false;
+    const scheduleFlush = () => {
+        flushQueued = true;
+        if (flushInFlight)
+            return;
+        flushInFlight = true;
+        void (async () => {
+            try {
+                while (flushQueued && !restored) {
+                    flushQueued = false;
+                    await flush();
+                }
+            }
+            finally {
+                flushInFlight = false;
+                if (flushQueued && !restored)
+                    scheduleFlush();
+            }
+        })().catch(() => {
+            cleanup();
+            process.exit(1);
+        });
+    };
     const scheduleSearchRepaint = () => {
         if (searchRepaintScheduled)
             return;
@@ -265,7 +298,7 @@ export async function runBrowse(opts = {}) {
         setImmediate(() => {
             searchRepaintScheduled = false;
             recompute();
-            flush();
+            scheduleFlush();
         });
     };
     const onKeySearch = (input, key) => {
@@ -276,7 +309,7 @@ export async function runBrowse(opts = {}) {
             state.query = '';
             state.sort = 'tree';
             recompute();
-            flush();
+            scheduleFlush();
             return;
         }
         if (key.return) {
@@ -288,7 +321,7 @@ export async function runBrowse(opts = {}) {
             const firstMatch = visible.findIndex((v) => v.matched);
             if (firstMatch >= 0)
                 state.cursor = firstMatch;
-            flush();
+            scheduleFlush();
             return;
         }
         if (key.backspace) {
@@ -325,13 +358,13 @@ export async function runBrowse(opts = {}) {
         // other key so the confirm is modal.
         if (state.pendingClose !== null) {
             if (input === 'y' || input === 'Y') {
-                doClose(state.pendingClose);
-                flush();
+                const target = state.pendingClose;
+                void doClose(target).then(() => scheduleFlush()).catch(() => scheduleFlush());
                 return;
             }
             // n / Esc / anything else cancels the close.
             state.pendingClose = null;
-            flush();
+            scheduleFlush();
             return;
         }
         const row = curRow();
@@ -341,22 +374,22 @@ export async function runBrowse(opts = {}) {
         // Move.
         if (key.upArrow || input === 'k') {
             state.cursor = Math.max(0, state.cursor - 1);
-            flush();
+            scheduleFlush();
             return;
         }
         if (key.downArrow || input === 'j') {
             state.cursor = Math.max(0, Math.min(visible.length - 1, state.cursor + 1));
-            flush();
+            scheduleFlush();
             return;
         }
         if (input === 'g') {
             state.cursor = 0;
-            flush();
+            scheduleFlush();
             return;
         }
         if (input === 'G') {
             state.cursor = Math.max(0, visible.length - 1);
-            flush();
+            scheduleFlush();
             return;
         }
         // Expand / descend.
@@ -370,7 +403,7 @@ export async function runBrowse(opts = {}) {
                     state.cursor += 1; // already expanded → step onto first child
                 }
             }
-            flush();
+            scheduleFlush();
             return;
         }
         // Collapse / ascend.
@@ -387,7 +420,7 @@ export async function runBrowse(opts = {}) {
                         state.cursor = idx;
                 }
             }
-            flush();
+            scheduleFlush();
             return;
         }
         // Toggle collapse.
@@ -399,18 +432,18 @@ export async function runBrowse(opts = {}) {
                     state.collapsed.delete(row.id);
                 recompute(row.id);
             }
-            flush();
+            scheduleFlush();
             return;
         }
         // Tabs.
         if (key.tab || input === ']') {
             cycleTab(1);
-            flush();
+            scheduleFlush();
             return;
         }
         if (key.shiftTab || input === '[') {
             cycleTab(-1);
-            flush();
+            scheduleFlush();
             return;
         }
         if (input >= '1' && input <= '4') {
@@ -421,40 +454,43 @@ export async function runBrowse(opts = {}) {
                 state.scrollOffset = 0;
                 recompute();
             }
-            flush();
+            scheduleFlush();
             return;
         }
         // Close-out the selected node (+ its exclusive subtree). If anything in that
         // subtree is actively streaming, confirm first (y/n); otherwise close at once.
         if (input === 'x') {
-            if (row !== undefined) {
-                if (anyStreaming(row.id))
-                    state.pendingClose = row.id;
-                else
-                    doClose(row.id);
+            if (row === undefined) {
+                scheduleFlush();
+                return;
+            }
+            if (anyStreaming(row.id)) {
+                state.pendingClose = row.id;
+                scheduleFlush();
+                return;
             }
-            flush();
+            void doClose(row.id).then(() => scheduleFlush()).catch(() => scheduleFlush());
             return;
         }
         // Sort / scope / residents / preview.
         if (input === 's') {
             cycleSort();
-            flush();
+            scheduleFlush();
             return;
         }
         if (input === 'c') {
             toggleScope();
-            flush();
+            scheduleFlush();
             return;
         }
         if (input === 'r') {
             toggleResidents();
-            flush();
+            scheduleFlush();
             return;
         }
         if (input === 'p') {
             state.preview = !state.preview;
-            flush();
+            scheduleFlush();
             return;
         }
         // Search. Starting a search ranks by relevance (decision) so the best prompt/
@@ -466,7 +502,7 @@ export async function runBrowse(opts = {}) {
             state.cursor = 0;
             state.scrollOffset = 0;
             recompute();
-            flush();
+            scheduleFlush();
             return;
         }
         // Revive now (on-demand kick): for a HANGING node, SIGTERM the live broker so
@@ -480,7 +516,7 @@ export async function runBrowse(opts = {}) {
                 if (r?.hanging != null)
                     reviveNow(row.id);
             }
-            flush();
+            scheduleFlush();
             return;
         }
         // Resume.
@@ -516,7 +552,7 @@ export async function runBrowse(opts = {}) {
         recompute(selfId);
     }
     setupTerminal();
-    flush();
+    await flush();
     // Background corpus warmer: after the instant first paint, progressively enrich
     // + load-preview every row (in small chunks, off the event loop) so the prompt
     // super-search corpus lights up shortly after the instant name/kind/id search.
@@ -525,24 +561,23 @@ export async function runBrowse(opts = {}) {
     const warmRows = [...tree.nodes.values()].map((n) => n.row);
     let warmIdx = 0;
     const WARM_CHUNK = 30;
-    const warmChunk = () => {
+    const warmChunk = async () => {
         if (restored)
             return;
         const end = Math.min(warmIdx + WARM_CHUNK, warmRows.length);
         const slice = warmRows.slice(warmIdx, end);
-        enrichRows(slice);
-        for (const r of slice)
-            loadPreview(r);
+        await enrichRowsFromSource(source, slice);
+        await Promise.all(slice.map((r) => loadPreviewFromSource(source, r)));
         warmIdx = end;
         // A live search may match the freshly-warmed prompts → recompute + repaint.
         if (state.search && state.query !== '') {
             recompute(curRow()?.id);
-            flush();
+            scheduleFlush();
         }
         if (warmIdx < warmRows.length)
-            setImmediate(warmChunk);
+            setImmediate(() => { void warmChunk().catch((err) => logAsyncFailure('background warm failed', err)); });
     };
-    setImmediate(warmChunk);
+    setImmediate(() => { void warmChunk().catch((err) => logAsyncFailure('background warm failed', err)); });
     await new Promise(() => {
         const onData = (data) => {
             try {
@@ -559,6 +594,6 @@ export async function runBrowse(opts = {}) {
             }
         };
         process.stdin.on('data', onData);
-        process.stdout.on('resize', flush);
+        process.stdout.on('resize', scheduleFlush);
     });
 }

package/dist/core/canvas/db.js

@@ -353,8 +353,9 @@ CREATE TABLE IF NOT EXISTS canvas_meta (
  *  (`<slug>-<id>`) a node runs under, chosen once at spawn (inherited from the
  *  spawner, or `--profile`). Durable IDENTITY mirrored from meta.json like
  *  `cwd`/`host_kind` (NOT runtime like `pane`), so it survives an index rebuild
- *  via the `IDENTITY_KEYS`/`upsertRow` path. Defaults NULL (root/no-profile);
- *  no data backfill. Additive, forward-only. */
+ *  via the `IDENTITY_KEYS`/`upsertRow` path. Defaults NULL for historical
+ *  root/no-profile rows; new root conversations use the stable root profile
+ *  id instead. No data backfill. Additive, forward-only. */
 function addProfileIdColumn(db) {
     const columns = nodeColumns(db);
     addNodeColumnIfMissing(db, columns, 'profile_id', `ALTER TABLE nodes ADD COLUMN profile_id TEXT;`);

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

@@ -2,6 +2,7 @@ export * from './types.js';
 export * from './labels.js';
 export * from './paths.js';
 export * from './canvas.js';
+export * from './source.js';
 export * from './history.js';
 export * from './focuses.js';
 export * from './triggers.js';

package/dist/core/canvas/index.js

@@ -4,6 +4,7 @@ export * from './types.js';
 export * from './labels.js';
 export * from './paths.js';
 export * from './canvas.js';
+export * from './source.js';
 export * from './history.js';
 export * from './focuses.js';
 export * from './triggers.js';

package/dist/core/canvas/nav-model.d.ts

@@ -91,14 +91,16 @@ export declare function isHumanAsk(id: string): boolean;
 export declare function convoChildIds(id: string): string[];
 /** Live reports (active|idle) of a node — the DOWN set in BASE. */
 export declare function liveReports(id: string): string[];
-/** Direct navigable children — used for the ⤳ badge and fold counts (human-ask
- *  nodes excluded, so the count matches what the tree actually shows). */
+/** Direct navigable children — used for the ⤳ badge (human-ask nodes excluded,
+ *  so the count matches what the tree actually shows). */
 export declare function childCount(id: string): number;
 /** Climb first-manager edges from `self` to the ancestry root (cycle-guarded). */
 export declare function climbRoot(self: string): string;
 /** Space-joined ids of a node's subtree (cursor-relative {subtree} var). */
 export declare function subtreeIds(root: string): string[];
-/** ⤳M direct-children badge — only on orchestrator rows. */
+/** ⤳M direct-children badge — the single child-count signal, shown on any row
+ *  with navigable children (folded or not). In GRAPH the ▸ caret separately marks
+ *  a collapsed row, so this stays a pure count and never doubles as a fold badge. */
 export declare function childBadge(node: NodeMeta | null): string;
 /** ⚑K pending-asks badge for a node, read from the supplied per-node ask map. */
 export declare function askBadge(id: string, asks: Record<string, number>): string;

package/dist/core/canvas/nav-model.js

@@ -322,8 +322,8 @@ export function liveReports(id) {
         return st === 'active' || st === 'idle';
     });
 }
-/** Direct navigable children — used for the ⤳ badge and fold counts (human-ask
- *  nodes excluded, so the count matches what the tree actually shows). */
+/** Direct navigable children — used for the ⤳ badge (human-ask nodes excluded,
+ *  so the count matches what the tree actually shows). */
 export function childCount(id) {
     return convoChildIds(id).length;
 }
@@ -360,9 +360,11 @@ export function subtreeIds(root) {
 // ---------------------------------------------------------------------------
 // Shared cell builders
 // ---------------------------------------------------------------------------
-/** ⤳M direct-children badge — only on orchestrator rows. */
+/** ⤳M direct-children badge — the single child-count signal, shown on any row
+ *  with navigable children (folded or not). In GRAPH the ▸ caret separately marks
+ *  a collapsed row, so this stays a pure count and never doubles as a fold badge. */
 export function childBadge(node) {
-    if (node === null || node.mode !== 'orchestrator')
+    if (node === null)
         return '';
     const m = childCount(node.node_id);
     return m > 0 ? ` ${DIM}⤳${m}${RESET}` : '';
@@ -484,10 +486,9 @@ export function renderGraphRow(r, isCursor, focused, activeBelow, asks) {
     // reads purely as "this unfolds".
     const expandable = r.hasKids && r.collapsed;
     const caret = !isCursor && expandable ? `${DIM}▸${RESET} ` : '  ';
-    const fold = expandable ? ` ${DIM}[+${childCount(r.id)}]${RESET}` : '';
     const fault = node !== null ? activeFaultForDisplay(node, readFault(r.id)) : null;
     const faultSuffix = fault !== null ? ` · ${faultSummary(fault)}` : '';
-    const line = `${r.branch}${caret}${dot} ${name} ${kind} ${tokens}${cycleBadge(node)}${childBadge(node)}${liveBelowBadge(node, activeBelow)}${fold}${askBadge(r.id, asks)}${activityCell(r.id, node)}${faultSuffix}`;
+    const line = `${r.branch}${caret}${dot} ${name} ${kind} ${tokens}${cycleBadge(node)}${childBadge(node)}${liveBelowBadge(node, activeBelow)}${askBadge(r.id, asks)}${activityCell(r.id, node)}${faultSuffix}`;
     return wrap(line, isAttached(r.id, node, focused));
 }
 /** Total lines the GRAPH widget may emit. pi hard-caps extension widgets at

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

@@ -45,6 +45,14 @@ 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
+ *  `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
+ *  user-authored artifact store), because it is ambient machine state, not a
+ *  document a human wrote. */
+export declare function situationalContextPath(nodeId: string): string;
 /** Passive-subscription accumulator. Pushes from publishers this node subscribes
  *  to PASSIVELY land here instead of inbox.jsonl — the inbox-watcher never polls
  *  it, so they never wake the node. Drained as XML pre-text on the next message. */

package/dist/core/canvas/paths.js

@@ -103,6 +103,16 @@ 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
+ *  `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
+ *  user-authored artifact store), because it is ambient machine state, not a
+ *  document a human wrote. */
+export function situationalContextPath(nodeId) {
+    return join(nodeDir(nodeId), 'situational-context.md');
+}
 /** Passive-subscription accumulator. Pushes from publishers this node subscribes
  *  to PASSIVELY land here instead of inbox.jsonl — the inbox-watcher never polls
  *  it, so they never wake the node. Drained as XML pre-text on the next message. */

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

@@ -1,3 +1,4 @@
+import type { CanvasSource } from './source.js';
 import { type Fault } from '../runtime/fault.js';
 import type { NodeStatus, Lifecycle } from './types.js';
 export declare function activeFaultForDisplay<T extends {
@@ -20,6 +21,8 @@ export declare function renderTree(rootId: string): string;
  * If there are no roots on the canvas, returns a placeholder string.
  */
 export declare function renderForest(): string;
+export declare function renderTreeFromSource(source: CanvasSource, rootId: string): Promise<string>;
+export declare function renderForestFromSource(source: CanvasSource): Promise<string>;
 export interface DashboardRow {
     node_id: string;
     name: string;
@@ -116,6 +119,7 @@ export declare function dashboardRows(rootId: string): DashboardRow[];
  * viewport on demand. See {@link enrichRow}, {@link enrichRows}, {@link loadPreview}.
  */
 export declare function dashboardRowsAll(): DashboardRow[];
+export declare function dashboardRowsAllFromSource(source: CanvasSource): Promise<DashboardRow[]>;
 /** Fold the cheap-boot row's deferred fields in for ONE row: the full label
  *  (meta.description → fullName), ctx tokens (telemetry.json), and ⚑ asks. One
  *  meta read + one telemetry read + one ask scan. Idempotent (no-op once enriched).
@@ -125,9 +129,11 @@ export declare function enrichRow(row: DashboardRow): DashboardRow;
  *  distinct cwd's ask inbox exactly ONCE (via `asksForNodes`) instead of per row.
  *  Use this for a whole viewport / the full forest; mutates each row in place. */
 export declare function enrichRows(rows: DashboardRow[]): void;
+export declare function enrichRowsFromSource(source: CanvasSource, rows: DashboardRow[]): Promise<void>;
 /** Load the SELECTED row's preview text: the spawn `goal` (initial-prompt.md) plus
  *  the whole-conversation `prompts` and the `lastAssistant` reply — the latter two
  *  folded into ONE session-file read (see {@link readSessionParts}). Mutates the row
  *  in place; idempotent. Call only for the cursor row (and lazily/in-background to
  *  warm the prompt super-search corpus), never on the boot path. */
 export declare function loadPreview(row: DashboardRow): DashboardRow;
+export declare function loadPreviewFromSource(source: CanvasSource, row: DashboardRow): Promise<DashboardRow>;