@north-light/api 0.3.580 → 0.3.587

package/dist/core/runtime/setup-marker.js

@@ -0,0 +1,46 @@
+// The machine-wide record that crouter's first-run setup has happened, and
+// whether the first root has been offered the tutorial yet. Bare `crtr` runs the
+// setup wizard when this file is absent, and `crtr sys setup` writes it too, so
+// a person who runs either never sees the wizard twice.
+//
+// The tutorial offer is a separate flag because setup and the first root boot
+// can happen on different invocations: a first `crtr` outside tmux runs setup,
+// then exits asking for a tmux session. The offer must survive to the next
+// `crtr` that actually boots a root.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { runtimeRoot } from '../layout.js';
+function markerPath() {
+    return join(runtimeRoot(), 'setup-completed.json');
+}
+export function setupCompleted() {
+    return existsSync(markerPath());
+}
+/** Record a finished setup run. A first setup leaves the tutorial offer
+ *  pending; a re-run keeps whatever the earlier marker said about it. */
+export async function recordSetupCompleted(outcome) {
+    const [{ atomicWriteJson, readJsonOrNull }, { crtrVersion }] = await Promise.all([
+        import('../fs-utils.js'),
+        import('../../shared/crtr-version.js'),
+    ]);
+    const previous = readJsonOrNull(markerPath());
+    atomicWriteJson(markerPath(), {
+        packageVersion: crtrVersion(),
+        completedAt: new Date().toISOString(),
+        outcome,
+        tourOffered: previous === null ? false : previous.tourOffered !== false,
+    });
+}
+/** True while setup has run but no root has booted since. */
+export async function tourOfferPending() {
+    const { readJsonOrNull } = await import('../fs-utils.js');
+    return readJsonOrNull(markerPath())?.tourOffered === false;
+}
+/** The root that carries the offer is booting; never offer it again. */
+export async function markTourOffered() {
+    const { atomicWriteJson, readJsonOrNull } = await import('../fs-utils.js');
+    const previous = readJsonOrNull(markerPath());
+    if (previous === null)
+        return;
+    atomicWriteJson(markerPath(), { ...previous, tourOffered: true });
+}

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

