@crouton-kit/crouter 0.3.60 → 0.3.62

package/dist/core/runtime/host.js

@@ -18,7 +18,7 @@ import { connect } from 'node:net';
 import { getNode } from '../canvas/index.js';
 import { nodeDir, jobDir, viewSocketPath } from '../canvas/paths.js';
 import { encodeFrame } from './broker-protocol.js';
-import { FRONT_DOOR_ENV } from './front-door.js';
+import { buildBrokerEnv } from './spawn-env.js';
 import { hostExecPath } from './branded-host.js';
 import { isPidAlive, killProcessTreePids, isAnyPidAlive, captureTeardownSnapshot } from '../canvas/pid.js';
 import { logger } from '../log.js';
@@ -36,6 +36,17 @@ function resolveBrokerEntry() {
     return join(here, 'broker-cli.js');
 }
 const DEFAULT_BROKER_ENGINE = '@earendil-works/pi-coding-agent';
+/** Resolve the broker engine spec for THIS launch, mirroring broker-sdk.ts's
+ *  own resolution order (`inv.env` first, then the launching process's ambient
+ *  `CRTR_BROKER_ENGINE` — the T11 test seam — then the real SDK default).
+ *  Called once by `preflightBrokerLaunch` (to validate resolvability before we
+ *  detach a process) and again by `launch` (to inject the SAME resolved value
+ *  into the child's env — see the child-env comment at the spawn() call for
+ *  why: the default-deny allowlist in spawn-env.ts strips `CRTR_*` from
+ *  ambient env, so the child can no longer re-derive this itself). */
+function resolveEngineSpec(inv) {
+    return inv.env['CRTR_BROKER_ENGINE'] ?? process.env['CRTR_BROKER_ENGINE'] ?? DEFAULT_BROKER_ENGINE;
+}
 function isPlainLaunchSessionPath(token) {
     return token.includes('/') || token.endsWith('.jsonl');
 }
