@crouton-kit/crouter 0.3.61 → 0.3.63

package/dist/core/worktree.js

@@ -39,24 +39,37 @@ export function openManagedWorktreeForNode(nodeId) {
 function repoRootFor(cwd) {
     return runGit(cwd, ['rev-parse', '--show-toplevel'], 'not_git_repo', 'Pass --cwd pointing inside a git repository.');
 }
-function requireOriginMain(repoRoot) {
-    return runGit(repoRoot, ['rev-parse', 'origin/main'], 'missing_origin_main', 'Managed worktrees land by rebasing onto origin/main. Fetch/create origin/main, then retry.');
+function requireLocalMain(repoRoot) {
+    return runGit(repoRoot, ['rev-parse', '--verify', 'refs/heads/main'], 'missing_local_main', 'Managed worktrees are based on and land onto your local `main` branch. Create a local `main`, then retry.');
+}
+/** Path of the worktree where a local branch is currently checked out, or null
+ *  if it is not checked out in any worktree. */
+function checkoutPathForBranch(repoRoot, branch) {
+    const out = runGit(repoRoot, ['worktree', 'list', '--porcelain'], 'worktree_list_failed', 'Inspect the repository worktrees manually, then retry.');
+    let current = null;
+    for (const line of out.split('\n')) {
+        if (line.startsWith('worktree '))
+            current = line.slice('worktree '.length).trim();
+        else if (line === `branch refs/heads/${branch}`)
+            return current;
+    }
+    return null;
 }
 export function createManagedWorktree(cwd, nodeId) {
     const repoRoot = repoRootFor(cwd);
-    const baseSha = requireOriginMain(repoRoot);
+    const baseSha = requireLocalMain(repoRoot);
     const path = managedWorktreePath(nodeId);
     if (existsSync(path)) {
         throw new WorktreeError('worktree_path_exists', `managed worktree path already exists: ${path}`, 'Remove the stale path or choose a fresh node id.');
     }
     const branch = `crtr/${nodeId}`;
-    runGit(repoRoot, ['worktree', 'add', '-b', branch, path, 'origin/main'], 'worktree_add_failed', 'Inspect the git error, fix the repository/worktree state, then retry spawning with --worktree.');
+    runGit(repoRoot, ['worktree', 'add', '-b', branch, path, 'main'], 'worktree_add_failed', 'Inspect the git error, fix the repository/worktree state, then retry spawning with --worktree.');
     return {
         state: 'open',
         path,
         branch,
         repo_root: repoRoot,
-        base_ref: 'origin/main',
+        base_ref: 'main',
         base_sha: baseSha,
         created: new Date().toISOString(),
     };
@@ -97,24 +110,33 @@ export function closeManagedWorktree(nodeId) {
         const found = branch === 'HEAD' ? 'detached HEAD' : branch;
         throw new WorktreeError('wrong_branch', `managed worktree is not on its recorded branch (expected ${wt.branch}, found ${found})`, `Check out ${wt.branch} in ${wt.path} before closing, or ask the human with \`crtr human ask\` if you are unsure why it changed, then rerun \`crtr node worktree close\`.`);
     }
-    runGit(wt.path, ['fetch', 'origin', 'main'], 'fetch_failed', 'Network/remote state blocked landing. Ask the human with `crtr human ask` if this is not a transient git/network issue.');
-    const rebase = gitSync(['rebase', 'origin/main'], wt.path);
+    requireLocalMain(wt.repo_root);
+    const rebase = gitSync(['rebase', 'main'], wt.path);
     if (rebase.status !== 0) {
         const detail = (rebase.stderr.trim() || rebase.stdout.trim()).trim();
-        throw new WorktreeError('rebase_failed', 'rebase onto origin/main did not complete', `Resolve conflicts in ${wt.path}, run \`git rebase --continue\` there, then rerun \`crtr node worktree close\`. If the blocker is not mechanical, ask the human with \`crtr human ask\`.`, detail);
+        throw new WorktreeError('rebase_failed', 'rebase onto local main did not complete', `Resolve conflicts in ${wt.path}, run \`git rebase --continue\` there, then rerun \`crtr node worktree close\`. If the blocker is not mechanical, ask the human with \`crtr human ask\`.`, detail);
     }
-    const push = gitSync(['push', 'origin', 'HEAD:main'], wt.path);
-    if (push.status !== 0) {
-        const detail = (push.stderr.trim() || push.stdout.trim()).trim();
-        throw new WorktreeError('push_main_failed', 'could not fast-forward/push origin/main from this worktree', 'Do not force-push main. Ask the human with `crtr human ask` how to land this managed worktree.', detail);
+    const landedSha = runGit(wt.path, ['rev-parse', 'HEAD'], 'landed_sha_failed', 'Inspect the worktree checkout manually, then rerun `crtr node worktree close`.');
+    // Fast-forward local `main` to the rebased worktree tip — landing is purely
+    // local, nothing is ever pushed to origin. If main is checked out in another
+    // worktree, ff-merge inside that checkout so its ref AND working tree advance
+    // together; otherwise move the branch ref directly.
+    const mainCheckout = checkoutPathForBranch(wt.repo_root, 'main');
+    const land = mainCheckout !== null
+        ? gitSync(['merge', '--ff-only', landedSha], mainCheckout)
+        : gitSync(['branch', '-f', 'main', landedSha], wt.repo_root);
+    if (land.status !== 0) {
+        const detail = (land.stderr.trim() || land.stdout.trim()).trim();
+        throw new WorktreeError('land_main_failed', 'could not fast-forward local main to this worktree', mainCheckout !== null
+            ? `Local main is checked out at ${mainCheckout} in a state that blocks a fast-forward (uncommitted changes, or it has diverged). Reconcile it there, then rerun \`crtr node worktree close\`. If you are unsure, ask the human with \`crtr human ask\`.`
+            : 'Ask the human with `crtr human ask` how to land this managed worktree.', detail);
     }
-    // The push landing IS the point of no return: persist `state: 'closed'`
-    // IMMEDIATELY, before reading the landed sha or attempting any cleanup below.
-    // Worktree removal and branch deletion are best-effort from here on — their
-    // failure is cosmetic (a stray checkout / local ref) and must never re-strand
-    // `state: 'open'` behind a dead end that permanently blocks push-final.
+    // Landing on local main IS the point of no return: persist `state: 'closed'`
+    // IMMEDIATELY, before attempting any cleanup below. Worktree removal and
+    // branch deletion are best-effort from here on — their failure is cosmetic
+    // (a stray checkout / local ref) and must never re-strand `state: 'open'`
+    // behind a dead end that permanently blocks push-final.
     updateNode(nodeId, { managed_worktree: { ...wt, state: 'closed', closed: new Date().toISOString() } });
-    const pushedSha = runGit(wt.path, ['rev-parse', 'HEAD'], 'pushed_sha_failed', 'The branch landed and the node is already marked closed, but crouter could not read the landed commit SHA. Inspect the checkout manually to confirm the landed commit; no further close action is needed.');
     const remove = gitSync(['worktree', 'remove', wt.path], wt.repo_root);
     const worktreeRemoved = remove.status === 0;
     if (worktreeRemoved && existsSync(wt.path)) {
@@ -149,7 +171,7 @@ export function closeManagedWorktree(nodeId) {
         node_id: nodeId,
         branch: wt.branch,
         worktree_path: wt.path,
-        pushed_sha: pushedSha,
+        landed_sha: landedSha,
         worktree_removed: worktreeRemoved,
         ...(worktreeRemoveError !== undefined ? { worktree_remove_error: worktreeRemoveError } : {}),
         branch_deleted: branchDeleted,

package/dist/daemon/crtrd.js

@@ -833,6 +833,38 @@ async function handleNodeLiveness(row, now, revivedThisTick) {
         return;
     }
     unhealthySince.delete(id);
+    // A FATAL *launch* fault (M-9 model-not-found — an unregistered/
+    // unauthenticated model spec recorded by the broker just before it threw
+    // and died) will reproduce IDENTICALLY on every resume: the saved launch
+    // recipe is what crashed it, so retrying it is not recovery, it's a crash
+    // loop — and unlike the null-pid stranded-relaunch path above, this branch
+    // has no attempt cap. Stop here: mark dead and notify once, instead of
+    // grace-reviving forever.
+    //
+    // Scoped narrowly to that launch fault (link + kind, not just
+    // disposition:'fatal') — other fatal faults (e.g. link:'pi→provider' auth/
+    // protocol/other faults) are intentionally handled live by
+    // handleFatalFault() without terminalizing the node, and must stay on the
+    // pre-existing liveness/grace-revive/resume path below if their broker pid
+    // later dies for an unrelated reason.
+    const fault = readFault(id);
+    if (fault !== null &&
+        fault.retry.disposition === 'fatal' &&
+        fault.link === 'crtr→pi' &&
+        fault.kind === 'model-not-found') {
+        process.stderr.write(`[crtrd] fatal-fault ${id} (${fault.kind}) — not resuming a dead-end launch; marking dead\n`);
+        transition(id, 'crash');
+        if (meta !== null) {
+            try {
+                fanDoctrineWake(id, subscribersOf(id), `Child failed to start — ${fullName(meta)} (${id}) hit a fatal launch fault (${fault.kind}: ${fault.message}) ` +
+                    `and is now dead. It stays dead until you fix the cause and revive it — \`crtr node lifecycle revive ${id}\`.`, { reason: 'child-crashed', child: id });
+            }
+            catch {
+                /* best-effort, mirrors every other fan-out in this file */
+            }
+        }
+        return;
+    }
     process.stderr.write(`[crtrd] revive ${id} (engine dead, intent=${String(row.intent)})\n`);
     reviveNode(id, { resume: retryResumeMode(meta) });
     revivedThisTick.add(id); // third-pass bare double-spawn guard (Maj-4)

package/dist/daemon/predicate-eval.js

@@ -17,6 +17,7 @@ import { randomUUID } from 'node:crypto';
 import { duePredicateTriggers, duePredicateTimeouts, runningPredicateTriggers, acquirePredicateLease, recordPredicateEvalResult, resetPredicateLease, consumeTrigger, getNode, } from '../core/canvas/index.js';
 import { isPidAlive, killProcessGroup } from '../core/canvas/pid.js';
 import { nextSlotAfter } from '../core/wake.js';
+import { buildOperationalEnvBase } from '../core/runtime/spawn-env.js';
 export const STDOUT_CAP_BYTES = 16 * 1024;
 export const STDERR_TAIL_BYTES = 4 * 1024;
 /** Read fresh each pass (not cached at module load) so a test/operator can
@@ -85,7 +86,15 @@ export function reapTimedOutPredicates(now, onTimeout) {
     }
 }
 function runOneEvaluation(t, config, onDone) {
+    // The TARGET's own cwd/profile — never this (daemon) process's ambient
+    // cwd/profile — so `buildOperationalEnvBase`'s source C (`spawnEnv.allow`)
+    // resolves from the target's own project-scope config. For `msg` the
+    // target node already exists (`t.node_id`). For `spawn_child` it doesn't
+    // exist yet, so the child's future scope is the OWNER's current scope
+    // (`t.owner_id`) — the same scope a real spawn would inherit (spawn.ts:
+    // a managed child's profile defaults to its spawner's).
     let cwd;
+    let targetProfileId;
     if (t.action === 'msg') {
         const target = t.node_id != null ? getNode(t.node_id) : null;
         if (target === null) {
@@ -94,12 +103,14 @@ function runOneEvaluation(t, config, onDone) {
             return;
         }
         cwd = target.cwd;
+        targetProfileId = target.profile_id ?? null;
     }
     else {
         cwd = t.payload.cwd;
+        targetProfileId = getNode(t.owner_id)?.profile_id ?? null;
     }
     const env = {
-        ...process.env,
+        ...buildOperationalEnvBase({ targetCwd: cwd, targetProfileId }),
         CRTR_TRIGGER_ID: t.trigger_id,
         CRTR_TRIGGER_OWNER_ID: t.owner_id,
     };

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export { closeNode } from './core/runtime/close.js';
 export type { CloseNodeResult } from './core/runtime/close.js';
 export { appendInbox } from './core/feed/inbox.js';
 export type { InboxEntry, InboxTier, InboxKind } from './core/feed/inbox.js';
+export { appendSituationalContext } from './core/runtime/situational-context.js';
 export { getNode, listNodes } from './core/canvas/canvas.js';
 export { nodeDir } from './core/canvas/paths.js';
 export type { NodeMeta, NodeRow, NodeStatus, Lifecycle, Mode, } from './core/canvas/types.js';

package/dist/index.js

@@ -16,6 +16,10 @@ export { spawnChild } from './core/runtime/spawn.js';
 export { reviveNode } from './core/runtime/revive.js';
 export { closeNode } from './core/runtime/close.js';
 export { appendInbox } from './core/feed/inbox.js';
+// Hidden ambient "current situation" sidecar (see runtime/situational-context.ts) —
+// upsert-only, narrow surface so an external composer (e.g. Hearth) never needs to
+// learn the storage file itself.
+export { appendSituationalContext } from './core/runtime/situational-context.js';
 // ── Canvas reads ─────────────────────────────────────────────────────────
 export { getNode, listNodes } from './core/canvas/canvas.js';
 export { nodeDir } from './core/canvas/paths.js';

package/dist/pi-extensions/canvas-bash-valve.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+export default function (pi: ExtensionAPI): void;

package/dist/pi-extensions/canvas-bash-valve.js

@@ -0,0 +1,238 @@
+// canvas-bash-valve.ts — the bash safety valve: auto-background hanging
+// commands, alert via inbox.
+//
+// Loaded into every canvas node's pi process via the node's launch.extensions
+// list. INERT when CRTR_NODE_ID is absent (plain pi session or legacy job
+// agent) — registers nothing, so the builtin bash tool stays in place.
+//
+// Rise with the tide: we do NOT reimplement or fork pi's bash tool. We call
+// pi's own `createBashToolDefinition()` (schema, description, rendering,
+// truncation, streaming throttle — ALL of it) and supply only a custom
+// `BashOperations` exec backend. Future pi improvements to the bash tool flow
+// through automatically; if pi ever changes the BashOperations interface, tsc
+// breaks loudly at upgrade instead of silently drifting.
+//
+// Why file-backed, not pipes: the builtin streams from a direct child over
+// pipes. A backgrounded orphan writing to a dead pipe after pi dies gets
+// SIGPIPE, and its exit code is observable by nobody. So every command is
+// file-backed from birth via a tiny detached supervisor (a `bash -c` process
+// group leader) that redirects the real command's stdout+stderr to a log
+// file and records its exit code to a sentinel file — both readable, and
+// tail-able, independent of whether this pi process is even still alive.
+//
+// Deviation from upstream: this backend pins `bash` as the shell (upstream
+// consults user shell config via non-exported helpers). Acceptable — crtr's
+// agents are bash-contract anyway.
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { createBashToolDefinition } from '@earendil-works/pi-coding-agent';
+// ---------------------------------------------------------------------------
+// Deadline — 5 minutes by default, overridable via CRTR_BASH_VALVE_MS
+// (undocumented; test-only seam so the E2E valve check doesn't sleep 5m).
+// ---------------------------------------------------------------------------
+const DEFAULT_VALVE_MS = 5 * 60 * 1000;
+const POLL_MS = 200;
+function resolveValveMs() {
+    const raw = process.env['CRTR_BASH_VALVE_MS'];
+    if (raw === undefined)
+        return DEFAULT_VALVE_MS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_VALVE_MS;
+}
+// ---------------------------------------------------------------------------
+// The detached supervisor. Spawned with `detached: true` so it becomes its
+// own process-group leader (pgid === its pid) — killing `-pgid` reaches the
+// real command and anything it forked, even after this pi process exits.
+//
+// Positional argv (never interpolated into the script — the command text
+// lives only in cmd.sh):
+//   $1 cmd.sh   $2 job.log   $3 job.exit   $4 job.bg   $5 jobId   $6 nodeId
+//
+// `--` before the paths is a dummy $0 (a standard `bash -c script -- args`
+// idiom) so the real payload lands at $1 onward.
+// ---------------------------------------------------------------------------
+const SUPERVISOR_SCRIPT = [
+    'bash "$1" > "$2" 2>&1',
+    'ec=$?',
+    'echo "$ec" > "$3"',
+    'if [ -f "$4" ]; then',
+    '  crtr node msg "Background bash job $5 finished (exit $ec). Log: $2  Command: $1" --to "$6" --tier normal || true',
+    'fi',
+].join('\n');
+function makeJobPaths(contextDir) {
+    const jobId = `${Date.now()}-${randomBytes(4).toString('hex')}`;
+    const dir = join(contextDir, 'jobs', jobId);
+    return {
+        jobId,
+        dir,
+        cmdSh: join(dir, 'cmd.sh'),
+        jobLog: join(dir, 'job.log'),
+        jobExit: join(dir, 'job.exit'),
+        jobBg: join(dir, 'job.bg'),
+    };
+}
+function killGroup(pgid) {
+    try {
+        process.kill(-pgid, 'SIGTERM');
+    }
+    catch {
+        /* already gone */
+    }
+    const killer = setTimeout(() => {
+        try {
+            process.kill(-pgid, 'SIGKILL');
+        }
+        catch {
+            /* already gone */
+        }
+    }, 2000);
+    killer.unref?.();
+}
+/** Read bytes appended to `path` since `offset`, feed them to onData, return
+ *  the new offset. Best-effort — a not-yet-created log file is not an error. */
+function tailOnce(path, offset, onData) {
+    let stat;
+    try {
+        stat = statSync(path);
+    }
+    catch {
+        return offset;
+    }
+    if (stat.size <= offset)
+        return offset;
+    const fd = openSync(path, 'r');
+    try {
+        const buf = Buffer.alloc(stat.size - offset);
+        readSync(fd, buf, 0, buf.length, offset);
+        onData(buf);
+        return stat.size;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function cleanupJobDir(dir) {
+    try {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    catch {
+        /* best-effort — worst case a stray dir under context/jobs/ */
+    }
+}
+function readExitCode(path) {
+    try {
+        const raw = readFileSync(path, 'utf8').trim();
+        const n = Number(raw);
+        return Number.isFinite(n) ? n : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The valve's BashOperations backend. */
+function createValveOperations(nodeId, contextDir) {
+    return {
+        exec: (command, cwd, { onData, signal, timeout, env }) => {
+            return new Promise((resolve, reject) => {
+                if (signal?.aborted) {
+                    reject(new Error('aborted'));
+                    return;
+                }
+                const paths = makeJobPaths(contextDir);
+                mkdirSync(paths.dir, { recursive: true });
+                writeFileSync(paths.cmdSh, command);
+                writeFileSync(paths.jobLog, '');
+                let offset = 0;
+                let settled = false;
+                let pgid;
+                const startedAt = Date.now();
+                const valveMs = resolveValveMs();
+                let interval;
+                const teardown = () => {
+                    if (interval)
+                        clearInterval(interval);
+                    if (signal)
+                        signal.removeEventListener('abort', onAbort);
+                };
+                const finish = (act) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    teardown();
+                    act();
+                };
+                function onAbort() {
+                    tailOnce(paths.jobLog, offset, onData);
+                    if (pgid)
+                        killGroup(pgid);
+                    finish(() => reject(new Error('aborted')));
+                    cleanupJobDir(paths.dir);
+                }
+                if (signal)
+                    signal.addEventListener('abort', onAbort, { once: true });
+                const child = spawn('bash', ['-c', SUPERVISOR_SCRIPT, '--', paths.cmdSh, paths.jobLog, paths.jobExit, paths.jobBg, paths.jobId, nodeId], {
+                    cwd,
+                    detached: true,
+                    stdio: 'ignore',
+                    env: env ?? process.env,
+                });
+                child.on('error', (err) => {
+                    finish(() => reject(err));
+                });
+                pgid = child.pid;
+                child.unref();
+                interval = setInterval(() => {
+                    offset = tailOnce(paths.jobLog, offset, onData);
+                    if (existsSync(paths.jobExit)) {
+                        offset = tailOnce(paths.jobLog, offset, onData);
+                        const exitCode = readExitCode(paths.jobExit);
+                        finish(() => resolve({ exitCode }));
+                        cleanupJobDir(paths.dir);
+                        return;
+                    }
+                    const elapsedMs = Date.now() - startedAt;
+                    if (timeout !== undefined && timeout > 0) {
+                        if (elapsedMs >= timeout * 1000) {
+                            if (pgid)
+                                killGroup(pgid);
+                            finish(() => reject(new Error(`timeout:${timeout}`)));
+                            cleanupJobDir(paths.dir);
+                        }
+                        return;
+                    }
+                    if (elapsedMs >= valveMs) {
+                        writeFileSync(paths.jobBg, '');
+                        const minutes = Math.round(valveMs / 60000);
+                        const notice = `\n[still running after ${minutes}m — backgrounded as job ${paths.jobId}. ` +
+                            `You'll get an inbox message when it exits. ` +
+                            `Watch: tail -f ${paths.jobLog} ; stop: kill -- -${pgid}]`;
+                        onData(Buffer.from(notice));
+                        finish(() => resolve({ exitCode: 0 }));
+                        // Backgrounded — job dir persists (inspectable); no cleanup here.
+                    }
+                }, POLL_MS);
+            });
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+export default function (pi) {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId.trim() === '')
+        return; // inert — builtin bash stays
+    const contextDir = process.env['CRTR_CONTEXT_DIR'];
+    if (contextDir === undefined || contextDir.trim() === '')
+        return; // defensive; always set alongside CRTR_NODE_ID
+    // Registered on session_start (fires for startup, new, resume, fork, and
+    // /reload) so we get ctx.cwd — the same session cwd the builtin bash tool
+    // is built against. registerTool replaces the builtin by name; re-firing on
+    // every session_start is idempotent (last registration wins).
+    pi.on('session_start', (_event, ctx) => {
+        const operations = createValveOperations(nodeId, contextDir);
+        pi.registerTool(createBashToolDefinition(ctx.cwd, { operations }));
+    });
+}

package/dist/pi-extensions/canvas-inbox-watcher.d.ts

@@ -4,6 +4,18 @@ interface PiLike {
     sendUserMessage: (content: string, options?: {
         deliverAs?: 'steer' | 'followUp';
     }) => void;
+    /** Custom-message injection — the hidden-context delivery seam (mirrors
+     *  canvas-context-intro's session_start use), distinct from sendUserMessage's
+     *  visible-chat path. */
+    sendMessage: (message: {
+        customType: string;
+        content: string;
+        display?: boolean;
+        details?: Record<string, unknown>;
+    }, options?: {
+        deliverAs?: 'steer' | 'followUp' | 'nextTurn';
+        triggerTurn?: boolean;
+    }) => void;
 }
 /**
  * Register the canvas inbox watcher on `pi`.

package/dist/pi-extensions/canvas-inbox-watcher.js

@@ -33,6 +33,7 @@
 // crouter's own tsc build without a dep on the pi packages.
 import { readInboxSince, readCursor, writeCursor, coalesce, } from '../core/feed/inbox.js';
 import { getNode } from '../core/canvas/index.js';
+import { readSituationalContext, SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../core/runtime/situational-context.js';
 // ---------------------------------------------------------------------------
 // Module-level timer — prevents stacking on /reload (the double-notify bug).
 //
@@ -137,15 +138,50 @@ export function registerCanvasInboxWatcher(pi) {
             return;
         const batch = buffer;
         buffer = [];
-        const digest = coalesce(batch);
+        // Hidden situational-context delivery: an entry with data.situational marks
+        // a pending ambient-context update on this node's sidecar. Deliver it as a
+        // HIDDEN custom message (never through coalesce(), never as a visible chat
+        // turn) ahead of whatever visible digest remains. situationalOnly entries
+        // (context alone, no accompanying visible body) are dropped from the
+        // visible batch entirely — they exist purely as a wake marker for this
+        // delivery and must never surface a line in the digest.
+        const hasSituational = batch.some((e) => e.data?.['situational'] === true);
+        const visibleBatch = batch.filter((e) => e.data?.['situationalOnly'] !== true);
+        if (hasSituational) {
+            const nodeId = process.env['CRTR_NODE_ID'];
+            const text = nodeId !== undefined ? readSituationalContext(nodeId) : null;
+            if (text !== null) {
+                try {
+                    pi.sendMessage({
+                        customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE,
+                        content: `<situational-context>\n${text}\n</situational-context>`,
+                        display: true,
+                        details: { nodeId },
+                    }, { deliverAs: 'followUp', triggerTurn: true });
+                }
+                catch {
+                    // Re-queue on delivery failure — same durability contract as the visible
+                    // digest path below. The cursor already advanced past these entries in
+                    // tick(), so a swallowed failure here would otherwise drop the hidden
+                    // wake permanently (never re-read from the inbox, never retried). Only
+                    // the situational-only entries go back; a real re-send re-reads the
+                    // CURRENT sidecar value (upsert, not append), so retrying is idempotent
+                    // even if the text changed again in between.
+                    buffer = batch.filter((e) => e.data?.['situationalOnly'] === true).concat(buffer);
+                }
+            }
+        }
+        if (visibleBatch.length === 0)
+            return;
+        const digest = coalesce(visibleBatch);
         // Tier (and kind) drive delivery mode. Critical is a TRUE preempt; urgent —
         // and a finished node (kind 'final') — steers at the turn boundary;
         // normal/deferred ride the next turn (followUp). (A purely-deferred idle
         // batch was already held above and never reaches here.) A completion a
         // subscriber is likely blocked on must not drain as a follow-up, so 'final'
         // steers exactly like 'urgent'.
-        const anyCritical = batch.some((e) => e.tier === 'critical');
-        const steerMidStream = anyCritical || batch.some((e) => e.tier === 'urgent' || e.kind === 'final');
+        const anyCritical = visibleBatch.some((e) => e.tier === 'critical');
+        const steerMidStream = anyCritical || visibleBatch.some((e) => e.tier === 'urgent' || e.kind === 'final');
         try {
             if (isIdle()) {
                 // Idle → trigger a new turn immediately (sendUserMessage always triggers).
@@ -163,7 +199,7 @@ export function registerCanvasInboxWatcher(pi) {
                     lastCtx?.abort?.();
                 }
                 catch { /* abort is best-effort */ }
-                buffer = batch.concat(buffer);
+                buffer = visibleBatch.concat(buffer);
             }
             else {
                 // Mid-stream → steer on urgency or a finished node, else enqueue for the
@@ -174,7 +210,7 @@ export function registerCanvasInboxWatcher(pi) {
         catch {
             // Re-queue on delivery failure so a transient error doesn't silently drop
             // inbox entries. They will be retried on the next flush.
-            buffer = batch.concat(buffer);
+            buffer = visibleBatch.concat(buffer);
         }
     };
     // ---------------------------------------------------------------------------

package/dist/types.d.ts

@@ -137,6 +137,35 @@ export interface ScopeConfig {
      *  `defaultScopeConfig()`; user/project `config.json` adds or shadows
      *  entries at the same scope precedence as the rest of `ScopeConfig`. */
     kinds: Record<string, KindConfig>;
+    /** Named remote-canvas targets for `crtr surface attach to <id> --canvas
+     *  <name>` (Phase 1 interim contract — hand-edited in config.json, no CLI
+     *  verbs yet; Phase 3 owns the real secret-store-backed `crtr canvas
+     *  config`/`crtr canvas use`). Unset via `sys config set` — not in
+     *  `TOP_LEVEL_KEYS`. */
+    remoteCanvas: RemoteCanvasConfig;
+    /** Extra env-var names/globs a scope explicitly admits across the broker
+     *  spawn-env boundary (`buildBrokerEnv`, `core/runtime/spawn-env.ts`) — the
+     *  "I accept this crosses as a shell-visible credential" escape hatch for a
+     *  bespoke provider key, a deliberate `GIT_*` var, or a credentialed proxy.
+     *  Default empty; merged additively across project > profile > user >
+     *  builtin scope precedence, same as the rest of `ScopeConfig`. */
+    spawnEnv?: {
+        allow?: string[];
+    };
+}
+/** One remote canvas target: where to relay-attach and how to find its
+ *  bearer token. The token itself is NEVER stored here — only the name of an
+ *  environment variable holding it, resolved at connect time by
+ *  `resolveRemoteCanvasTarget` (`src/core/view/remote-canvas-target.ts`). */
+export interface RemoteCanvasTarget {
+    previewEndpoint: string;
+    /** Name of an environment variable holding the raw relay/bearer token —
+     *  NEVER the token itself. Resolved from process.env at connect time. */
+    relayTokenEnv: string;
+    cpOrigin?: string;
+}
+export interface RemoteCanvasConfig {
+    targets: Record<string, RemoteCanvasTarget>;
 }
 export interface ScopeState {
     marketplaces: Record<string, {
@@ -214,6 +243,9 @@ export declare const AGENTS_DIR = "agents";
 export declare const PROFILE_DIR = "profiles";
 export declare const DEFAULT_MAX_PANES_PER_WINDOW = 3;
 export declare function defaultScopeConfig(): ScopeConfig;
+/** No remote canvas targets are configured out of the box — every one is
+ *  hand-added to config.json (Phase 1 interim contract, see `RemoteCanvasConfig`). */
+export declare function defaultRemoteCanvasConfig(): RemoteCanvasConfig;
 /** The builtin kind registry (spec §1.5): the built-in defaults for every
  *  top-level kind and its sub-persona kinds. `whenToUse`/`model` are the
  *  one-per-kind defaults (not one per mode) that seed a node's spawn menu

package/dist/types.js

@@ -31,8 +31,15 @@ export function defaultScopeConfig() {
         canvasNav: defaultCanvasNavConfig(),
         modelLadders: defaultModelLaddersConfig(),
         kinds: defaultKindsConfig(),
+        remoteCanvas: defaultRemoteCanvasConfig(),
+        spawnEnv: { allow: [] },
     };
 }
+/** No remote canvas targets are configured out of the box — every one is
+ *  hand-added to config.json (Phase 1 interim contract, see `RemoteCanvasConfig`). */
+export function defaultRemoteCanvasConfig() {
+    return { targets: {} };
+}
 /** The builtin kind registry (spec §1.5): the built-in defaults for every
  *  top-level kind and its sub-persona kinds. `whenToUse`/`model` are the
  *  one-per-kind defaults (not one per mode) that seed a node's spawn menu