@@ -0,0 +1,16 @@
+/** The `customType` stamped on the hidden custom message the inbox watcher
+ *  sends for an existing node's situational-context update. */
+export { SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../../shared/generated-context.js';
+/** Render prose supplied through a `situational_context` string entry point
+ *  (`crtr node message --situational-context`, the node-create seed) as the
+ *  card the sidecar stores. Card-supplying callers pass their own rendered
+ *  envelope to `appendSituationalContext` instead. Blank prose renders as ''
+ *  so the sidecar write stays a no-op rather than storing an empty card. */
+export declare function formatSituationalProse(prose: string): string;
+/** Upsert the node's current situational context (replace, not append) — the
+ *  one sanctioned writer for the sidecar, taking an ALREADY-RENDERED envelope.
+ *  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): Promise<void>;
+/** The node's latest situational card, never read from the control plane's disk. */
+export declare function situationalContextEnvelope(nodeId: string): Promise<string | null>;

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

@@ -0,0 +1,54 @@
+// situational-context.ts — the hidden ambient "current situation" sidecar.
+//
+// A node-owned run file (nodes/<id>/situational-context.md, NOT under
+// context/ — see `situationalContextPath`) storing ONE rendered runtime-card
+// envelope describing the LATEST situation: 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, so
+// stale applet pages never accumulate across concierge reuse.
+//
+// `situationalContextEnvelope()` is the ONE read, and it yields the stored card
+// verbatim — no caller downstream has a shape to check. Its three callers use
+// it differently, and only the last nests:
+//   - canvas-inbox-watcher's context channel — delivered verbatim as a custom
+//     message's content, with SITUATIONAL_CONTEXT_CUSTOM_TYPE as delivery
+//     metadata only.
+//   - setSituationalContextLive() (warm-spare claim) — the same verbatim
+//     delivery, `deliverAs: 'nextTurn'`.
+//   - buildContextBearingsFromState() / buildForkBearingsFromState() — the card
+//     is placed in the bearings body, where it is deliberately a nested card
+//     inside the outer `bearings` card. The only nesting site in the system.
+//
+// The visible revive kickoff carries NO situational context: a fresh or cycling
+// revive receives it through the session-start bearings instead.
+import { openDb } from '../canvas/db.js';
+import { formatCard, parseCard } from '../../shared/generated-context.js';
+/** The `customType` stamped on the hidden custom message the inbox watcher
+ *  sends for an existing node's situational-context update. */
+export { SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../../shared/generated-context.js';
+/** Render prose supplied through a `situational_context` string entry point
+ *  (`crtr node message --situational-context`, the node-create seed) as the
+ *  card the sidecar stores. Card-supplying callers pass their own rendered
+ *  envelope to `appendSituationalContext` instead. Blank prose renders as ''
+ *  so the sidecar write stays a no-op rather than storing an empty card. */
+export function formatSituationalProse(prose) {
+    return prose.trim() === '' ? '' : formatCard('situational', {}, prose);
+}
+/** Upsert the node's current situational context (replace, not append) — the
+ *  one sanctioned writer for the sidecar, taking an ALREADY-RENDERED envelope.
+ *  No-op for blank text, so a caller can pass through an optional/empty value
+ *  with no guard at the call site. */
+export async function appendSituationalContext(nodeId, text) {
+    const body = text.trim();
+    if (body === '')
+        return;
+    await (await openDb()).prepare('UPDATE nodes SET situational_card = ? WHERE node_id = ?').run(body + '\n', nodeId);
+}
+/** The node's latest situational card, never read from the control plane's disk. */
+export async function situationalContextEnvelope(nodeId) {
+    const row = await (await openDb()).prepare('SELECT situational_card FROM nodes WHERE node_id = ?').get(nodeId);
+    const text = row?.situational_card?.trim() ?? '';
+    if (text === '')
+        return null;
+    return parseCard({ content: text }) === null ? formatSituationalProse(text) : text;
+}

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

@@ -0,0 +1,9 @@
+/** Write `text` (prose) to the node's sidecar and, when its broker is live,
+ *  deliver the stored card into the running session for the NEXT turn.
+ *
+ *  Rejects when a live broker cannot be reached or refuses the frame — the
+ *  caller decides what that means. For a warm claim it is fatal (a node holding
+ *  the wrong situation is worse than a slow one), the same call the model swap
+ *  makes. A DORMANT node needs no delivery at all: its next revive renders the
+ *  sidecar into the kickoff. */
+export declare function setSituationalContextLive(nodeId: string, text: string): Promise<void>;

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

@@ -0,0 +1,41 @@
+// situational-live.ts — hand a node its situational context WITHOUT waking it.
+//
+// The sidecar (`situational-context.ts`) is the durable half: it stores one
+// rendered `situational` card, which every revive path nests into the bearings.
+// This module is the LIVE half for a node whose session has already passed
+// `session_start` — the warm-pool claim, where a spare booted with no
+// situational context is handed to a claimant that has one. The stored card is
+// delivered UNWRAPPED; the customType is delivery metadata only.
+//
+// It is deliberately NOT the inbox watcher's situational send. That seam exists
+// to WAKE a live node when its applet situation changes. A freshly-claimed
+// spare must not run a turn before its owner says anything, so this path uses
+// `nextTurn` delivery: the card rides the claimant's first real turn instead of
+// starting one.
+//
+// Everything below the sidecar write is the shared live-delivery path
+// (`deliver-live.ts`), which the claim's bearings delivery also rides.
+import { getNode } from '../canvas/index.js';
+import { deliverCustomMessageLive } from './deliver-live.js';
+import { appendSituationalContext, formatSituationalProse, situationalContextEnvelope, SITUATIONAL_CONTEXT_CUSTOM_TYPE, } from './situational-context.js';
+/** Write `text` (prose) to the node's sidecar and, when its broker is live,
+ *  deliver the stored card into the running session for the NEXT turn.
+ *
+ *  Rejects when a live broker cannot be reached or refuses the frame — the
+ *  caller decides what that means. For a warm claim it is fatal (a node holding
+ *  the wrong situation is worse than a slow one), the same call the model swap
+ *  makes. A DORMANT node needs no delivery at all: its next revive renders the
+ *  sidecar into the kickoff. */
+export async function setSituationalContextLive(nodeId, text) {
+    await appendSituationalContext(nodeId, formatSituationalProse(text));
+    if (await getNode(nodeId) === null)
+        throw new Error(`setSituationalContextLive: unknown node ${nodeId}`);
+    const envelope = await situationalContextEnvelope(nodeId);
+    if (envelope === null)
+        return; // no sidecar at all — blank text on a node that never had one
+    await deliverCustomMessageLive(nodeId, {
+        customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE,
+        content: envelope,
+        deliverAs: 'nextTurn',
+    });
+}

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

@@ -0,0 +1,5 @@
+import type { PiInvocation } from './invocation.js';
+/** The app process env for a launch: the secrets of the node's environment (the app's rows, the environment owner's profile rows, the deployment rows). */
+export declare function buildAppProcessEnv(targetCwd: string, targetProfileId: string | null, app: string): Promise<NodeJS.ProcessEnv>;
+/** The one authoritative broker child env; every broker launch funnels through `headlessBrokerHost.launch()`, which calls this. */
+export declare function buildBrokerEnv(inv: PiInvocation): Promise<NodeJS.ProcessEnv>;

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

@@ -0,0 +1,15 @@
+// The daemon-side half of the spawn env: reads the sealed env rows and hands them to the pure builders in `spawn-env.ts`.
+// Kept apart because this file reaches Postgres (through the env stores); a CLI leaf must not import it (V-1) and `spawn-env.ts` must stay free of it.
+import { localEnvironmentSecrets } from '../secrets/environment-owner.js';
+import { composeAppProcessEnv, overlayBrokerEnv } from './spawn-env.js';
+/** The app process env for a launch: the secrets of the node's environment (the app's rows, the environment owner's profile rows, the deployment rows). */
+export async function buildAppProcessEnv(targetCwd, targetProfileId, app) {
+    return composeAppProcessEnv(targetCwd, targetProfileId, app, await localEnvironmentSecrets(targetProfileId, app), {});
+}
+/** The one authoritative broker child env; every broker launch funnels through `headlessBrokerHost.launch()`, which calls this. */
+export async function buildBrokerEnv(inv) {
+    const targetCwd = inv.env['CRTR_NODE_CWD'] ?? process.cwd();
+    const targetProfileId = inv.env['CRTR_PROFILE_ID'] || null;
+    const app = inv.env['CRTR_GRANTEE'] ?? 'app:terminal';
+    return overlayBrokerEnv(inv, await buildAppProcessEnv(targetCwd, targetProfileId, app));
+}

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

@@ -0,0 +1,40 @@
+import type { PiInvocation } from './invocation.js';
+import type { ModelProvider } from '../../types.js';
+/** The unshimmed PATH admitted from the host. Broker and cron shells resolve
+ *  crouter-owned executables from this value, while commands those shells run
+ *  still receive the shim-prepended PATH. */
+export declare const ADMITTED_HOST_PATH_ENV = "CRTR_ADMITTED_HOST_PATH";
+/** Resolve a regular executable against a shell PATH without executing it.
+ *  The result is absolute, or null when no PATH entry supplies the command. */
+export declare function resolvePathExecutable(name: string, env: NodeJS.ProcessEnv, cwd: string): string | null;
+export declare function resolveAdmittedHostCommand(name: string, env: NodeJS.ProcessEnv, cwd: string): string;
+/** Vendor keys stay with the daemon, even when an explicit profile or host
+ *  allowlist names one of them. The front-door credential check uses this map. */
+export declare const PROVIDER_ENV_KEYS: Record<ModelProvider, string>;
+/** Sources A–C: the operational base shared by the broker boundary (this
+ *  module's `buildBrokerEnv`) and cron executor — the single shared definition
+ *  of "non-secret host state the runtime exposes to any spawned shell." Does not include
+ *  `inv.env`/`FRONT_DOOR_ENV` (source D), which is broker-specific. */
+export declare function buildOperationalEnvBase(opts: {
+    /** The TARGET node's cwd — never the calling/daemon process's own ambient
+     *  `process.cwd()`. Threaded into `readMergedLaunchConfig` so source C
+     *  (`spawnEnv.allow`) resolves from the TARGET's own project-scope config,
+     *  not whichever cwd happened to launch the process that builds this env. */
+    targetCwd: string;
+    /** The TARGET node's profile id — never the calling process's own ambient
+     *  `CRTR_PROFILE_ID`. `null`/`''` for no profile. */
+    targetProfileId: string | null;
+    host?: NodeJS.ProcessEnv;
+    /** App runs do not inherit the owner project's explicit host-env allowlist. */
+    skipSpawnAllow?: boolean;
+}): NodeJS.ProcessEnv;
+/** Source F — the TARGET profile's manifest `metadata`, each entry surfaced
+ *  as `CRTR_PROFILE_META_<KEY>` (key uppercased, every non-alphanumeric run
+ *  → `_`). Identity facts rather than secrets — unlike the env store these
+ *  are readable back (`profile show`, ProfileDTO). Read straight off the
+ *  manifest at every launch; never throws (a bad profile id yields `{}`). */
+export declare function profileMetadataEnv(profileId: string | null): NodeJS.ProcessEnv;
+/** The app process env: the operational base, the app's and the target profile's stored rows (read by `spawn-env-rows.ts`), and the pins below. */
+export declare function composeAppProcessEnv(targetCwd: string, targetProfileId: string | null, app: string, appVars: Record<string, string>, profileVars: Record<string, string>): NodeJS.ProcessEnv;
+/** A broker's env: the trusted `inv.env` overlay on an app process env, plus the fork-bomb guard. */
+export declare function overlayBrokerEnv(inv: PiInvocation, base: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

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

@@ -0,0 +1,260 @@
+// 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), or
+// an explicit `spawnEnv.allow` entry (C). A separate source E, the TARGET
+// profile's own `profile env` store
+// (`core/profiles/env-store.ts`), is read directly off disk — never through
+// `process.env` — and injected unconditionally: storing a value there IS the
+// operator's consent to cross the boundary, so it needs no matching
+// `spawnEnv.allow` entry. `inv.env` (D) is crtr-constructed and trusted, so
+// it overlays unconditionally, layered after E.
+//
+// One name IS rewritten rather than merely admitted: `PATH`. Bare-binary
+// contributions (`bin` in a plugin manifest or a scope `config.json`) are
+// materialized into a crouter-owned shim directory by
+// `core/runtime/bin-contributions.ts`, and that directory is PREPENDED here so
+// a declared bare command wins its name in every node's bash. The admitted
+// host PATH stays intact behind it.
+//
+// `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 { statSync } from 'node:fs';
+import { SANDBOX_RUNTIME_HOME } from '../spaces/runtime-home.js';
+import { appProcessHome, appSpace, layoutRoot, runtimeRoot } from '../layout.js';
+import { delimiter, join, resolve } from 'node:path';
+import { readMergedLaunchConfig } from '../config.js';
+import { loadProfileManifest, metadataEnvName, readProfileMetadata } from '../profiles/manifest.js';
+import { binShimDirFor } from './bin-contributions.js';
+import { FRONT_DOOR_ENV } from './front-door-env.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',
+    '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_'];
+/** The unshimmed PATH admitted from the host. Broker and cron shells resolve
+ *  crouter-owned executables from this value, while commands those shells run
+ *  still receive the shim-prepended PATH. */
+export const ADMITTED_HOST_PATH_ENV = 'CRTR_ADMITTED_HOST_PATH';
+/** Resolve a regular executable against a shell PATH without executing it.
+ *  The result is absolute, or null when no PATH entry supplies the command. */
+export function resolvePathExecutable(name, env, cwd) {
+    const pathValue = env['PATH'];
+    if (pathValue === undefined || pathValue === '')
+        return null;
+    for (const directory of pathValue.split(delimiter)) {
+        const candidate = resolve(cwd, directory === '' ? '.' : directory, name);
+        try {
+            const stat = statSync(candidate);
+            if (stat.isFile() && (stat.mode & 0o111) !== 0)
+                return candidate;
+        }
+        catch {
+            // Keep searching exactly as PATH resolution does.
+        }
+    }
+    return null;
+}
+export function resolveAdmittedHostCommand(name, env, cwd) {
+    const pathValue = env[ADMITTED_HOST_PATH_ENV] ?? env['PATH'];
+    if (pathValue === undefined || pathValue === '') {
+        throw new Error(`cannot resolve crouter-owned ${name}: the admitted host PATH is empty`);
+    }
+    const command = resolvePathExecutable(name, { PATH: pathValue }, cwd);
+    if (command !== null)
+        return command;
+    throw new Error(`cannot resolve crouter-owned ${name} from the admitted host PATH`);
+}
+/** 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'];
+/** Vendor keys stay with the daemon, even when an explicit profile or host
+ *  allowlist names one of them. The front-door credential check uses this map. */
+export 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 the broker boundary (this
+ *  module's `buildBrokerEnv`) and cron executor — the single shared definition
+ *  of "non-secret host state the runtime exposes to any spawned shell." Does not include
+ *  `inv.env`/`FRONT_DOOR_ENV` (source D), which is broker-specific. */
+export 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;
+        }
+    }
+    // The spawned process starts in the target cwd, not the daemon's cwd.
+    out['PWD'] = opts.targetCwd;
+    // 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;
+    }
+    // C — explicit config-declared extra allowlist (literal names and/or
+    // globs), resolved from the TARGET's own cwd/profile scope (default empty).
+    const allow = opts.skipSpawnAllow ? [] : 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;
+        }
+    }
+    // Preserve the unshimmed admitted host PATH across broker and cron children.
+    // A nested `crtr` launched from an agent inherits this constructed value,
+    // rather than mistaking its shim-prepended PATH for the host path.
+    const admittedHostPath = host[ADMITTED_HOST_PATH_ENV] ?? out['PATH'];
+    if (admittedHostPath !== undefined && admittedHostPath !== '')
+        out[ADMITTED_HOST_PATH_ENV] = admittedHostPath;
+    // Bare-binary contributions (`core/runtime/bin-contributions.ts`): the shim
+    // dir holding one symlink per declared bare command, PREPENDED so a
+    // contribution wins its name, with the host PATH admitted above left intact
+    // behind it. Resolved from the TARGET's own cwd/profile like source C.
+    const shimDir = binShimDirFor(opts.targetCwd, opts.targetProfileId);
+    if (shimDir !== null) {
+        const hostPath = out['PATH'];
+        out['PATH'] = hostPath === undefined || hostPath === '' ? shimDir : `${shimDir}:${hostPath}`;
+    }
+    return out;
+}
+/** Source F — the TARGET profile's manifest `metadata`, each entry surfaced
+ *  as `CRTR_PROFILE_META_<KEY>` (key uppercased, every non-alphanumeric run
+ *  → `_`). Identity facts rather than secrets — unlike the env store these
+ *  are readable back (`profile show`, ProfileDTO). Read straight off the
+ *  manifest at every launch; never throws (a bad profile id yields `{}`). */
+export function profileMetadataEnv(profileId) {
+    const out = {};
+    for (const [key, value] of Object.entries(readProfileMetadata(profileId))) {
+        out[metadataEnvName(key)] = value;
+    }
+    return out;
+}
+/** The app process env: the operational base, the app's and the target profile's stored rows (read by `spawn-env-rows.ts`), and the pins below. */
+export function composeAppProcessEnv(targetCwd, targetProfileId, app, appVars, profileVars) {
+    const manifest = targetProfileId === null ? null : loadProfileManifest(targetProfileId).manifest;
+    const operational = buildOperationalEnvBase({ targetCwd, targetProfileId, skipSpawnAllow: app !== 'app:terminal' });
+    const env = {
+        ...operational,
+        ...appVars,
+        ...(manifest === null ? {} : profileMetadataEnv(targetProfileId)),
+        ...profileVars,
+        HOME: appProcessHome(app),
+        // pi's agent dir stays in the app home even when HOME is the person's: the
+        // daemon writes broker models.json there, never into the person's ~/.pi.
+        PI_CODING_AGENT_DIR: join(appSpace(app).home, '.pi', 'agent'),
+        [ADMITTED_HOST_PATH_ENV]: operational[ADMITTED_HOST_PATH_ENV],
+        // HOME is the app's home, so crouter's own `~/.crouter` defaults (the volume
+        // root, and the `crtr` shim's runtime selection) would resolve inside it; pin
+        // the ones the daemon runs on.
+        ...(process.platform === 'linux' ? { CRTR_RUNTIME_HOME: SANDBOX_RUNTIME_HOME } : {
+            CRTR_HOME: layoutRoot(),
+            CRTR_RUNTIME_HOME: process.env['CRTR_RUNTIME_HOME'] ?? runtimeRoot(),
+        }),
+    };
+    for (const key of Object.values(PROVIDER_ENV_KEYS))
+        delete env[key];
+    return env;
+}
+/** A broker's env: the trusted `inv.env` overlay on an app process env, plus the fork-bomb guard. */
+export function overlayBrokerEnv(inv, base) {
+    const brokerEnv = {
+        ...base,
+        ...inv.env,
+        HOME: base['HOME'],
+        PI_CODING_AGENT_DIR: base['PI_CODING_AGENT_DIR'],
+        [ADMITTED_HOST_PATH_ENV]: base[ADMITTED_HOST_PATH_ENV],
+        CRTR_RUNTIME_HOME: base['CRTR_RUNTIME_HOME'],
+        [FRONT_DOOR_ENV]: '1',
+    };
+    for (const key of Object.values(PROVIDER_ENV_KEYS))
+        delete brokerEnv[key];
+    return brokerEnv;
+}