@@ -67,7 +78,7 @@ export function preflightBrokerLaunch(nodeId, inv, cwd) {
     if (!Array.isArray(recipe.argv)) {
         throw new Error(`[broker] refusing to launch ${nodeId}: broker-launch.json is missing the argv array`);
     }
-    const engineSpec = inv.env['CRTR_BROKER_ENGINE'] ?? process.env['CRTR_BROKER_ENGINE'] ?? DEFAULT_BROKER_ENGINE;
+    const engineSpec = resolveEngineSpec(inv);
     try {
         const resolvedEngine = import.meta.resolve(engineSpec);
         if (resolvedEngine.startsWith('file:') && !existsSync(fileURLToPath(resolvedEngine))) {
@@ -179,11 +190,40 @@ export const headlessBrokerHost = {
         // Launch from the crouter-branded host binary (a copy of node) so the
         // broker shows "crouter" in macOS Full Disk Access, not "node". On
         // non-darwin / dev / tests this is just process.execPath (see branded-host).
+        // buildBrokerEnv's default-deny allowlist has no `CRTR_` prefix, so a bare
+        // `CRTR_BROKER_ENGINE` set only in the LAUNCHING process's ambient env (the
+        // T11 test seam — see broker-sdk.ts) would never reach the child, which
+        // would silently fall back to booting the real SDK. Inject the SAME value
+        // preflightBrokerLaunch already resolved+validated above: it is
+        // parent-resolved, crtr-trusted data (the same trust category as
+        // `inv.env`), not a blanket `CRTR_*` passthrough, so this does not weaken
+        // the allowlist's hardening. In production `engineSpec` is always the real
+        // SDK default, so this is a no-op there.
+        const engineSpec = resolveEngineSpec(inv);
+        const childEnv = { ...buildBrokerEnv(inv), CRTR_BROKER_ENGINE: engineSpec };
+        // NODE_OPTIONS is deliberately absent from the operational allowlist (it is
+        // a code-execution vector — `--require`/`--import` — and DAEMON_ENV_STRIP_KEYS
+        // strips it from the daemon's own env for the identical reason: a poisoned
+        // NODE_OPTIONS in an inheriting shell must never reach a process that then
+        // handles model credentials). It is genuinely needed ONLY for the T11 test
+        // seam above: the fake engine is a `.ts` fixture, and the broker CLI entry
+        // itself is only a `.js` file under the compiled `dist/`, so the harness
+        // relies on `NODE_OPTIONS=--import tsx/esm` (set on its own ambient env, same
+        // seam as CRTR_BROKER_ENGINE) to make the spawned child resolve both under
+        // tsx. Gating this carry on `engineSpec !== DEFAULT_BROKER_ENGINE` — i.e. only
+        // when the trusted test seam above already fired — keeps production (where
+        // the engine is never overridden) byte-identical to today: NODE_OPTIONS is
+        // never forwarded there, so an ambient poisoned value stays contained.
+        if (engineSpec !== DEFAULT_BROKER_ENGINE) {
+            const nodeOptions = inv.env['NODE_OPTIONS'] ?? process.env['NODE_OPTIONS'];
+            if (nodeOptions !== undefined)
+                childEnv['NODE_OPTIONS'] = nodeOptions;
+        }
         const child = spawn(hostExecPath(), [resolveBrokerEntry(), nodeId], {
             cwd: opts.cwd,
             detached: true,
             stdio: ['ignore', logFd, logFd],
-            env: { ...process.env, ...inv.env, [FRONT_DOOR_ENV]: '1' },
+            env: childEnv,
         });
         // The child holds its own dup of the fd; release the parent's copy so the
         // launching process (CLI or daemon) never leaks it.

package/dist/core/runtime/kickoff.js

@@ -249,6 +249,12 @@ export function buildReviveKickoff(meta, bearings, wakeReason) {
     }
     const files = listContextDir(nodeId);
     parts.push(`<context-dir path="${contextDir(nodeId)}">\n${files.length > 0 ? files.join('\n') : '(empty)'}\n</context-dir>`);
+    // Hidden applet/situation-origin ambient context (see situational-context.ts)
+    // is deliberately NOT injected here — this kickoff is the VISIBLE revive prompt.
+    // canvas-context-intro's session_start handler re-fires on every fresh/cycling
+    // revive (a new pi process boot) and re-injects buildContextIntro(), which
+    // already carries the sidecar as a hidden sibling of <crtr-bearings>; that seam
+    // covers this path, so duplicating it into the visible prompt would leak it.
     parts.push(feedBlock(nodeId, bearings.unreadDigest));
     parts.push(bearings.yieldMsg !== null
         ? `<yield-message>\n${bearings.yieldMsg.trim()}\n</yield-message>`

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

@@ -9,6 +9,7 @@ export declare const CANVAS_PASSIVE_CONTEXT_PATH: string;
 export declare const CANVAS_CONTEXT_INTRO_PATH: string;
 export declare const CANVAS_DOC_SUBSTRATE_PATH: string;
 export declare const CANVAS_STRUCTURED_OUTPUT_PATH: string;
+export declare const CANVAS_BASH_VALVE_PATH: string;
 /** The canvas extensions every node loads, in order: stophook (routing +
  *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
  *  graph chrome), recap (the per-node inactivity recap card — Haiku over the
@@ -18,7 +19,11 @@ export declare const CANVAS_STRUCTURED_OUTPUT_PATH: string;
  *  context-intro (inject the <crtr-bearings> block + the <memory kind="knowledge">
  *  catalog as its own session message, once per brand-new chat),
  *  doc-substrate (the unified document substrate's two hooks: the
- *  <memory kind="preference"> block at boot, on-read context injection).
+ *  <memory kind="preference"> block at boot, on-read context injection),
+ *  bash-valve (replaces the builtin bash tool with a file-backed exec
+ *  backend: commands under 5min are byte-identical to today; past 5min
+ *  with no explicit timeout, the tool call returns with output-so-far and
+ *  the command keeps running detached, alerting via inbox on exit).
  *  All self-gate on CRTR_NODE_ID. goal-capture precedes passive-context so it
  *  reads the raw user text. */
 export declare const CANVAS_EXTENSIONS: string[];

package/dist/core/runtime/launch.js

@@ -36,6 +36,7 @@ export const CANVAS_PASSIVE_CONTEXT_PATH = resolveExtension('canvas-passive-cont
 export const CANVAS_CONTEXT_INTRO_PATH = resolveExtension('canvas-context-intro');
 export const CANVAS_DOC_SUBSTRATE_PATH = resolveExtension('canvas-doc-substrate');
 export const CANVAS_STRUCTURED_OUTPUT_PATH = resolveExtension('canvas-structured-output');
+export const CANVAS_BASH_VALVE_PATH = resolveExtension('canvas-bash-valve');
 /** The canvas extensions every node loads, in order: stophook (routing +
  *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
  *  graph chrome), recap (the per-node inactivity recap card — Haiku over the
@@ -45,7 +46,11 @@ export const CANVAS_STRUCTURED_OUTPUT_PATH = resolveExtension('canvas-structured
  *  context-intro (inject the <crtr-bearings> block + the <memory kind="knowledge">
  *  catalog as its own session message, once per brand-new chat),
  *  doc-substrate (the unified document substrate's two hooks: the
- *  <memory kind="preference"> block at boot, on-read context injection).
+ *  <memory kind="preference"> block at boot, on-read context injection),
+ *  bash-valve (replaces the builtin bash tool with a file-backed exec
+ *  backend: commands under 5min are byte-identical to today; past 5min
+ *  with no explicit timeout, the tool call returns with output-so-far and
+ *  the command keeps running detached, alerting via inbox on exit).
  *  All self-gate on CRTR_NODE_ID. goal-capture precedes passive-context so it
  *  reads the raw user text. */
 export const CANVAS_EXTENSIONS = [
@@ -58,6 +63,7 @@ export const CANVAS_EXTENSIONS = [
     CANVAS_CONTEXT_INTRO_PATH,
     CANVAS_DOC_SUBSTRATE_PATH,
     CANVAS_STRUCTURED_OUTPUT_PATH,
+    CANVAS_BASH_VALVE_PATH,
 ];
 // ---------------------------------------------------------------------------
 // Two-axis model resolution: (provider × strength) → concrete `model:thinking`.

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

@@ -47,12 +47,13 @@ export interface SpawnNodeOpts {
      *  persona default. Persisted to `meta.model_override` so polymorphs preserve
      *  it. Omit to use the persona default. */
     modelOverride?: string | null;
-    /** The profile-directory id (`<slug>-<id>`) this node runs under; null for a
-     *  root/no-profile node. Written to `meta.profile_id` and the row, and mirrored
-     *  into the pi process env as `CRTR_PROFILE_ID` by `nodeEnv` — the runtime
-     *  → resolver seam every downstream memory/gate consumer reads. Callers
-     *  resolve/validate the operand (via `loadProfileManifest`) before it reaches
-     *  here; this layer just persists the already-resolved id. */
+    /** The profile-directory id (`<slug>-<id>`) this node runs under; null only
+     *  for historical root/no-profile nodes. Written to `meta.profile_id` and the
+     *  row, and mirrored into the pi process env as `CRTR_PROFILE_ID` by
+     *  `nodeEnv` — the runtime → resolver seam every downstream memory/gate
+     *  consumer reads. Callers resolve/validate the operand (via
+     *  `loadProfileManifest`) before it reaches here; this layer just persists the
+     *  already-resolved id. */
     profile_id?: string | null;
     /** Managed worktree already created for this node, if any. */
     managedWorktree?: ManagedWorktree;

package/dist/core/runtime/nodes.js

@@ -65,9 +65,9 @@ export function nodeEnv(meta) {
         CRTR_CONTEXT_DIR: contextDir(meta.node_id),
         CRTR_CYCLES: (meta.cycles ?? 0).toString(),
         // The runtime→resolver seam: memory-resolver.ts/scope.ts/config.ts read
-        // this process-wide env var (Phase 5) to pull in the node's profile memory
-        // store and multi-project pointer set. '' (never omitted) for a root/
-        // no-profile node, matching every other CRTR_* scalar here.
+        // this process-wide env var to pull in the node's profile memory store and
+        // multi-project pointer set. '' (never omitted) only for historical
+        // null-profile rows, matching every other CRTR_* scalar here.
         CRTR_PROFILE_ID: meta.profile_id ?? '',
     };
     if (meta.parent)

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/spawn-env.d.ts

@@ -0,0 +1,27 @@
+import type { PiInvocation } from './launch.js';
+/** Sources A–C: the operational base shared by both the broker boundary (this
+ *  module's `buildBrokerEnv`) and the predicate-eval `when_script` path
+ *  (`daemon/predicate-eval.ts`) — 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) plus D — the trusted,
+ *  crtr-constructed `inv.env` overlay and the fork-bomb recursion guard
+ *  `FRONT_DOOR_ENV=1`. 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;

package/dist/core/runtime/spawn-env.js

@@ -0,0 +1,169 @@
+// The spawn-env boundary (design: C-1 crtr substrate spawn-env boundary).
+//
+// One authoritative builder for every broker child's process env. The prior
+// shape was `{ ...process.env, ...inv.env }` — the whole host env, including
+// every ambient credential (`MISTRAL_API_KEY`, `GITHUB_TOKEN`, `AWS_*`, …),
+// inherited verbatim into the broker and, through it, into pi's bash tool
+// (`printenv`/`ps eww` both expose it). This module replaces that spread with
+// a default-deny allowlist: nothing in `process.env` crosses unless it is a
+// literal non-secret operational name (A1), a value-guarded proxy var (A2), a
+// configured model-provider key (B), or an explicit `spawnEnv.allow` entry
+// (C). `inv.env` (D) is crtr-constructed and trusted, so it overlays
+// unconditionally.
+//
+// `GIT_*` is deliberately absent from the allowlist: the whole namespace is an
+// auth/config-injection surface (`GIT_CONFIG_KEY_*`/`GIT_CONFIG_VALUE_*`,
+// `GIT_ASKPASS`, `GIT_SSH_COMMAND`), not a non-secret operational family, and
+// ordinary git needs none of it (identity/credential-helper config via
+// `~/.gitconfig`, reached through the allowlisted `HOME`; SSH remotes via the
+// allowlisted `SSH_AUTH_SOCK`). A deliberate `GIT_*` need goes through
+// `spawnEnv.allow`.
+import { readMergedLaunchConfig } from '../config.js';
+import { FRONT_DOOR_ENV } from './front-door.js';
+/** A1 — literal env-var names copied verbatim (no value inspection): a login
+ *  shell plus dev toolchain needs exactly these, and none of them can carry a
+ *  credential. */
+const OPERATIONAL_LITERAL_NAMES = new Set([
+    'HOME',
+    'PATH',
+    'SHELL',
+    'USER',
+    'LOGNAME',
+    'PWD',
+    'TMPDIR',
+    'TERM',
+    'TERMINFO',
+    'COLORTERM',
+    'LANG',
+    'LANGUAGE',
+    'TZ',
+    'NO_PROXY',
+    'no_proxy',
+    'SSH_AUTH_SOCK',
+    // Bash safety-valve deadline override (ms) — an operator-wide knob set in
+    // the daemon's own ambient env, not a per-node secret.
+    'CRTR_BASH_VALVE_MS',
+]);
+/** A1 — prefixes admitted in full: each is a structurally non-secret family
+ *  (locale, XDG base-dir paths, pi's own config/rendering knobs — pi's auth is
+ *  file-backed in `auth.json`, never an env value). `GIT_` is NOT here — see
+ *  module comment. */
+const OPERATIONAL_PREFIXES = ['LC_', 'XDG_', 'PI_'];
+/** A2 — proxy var names. Admitted only when the value's URL authority carries
+ *  no userinfo component (no `user@` / `user:pass@`) — the one value-inspected
+ *  entry in the whole builder, because a proxy var is the single operational
+ *  name whose *value* (not name) can carry a secret. */
+const PROXY_NAMES = ['HTTP_PROXY', 'HTTPS_PROXY', 'http_proxy', 'https_proxy'];
+/** B — the exact env-var name of each crtr-configured model provider's API
+ *  key. Deliberately an explicit provider→env-key mapping, NOT inferred from
+ *  `MODEL_PROVIDER_KEYS` in launch.ts (that constant is a provider-ID list —
+ *  `['anthropic', 'openai']` — not env-var names; conflating the two would
+ *  silently admit the wrong names the moment either list changes). */
+const PROVIDER_ENV_KEYS = {
+    anthropic: 'ANTHROPIC_API_KEY',
+    openai: 'OPENAI_API_KEY',
+};
+/** True when `value` is an absolute `http(s)` proxy URL with a host and NO
+ *  embedded userinfo (`user@` / `user:pass@` / `:pass@`) — the only shape
+ *  allowed to cross by default. Rejects three leak shapes a naive
+ *  `new URL(value).username === ''` check misses:
+ *   - password-only authority (`http://:pass@host`) — `username` is empty but
+ *     `password` is not, so both must be checked.
+ *   - scheme-less userinfo (`user:pass@host:3128`, no `http(s)://` prefix) —
+ *     `URL` parses the text before the first `:` as a CUSTOM scheme (here
+ *     `user:`), leaving `username`/`password` both empty even though the
+ *     value plainly carries credentials. Requiring `protocol` to be exactly
+ *     `http:`/`https:` rejects this shape before userinfo parsing could ever
+ *     be fooled by it, rather than normalizing/re-parsing a scheme-less form.
+ *   - anything else unparseable, protocol-mismatched, or hostless — safe-fail
+ *     to "never admit" rather than silently passing a value through. */
+function isCredentialFreeProxyValue(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+        return false;
+    if (parsed.hostname === '')
+        return false;
+    if (parsed.username !== '' || parsed.password !== '')
+        return false;
+    return true;
+}
+/** Anchored FULL-STRING glob match for one `spawnEnv.allow` entry: `*` matches
+ *  any (possibly empty) run of characters; every other character — including
+ *  regex metacharacters — matches literally. A pattern with no `*` is a plain
+ *  exact-name match (the common case, and the only shape prior to this fix).
+ *  A bare/all-`*` "match everything" pattern is rejected earlier, at config
+ *  read (`core/config.ts`'s `mergeSpawnEnv`), so it can never reach here. */
+function matchesAllowPattern(name, pattern) {
+    if (!pattern.includes('*'))
+        return name === pattern;
+    const escaped = pattern
+        .split('*')
+        .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+        .join('.*');
+    return new RegExp(`^${escaped}$`).test(name);
+}
+/** Sources A–C: the operational base shared by both the broker boundary (this
+ *  module's `buildBrokerEnv`) and the predicate-eval `when_script` path
+ *  (`daemon/predicate-eval.ts`) — 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 function buildOperationalEnvBase(opts) {
+    const host = opts.host ?? process.env;
+    const out = {};
+    // A1 — literal names + non-secret prefixes, copied verbatim.
+    for (const [key, value] of Object.entries(host)) {
+        if (value === undefined)
+            continue;
+        if (OPERATIONAL_LITERAL_NAMES.has(key) || OPERATIONAL_PREFIXES.some((prefix) => key.startsWith(prefix))) {
+            out[key] = value;
+        }
+    }
+    // A2 — proxy vars, admitted only past the userinfo guard.
+    for (const key of PROXY_NAMES) {
+        const value = host[key];
+        if (value !== undefined && isCredentialFreeProxyValue(value))
+            out[key] = value;
+    }
+    // B — configured model-provider keys, by exact env-var name.
+    for (const envKey of Object.values(PROVIDER_ENV_KEYS)) {
+        const value = host[envKey];
+        if (value !== undefined)
+            out[envKey] = value;
+    }
+    // C — explicit config-declared extra allowlist (literal names and/or
+    // globs), resolved from the TARGET's own cwd/profile scope (default empty).
+    const allow = readMergedLaunchConfig(opts.targetCwd, opts.targetProfileId).spawnEnv.allow;
+    if (allow.length > 0) {
+        for (const [key, value] of Object.entries(host)) {
+            if (value === undefined)
+                continue;
+            if (allow.some((pattern) => matchesAllowPattern(key, pattern)))
+                out[key] = value;
+        }
+    }
+    return out;
+}
+/** 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) plus D — the trusted,
+ *  crtr-constructed `inv.env` overlay and the fork-bomb recursion guard
+ *  `FRONT_DOOR_ENV=1`. Every broker launch (front-door root, managed child,
+ *  `--root`, every revive/daemon relaunch) funnels through
+ *  `headlessBrokerHost.launch()`, which calls this. */
+export function buildBrokerEnv(inv) {
+    const targetCwd = inv.env['CRTR_NODE_CWD'] ?? process.cwd();
+    const targetProfileId = inv.env['CRTR_PROFILE_ID'] || null;
+    return {
+        ...buildOperationalEnvBase({ targetCwd, targetProfileId }),
+        ...inv.env,
+        [FRONT_DOOR_ENV]: '1',
+    };
+}

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

@@ -7,9 +7,10 @@ export interface BootRootOpts {
     /** Optional starter prompt (bare `crtr` requires none). */
     prompt?: string;
     /** Explicit `--profile <id-or-name>` on the front-door invocation, validated
-     *  through `loadProfileManifest`. Omit to run the MRU/create-or-root startup
-     *  selector for `cwd` (see `selectProfileForCwd`) — a root has no spawner to
-     *  inherit from, so this is the front door's only source of profile identity. */
+     *  through `loadProfileManifest`. Omit to run the MRU/create-or-root-profile
+     *  startup selector for `cwd` (see `selectProfileForCwd`) — a root has no
+     *  spawner to inherit from, so this is the front door's only source of profile
+     *  identity. */
     profile?: string | null;
     /** `crtr --pick-profile`: force the startup profile chooser to open even when
      *  a per-cwd default is pinned, so the user can re-pin or unpin it. Without
@@ -56,15 +57,23 @@ export interface SpawnChildOpts {
     /** Select the profile this node runs under — an exact profile id or a unique
      *  manifest name, validated through `loadProfileManifest`. Omit to INHERIT the
      *  spawner's current `profile_id` (managed child or --root alike — --root only
-     *  means top-level, it does not reset to no profile). Passed through unchanged
-     *  into a deferred trigger recipe so a triggered birth re-resolves the SAME
-     *  choice at fire time (an explicit value re-validates; inheritance re-reads
-     *  the spawner's THEN-current profile). */
+     *  means top-level, it does not reset to a different profile; a shell root
+     *  falls back to the stable root profile in the startup selector). Passed
+     *  through unchanged into a deferred trigger recipe so a triggered birth
+     *  re-resolves the SAME choice at fire time (an explicit value re-validates;
+     *  inheritance re-reads the spawner's THEN-current profile). */
     profile?: string | null;
     /** Create a managed worktree for this node and pin its cwd to it. */
     worktree?: boolean;
     /** Preallocated node id, used when a managed worktree must be named before birth. */
     nodeId?: string;
+    /** Hidden ambient "current situation" text — NOT the visible prompt/body.
+     *  Persisted via `appendSituationalContext` BEFORE launch so canvas-context-
+     *  intro's session_start bearings carry it as a `<situational-context>`
+     *  sibling from the node's very first turn. Passed through unchanged into a
+     *  deferred trigger recipe (the same field survives a scheduled node_birth).
+     *  Omit for no ambient context. */
+    situationalContext?: string;
 }
 /** Resolve a `--fork-from` value to an ABSOLUTE `.jsonl` source path for the
  *  broker fork (`SessionManager.forkFrom`, which loads a file — never a bare id).

package/dist/core/runtime/spawn.js

@@ -21,6 +21,7 @@ import { gitSync } from '../git.js';
 import { createManagedWorktree } from '../worktree.js';
 import { usage } from '../errors.js';
 import { writeGoal } from './kickoff.js';
+import { appendSituationalContext } from './situational-context.js';
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
 import { buildIdentityAssertion, buildWakeBearings } from './bearings.js';
 import { installMenuBinding, installNavBindings, installViewNavBindings } from './tmux-chrome.js';
@@ -68,7 +69,8 @@ export async function bootRoot(opts) {
     const kind = opts.kind ?? 'general';
     // The front door's only source of profile identity — a root has no spawner
     // to inherit from. Runs BEFORE spawnNode: explicit --profile > MRU profile
-    // covering cwd > a synchronous create-or-root prompt (or root, headless).
+    // covering cwd > a synchronous create-or-root-profile prompt (the stable root
+    // profile, headless).
     const profileId = await selectProfileForCwd(opts.cwd, opts.profile, opts.pickProfile ?? false);
     // A born-resident root starts in base mode; it earns the orchestrator persona
     // the first time it delegates (or on promotion). Resident lifecycle either way.
@@ -258,7 +260,7 @@ export function resolveForkSource(value) {
  *  there is NO spawner at all — `crtr node new --root` run directly from a
  *  shell, not from inside a node — there is no profile to inherit, so this runs
  *  the same startup selector the front door uses (MRU covering `cwd`, else the
- *  synchronous create-or-root prompt / headless root default). */
+ *  root-profile prompt/default). */
 async function resolveProfileId(explicit, spawner, cwd) {
     if (explicit !== undefined && explicit !== null && explicit !== '') {
         return loadProfileManifest(explicit).profileId;
@@ -347,6 +349,10 @@ export async function spawnChild(opts) {
         });
         // Persist the task as the child's goal for a fresh revive to re-read.
         writeGoal(meta.node_id, opts.prompt);
+        // Hidden ambient context, written BEFORE the engine launches so canvas-
+        // context-intro's session_start bearings carry it from the first turn.
+        if (opts.situationalContext !== undefined)
+            appendSituationalContext(meta.node_id, opts.situationalContext);
         // A fork inherits the SOURCE node's entire first-person conversation, so the
         // identity re-assertion must ride the STRONGEST channel too, not only the
         // session-start bearings (a trailing custom_message the model weighs only by

package/dist/core/substrate/session-cache.js

@@ -42,7 +42,13 @@ export function clearSessionCache() {
  *  `listFn` is injected by the caller to avoid circular imports at module init. */
 export function cachedAllMemoryDocs(listFn) {
     if (_cache.allMemoryDocs === null) {
-        _cache.allMemoryDocs = listFn();
+        // The boot pipeline (render + on-read) EXCLUDES node-scope docs: node-local
+        // memory surfaces at boot via render.ts's nodeLocalDocs (any kind, floored
+        // into the knowledge block), NOT through the resolver corpus, so a node doc
+        // must not also enter here (it would double-surface at boot and could fire
+        // on-read). The `node` scope reaches CLI read/list/find/delete through the
+        // uncached listAllMemoryDocs() path instead.
+        _cache.allMemoryDocs = listFn().filter((d) => d.scope !== 'node');
     }
     return _cache.allMemoryDocs;
 }

package/dist/core/substrate/subject.d.ts

@@ -24,7 +24,7 @@ export interface NodeConfigSubject {
     };
     /** DERIVED: `meta.profile_id` resolved to its manifest's mutable `name` (NOT
      *  the stable directory id — gate authors write `gate: {profile: <name>}`).
-     *  null for a root/no-profile node, and null (never throwing) when the
+     *  null for historical null-profile rows, and null (never throwing) when the
      *  profile has been deleted or its manifest is unreadable — this is a HOT,
      *  every-doc-render path and must never brick boot/on-read gating. */
     profile: string | null;

package/dist/core/view/remote-canvas-target.d.ts

@@ -0,0 +1,3 @@
+import type { Scope } from '../../types.js';
+import type { RelayTarget } from '../../clients/attach/transport-relay.js';
+export declare function resolveRemoteCanvasTarget(name: string, scope?: Scope): RelayTarget;

package/dist/core/view/remote-canvas-target.js

@@ -0,0 +1,25 @@
+// remote-canvas-target.ts — resolves a named `remoteCanvas.targets.<name>`
+// config entry (see `RemoteCanvasTarget`, `src/types.ts`) into a `RelayTarget`
+// ready for `RelayTransport` (`src/clients/attach/transport-relay.ts`).
+//
+// The raw bearer token NEVER lives in config or argv — only the name of an
+// environment variable holding it (`relayTokenEnv`), read here at connect
+// time. This is the Phase 1 interim contract; Phase 3 owns the real
+// secret-store-backed `crtr canvas config`/`crtr canvas use` CLI.
+import { usage } from '../errors.js';
+import { readConfig } from '../config.js';
+export function resolveRemoteCanvasTarget(name, scope = 'user') {
+    const cfg = readConfig(scope);
+    const target = cfg.remoteCanvas.targets[name];
+    if (target === undefined) {
+        const known = Object.keys(cfg.remoteCanvas.targets);
+        throw usage(`no remote canvas target named '${name}'` +
+            (known.length > 0 ? ` — configured: ${known.join(', ')}` : ' — none configured yet') +
+            `. Add remoteCanvas.targets.${name} to config.json (run \`crtr sys config path\`): {"previewEndpoint": "https://<hash>.preview.bl.run", "relayTokenEnv": "<ENV_VAR_NAME>"}.`);
+    }
+    const relayToken = process.env[target.relayTokenEnv];
+    if (relayToken === undefined || relayToken === '') {
+        throw usage(`remote canvas target '${name}' needs its relay token in $${target.relayTokenEnv} — that environment variable is unset. Export it before running this command; the token is never read from config or argv.`);
+    }
+    return { previewEndpoint: target.previewEndpoint, relayToken };
+}

package/dist/core/worktree.d.ts

@@ -20,14 +20,14 @@ export interface CloseManagedWorktreeResult {
     node_id: string;
     branch: string;
     worktree_path: string;
-    pushed_sha: string;
-    /** False when the push landed but the worktree checkout could not be removed
-     *  automatically afterward — the close still counts as done (state is
+    landed_sha: string;
+    /** False when the landing happened but the worktree checkout could not be
+     *  removed automatically afterward — the close still counts as done (state is
      *  closed, push-final is unblocked); `worktree_remove_error` carries the
      *  manual cleanup note. */
     worktree_removed: boolean;
     worktree_remove_error?: string;
-    /** False when the push landed but the local branch could not be deleted
+    /** False when the landing happened but the local branch could not be deleted
      *  afterward — same non-fatal treatment as worktree_removed. */
     branch_deleted: boolean;
     branch_delete_error?: string;