@north-light/api 0.3.580 → 0.3.587

package/dist/core/runtime/host.js

@@ -0,0 +1,695 @@
+// src/core/runtime/host.ts
+//
+// The Host abstraction (design §3): owns an engine PROCESS's lifecycle, not its
+// display. After the broker-is-the-host cut there is ONE impl —
+// HeadlessBrokerHost — a detached broker process with no tmux pane. Every node
+// (managed child, named node, --root, front-door root) runs on it; a tmux pane
+// is only an attach VIEWER. The `Host` interface is kept as a one-impl seam (the
+// test/future-host boundary).
+//
+// This file imports neither './tmux.js' nor './placement.js' — the broker host
+// needs no tmux verb at all (it supervises via the broker pid, tears down over
+// the node's unix socket).
+import { assertGranteeRunsHere } from './unsandboxed.js';
+import { spawn } from 'node:child_process';
+import { mkdirSync, existsSync, unlinkSync, openSync, closeSync, writeSync, chmodSync, lstatSync } from 'node:fs';
+import { ensureAppSpace } from '../spaces/space.js';
+import { sandboxCacheEnv } from '../spaces/cache-env.js';
+import { compileLaunch, launchStillGranted } from '../spaces/mounts.js';
+import { grantsGeneration } from '../grants/mirror.js';
+import { LAUNCHER_SOCKET } from '../../launcher/spec.js';
+import { launcherRequest } from '../../launcher/client.js';
+import { piAgentDir } from './package-health.js';
+import { existsBeneath, readFileBeneath, readTextBeneathIfExists, setModeBeneath, withDirBeneath, writeFileBeneath } from '../spaces/open-beneath.js';
+import { dirname, join, resolve, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { connectViewSocket } from './view-socket.js';
+import { appSpace } from '../layout.js';
+import { readConfig, readMergedLaunchConfig } from '../config.js';
+import { loadRotationConfig } from '../subscription-state.js';
+import { getNode } from '../canvas/index.js';
+import { withCanvasWrite } from '../canvas/db.js';
+import { requestExecutionStop } from '../canvas/executions.js';
+import { scopesFilePath, crtrHome, nodeRunDir, nodeRunJobDir, jobDir, viewSocketPath, nodeAgentDir, contextDir, nodeHome } from '../canvas/paths.js';
+import { encodeFrame } from './broker-protocol.js';
+import { buildBrokerEnv } from './spawn-env-rows.js';
+import { hostExecPathFresh } from './branded-host.js';
+import { isPidAlive, killProcessTreePids, isAnyPidAlive, captureTeardownSnapshot } from '../canvas/pid.js';
+import { assertMandatoryCanvasExtensions } from './canvas-extensions.js';
+import { appMemoryFull, appMemoryTooSmall, boundFleet, brokerCapReached, brokerThresholdsForDaemon } from './fleet.js';
+import { admitBrokerMemory } from './memory-admission.js';
+import { emitEvent } from '../events/emit.js';
+import { bindBrokerEventSource, eventSource } from '../events/source.js';
+import { envBrokerEngine } from '../../shared/env.js';
+import { conversationIdFromPath, conversationStore, ConversationNotFoundError } from '../conversation-store/index.js';
+import { mintNodeToken } from '../canvas/node-tokens.js';
+import { personId } from '../canvas/person.js';
+// HeadlessBrokerHost (design §3.3): a detached broker PROCESS, no tmux pane. It
+// boots the dedicated broker-cli entry directly (NEVER src/cli.ts), supervises
+// via the broker pid recorded as pi_pid, and tears down over the node's unix
+// socket (graceful `shutdown` frame, SIGTERM fallback).
+/** Resolve the broker entry beside this module. A broker must run from the
+ *  same generation as the crtrd launching it, so module-relative resolution
+ *  preserves that invariant. */
+function resolveBrokerEntry() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, 'broker-cli.js');
+}
+const DEFAULT_BROKER_ENGINE = '@earendil-works/pi-coding-agent';
+/** The scrubbed models.json the broker's agent dir carries, or null when the
+ *  operator has none. Credentials are stripped; they live in daemon secrets. */
+function scrubbedBrokerModels() {
+    const source = join(piAgentDir(), 'models.json');
+    const text = readTextBeneathIfExists(dirname(source), source);
+    if (text === null)
+        return null;
+    const models = JSON.parse(text);
+    const scrub = (value) => {
+        if (Array.isArray(value))
+            return value.map(scrub);
+        if (value === null || typeof value !== 'object')
+            return value;
+        return Object.fromEntries(Object.entries(value).filter(([key]) => !/^(apiKey|authorization|headers|token|secret)$/i.test(key)).map(([key, item]) => [key, scrub(item)]));
+    };
+    return { text, clean: `${JSON.stringify(scrub(models), null, 2)}\n`, credentialed: JSON.stringify(models) !== JSON.stringify(scrub(models)) };
+}
+function writeBrokerModels(home, agentDir) {
+    const source = join(piAgentDir(), 'models.json');
+    const target = join(agentDir, 'models.json');
+    const models = scrubbedBrokerModels();
+    if (models === null)
+        return;
+    if (source === target && models.text !== models.clean) {
+        // Never overwrite an operator's source model configuration in place.
+        if (models.credentialed)
+            throw new Error('terminal models.json contains credentials; move them into daemon secrets');
+        setModeBeneath(home, target, 0o660);
+        return;
+    }
+    writeFileBeneath(home, target, models.clean, { atomic: true, mode: 0o660 });
+    setModeBeneath(home, target, 0o660);
+}
+/** 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'] ?? envBrokerEngine();
+}
+function isPlainLaunchSessionPath(token) {
+    return token.includes('/') || token.endsWith('.jsonl');
+}
+function resolvePlainLaunchPath(token, cwd) {
+    return isAbsolute(token) ? token : resolve(cwd, token);
+}
+async function preflightLaunchSessionArg(nodeId, cwd, flag, value) {
+    if (flag === '--session' && !isPlainLaunchSessionPath(value)) {
+        throw new Error(`[broker] refusing to launch ${nodeId}: launch recipe passes bare --session id '${value}' — the broker fatally rejects bare ids; pass the .jsonl path instead.`);
+    }
+    if (!isPlainLaunchSessionPath(value))
+        return;
+    const sessionPath = resolvePlainLaunchPath(value, cwd);
+    const id = conversationIdFromPath(sessionPath);
+    try {
+        if (id === null)
+            throw new ConversationNotFoundError(sessionPath);
+        await conversationStore().header(id);
+    }
+    catch (error) {
+        if (!(error instanceof ConversationNotFoundError))
+            throw error;
+        const label = flag === '--session' ? 'session file' : 'fork source';
+        throw new Error(`[broker] refusing to launch ${nodeId}: launch recipe references missing ${label} '${value}' (${sessionPath})`);
+    }
+}
+/** The launch recipe stored in `executions.launch_json`: the invocation, the
+ *  config snapshot, the node's `scopes` (null when unnarrowed) and the scrubbed
+ *  `models` object (null when the operator has no models.json) — everything a
+ *  runner on another machine needs to rebuild the broker's run dir and agent dir. */
+export async function brokerLaunchJson(nodeId, inv, cwd) {
+    const models = scrubbedBrokerModels();
+    return JSON.stringify({ ...inv, configSnapshot: {
+            user: readConfig('user'),
+            launch: readMergedLaunchConfig(cwd, inv.env['CRTR_PROFILE_ID'] || null),
+            rotation: await loadRotationConfig(),
+        }, scopes: (await getNode(nodeId))?.scopes ?? null,
+        models: models === null ? null : JSON.parse(models.clean) });
+}
+/** Validate the broker launch recipe before we detach a child process. This is
+ *  the fast-fail seam for known module/path errors: a bad engine resolve or a
+ *  missing plain session path throws here, before spawn(). */
+export async function preflightBrokerLaunch(nodeId, inv, cwd, launchJson) {
+    const dir = nodeRunDir(nodeId);
+    mkdirSync(dir, { recursive: true });
+    if (process.platform === 'linux' && existsSync(LAUNCHER_SOCKET) && lstatSync(dir).uid === process.getuid())
+        chmodSync(dir, 0o770);
+    const launchPath = join(dir, 'broker-launch.json');
+    writeFileBeneath(dir, launchPath, launchJson ?? await brokerLaunchJson(nodeId, inv, cwd), { atomic: true });
+    if (inv.env['CRTR_SCOPES_FILE'] !== undefined) {
+        // Same folder and writer as the launch recipe: the env carries only this path.
+        writeFileBeneath(dir, scopesFilePath(nodeId), JSON.stringify((await getNode(nodeId))?.scopes ?? []), { atomic: true });
+    }
+    const raw = readFileBeneath(dir, launchPath).toString('utf8');
+    const recipe = JSON.parse(raw);
+    if (!Array.isArray(recipe.argv)) {
+        throw new Error(`[broker] refusing to launch ${nodeId}: broker-launch.json is missing the argv array`);
+    }
+    const engineSpec = resolveEngineSpec(inv);
+    try {
+        const resolvedEngine = import.meta.resolve(engineSpec);
+        if (resolvedEngine.startsWith('file:') && !existsSync(fileURLToPath(resolvedEngine))) {
+            throw new Error(`resolved to missing file ${resolvedEngine}`);
+        }
+    }
+    catch (error) {
+        throw new Error(`[broker] refusing to launch ${nodeId}: cannot resolve broker engine '${engineSpec}' from ${resolveBrokerEntry()} — ${error.message}`);
+    }
+    const argv = recipe.argv;
+    const extensionPaths = [];
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (tok === '-e') {
+            const value = argv[++i];
+            if (value !== undefined)
+                extensionPaths.push(value);
+            continue;
+        }
+        if (tok !== '--session' && tok !== '--fork')
+            continue;
+        const value = argv[++i];
+        if (value === undefined)
+            continue;
+        await preflightLaunchSessionArg(nodeId, cwd, tok, value);
+    }
+    try {
+        assertMandatoryCanvasExtensions(extensionPaths);
+    }
+    catch (error) {
+        throw new Error(`[broker] refusing to launch ${nodeId}: ${error.message}`);
+    }
+}
+/** How long teardown waits after sending the graceful `shutdown` frame before
+ *  escalating a broker/tree that connected but never fully exited (e.g. a hung
+ *  dispose(), or a dispose() that reaped the broker but left a descendant
+ *  behind). */
+const BROKER_SHUTDOWN_GRACE_MS = 2_000;
+/** How long teardown waits after the tree-wide SIGTERM before the final
+ *  tree-wide SIGKILL sweep — the last resort for a broker (or its
+ *  descendants) that ignores SIGTERM entirely. */
+const BROKER_SIGKILL_GRACE_MS = 2_000;
+/** How often `pollUntilTreeDead` re-checks the process TREE. Short enough that
+ *  the common/happy path (tree already dead) pays only a couple of ticks; the
+ *  full grace ceilings above are reserved for the genuinely-wedged case,
+ *  where the added latency is the whole point. */
+const TEARDOWN_POLL_MS = 150;
+/** Wait against the fixed snapshot. The ref'd timer keeps a short-lived
+ * caller alive through the final SIGKILL confirmation. */
+async function waitForTreeExit(tree, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (isAnyPidAlive(tree)) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, Math.min(TEARDOWN_POLL_MS, remaining)));
+    }
+    return true;
+}
+/** Finish one teardown using the snapshot captured before any signal can sever
+ * broker parentage. A failed confirmation is explicit so post-teardown cleanup
+ * never runs against an engine tree that may still own its resources. */
+async function terminateBrokerTree(tree, identities, graceful) {
+    if (tree.length === 0)
+        return { confirmed: true };
+    if (graceful && await waitForTreeExit(tree, BROKER_SHUTDOWN_GRACE_MS))
+        return { confirmed: true };
+    killProcessTreePids(tree, 'SIGTERM', identities);
+    if (await waitForTreeExit(tree, BROKER_SIGKILL_GRACE_MS))
+        return { confirmed: true };
+    killProcessTreePids(tree, 'SIGKILL', identities);
+    if (await waitForTreeExit(tree, 5_000))
+        return { confirmed: true };
+    return { confirmed: false, error: new Error(`broker process tree for ${tree.join(', ')} remained alive after SIGKILL`) };
+}
+/** Capture the one authoritative process snapshot before a caller can reap the
+ * node row. No signal or socket operation occurs here; execution remains queued
+ * until the close response has settled. */
+async function prepareBrokerTeardown(nodeId, opts) {
+    const node = await getNode(nodeId);
+    const pid = node?.pi_pid;
+    const snapshot = pid != null
+        ? captureTeardownSnapshot(pid, node?.pi_pid_identity ?? null, opts.excludePid)
+        : null;
+    if (snapshot?.reused === true) {
+        emitEvent({
+            level: 'warn',
+            event: 'broker.teardown.pid_reuse_refused',
+            node_id: nodeId,
+            fields: { recorded_pid: pid, expected_identity: node?.pi_pid_identity ?? null },
+        });
+    }
+    return {
+        tree: snapshot?.tree ?? [],
+        identities: snapshot?.identities ?? null,
+        nodeId,
+        launcherPid: existsSync(LAUNCHER_SOCKET) && snapshot?.tree.includes(pid) ? pid : null,
+    };
+}
+async function runPreparedBrokerTeardown(prepared) {
+    if (prepared.launcherPid !== null) {
+        try {
+            await launcherRequest({ operation: 'stop', pid: prepared.launcherPid });
+        }
+        catch (error) {
+            if (!isPidAlive(prepared.launcherPid))
+                return { confirmed: true };
+            return { confirmed: false, error: error instanceof Error ? error : new Error(String(error)) };
+        }
+        return await waitForTreeExit([prepared.launcherPid], 5_000)
+            ? { confirmed: true }
+            : { confirmed: false, error: new Error(`launcher pid ${prepared.launcherPid} remained alive`) };
+    }
+    // Even a dead broker pid can still be the process-group leader for an orphan
+    // that the initial ppid walk could no longer reach. The connect-failure path
+    // must retain that leader id for group signaling rather than treating its dead
+    // status as confirmation that no descendant survives.
+    return new Promise((resolve) => {
+        let connected = false;
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        const cleanupSocket = () => {
+            try {
+                unlinkSync(viewSocketPath(prepared.nodeId));
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+        };
+        const finish = (graceful) => {
+            void terminateBrokerTree(prepared.tree, prepared.identities, graceful).then(settle, (error) => settle({ confirmed: false, error: error instanceof Error ? error : new Error(String(error)) }));
+        };
+        const sock = connectViewSocket(prepared.nodeId);
+        sock.once('error', () => {
+            if (connected)
+                return;
+            cleanupSocket();
+            finish(false);
+        });
+        sock.once('connect', () => {
+            connected = true;
+            try {
+                // The broker admits `shutdown` from a controller only; an unhelloed socket is an observer.
+                sock.write(encodeFrame({ type: 'hello', role: 'controller', client_id: `daemon-shutdown-${process.pid}` }));
+                sock.write(encodeFrame({ type: 'shutdown' }));
+            }
+            catch {
+                /* the broker may have raced us to exit */
+            }
+            sock.end();
+            cleanupSocket();
+            finish(true);
+        });
+    });
+}
+/** Record the stop on the node's live execution row, then tear the broker down in this process: on the next event-loop
+ * turn, or once `opts.startAfter` settles. The row is what survives this process: when it dies before the teardown
+ * completes, the node-lifecycle claim holder enacts the stop from `stop_requested_at` / `stop_after_turn`
+ * (`enactRequestedStops`). Completion includes any post-teardown work, which lets the daemon drain it during shutdown;
+ * that work is this call's closure and does not outlive the process. */
+export async function requestBrokerTeardown(nodeId, opts = {}, after) {
+    let prepared;
+    try {
+        await requestExecutionStop(nodeId, { afterTurn: opts.startAfter !== undefined, reason: opts.reason ?? 'teardown' });
+        prepared = await prepareBrokerTeardown(nodeId, opts);
+    }
+    catch (error) {
+        const failure = { confirmed: false, error: error instanceof Error ? error : new Error(String(error)) };
+        emitEvent({ level: 'error', event: 'broker.teardown.unconfirmed', node_id: nodeId, error: failure.error });
+        return failure;
+    }
+    return await new Promise((resolve) => {
+        const run = () => {
+            void runPreparedBrokerTeardown(prepared).then(async (result) => {
+                if (result.confirmed) {
+                    if (after !== undefined) {
+                        try {
+                            await after();
+                        }
+                        catch (error) {
+                            emitEvent({ level: 'error', event: 'broker.teardown.after_failed', node_id: nodeId, error });
+                        }
+                    }
+                }
+                else {
+                    emitEvent({ level: 'error', event: 'broker.teardown.unconfirmed', node_id: nodeId, error: result.error });
+                }
+                resolve(result);
+            }, (error) => {
+                const failure = { confirmed: false, error: error instanceof Error ? error : new Error(String(error)) };
+                emitEvent({ level: 'error', event: 'broker.teardown.unconfirmed', node_id: nodeId, error: failure.error });
+                resolve(failure);
+            });
+        };
+        if (opts.startAfter === undefined)
+            setImmediate(run);
+        else
+            void opts.startAfter.then(run, run);
+    });
+}
+/** Isolated brokers require the Linux launcher; direct host spawn cannot enforce their filesystem or network policy. */
+export function isolatedBrokerLauncherAvailable() {
+    return process.platform === 'linux' && existsSync(LAUNCHER_SOCKET);
+}
+export const headlessBrokerHost = {
+    async launch(nodeId, inv, opts) {
+        assertGranteeRunsHere((await getNode(nodeId))?.grantee);
+        if ((await getNode(nodeId))?.isolated === true && !isolatedBrokerLauncherAvailable()) {
+            throw new Error('isolated broker requires the Linux root launcher');
+        }
+        // Fast-fail known launch errors before we detach a broker process.
+        await preflightBrokerLaunch(nodeId, inv, opts.cwd, opts.launchJson);
+        // Resolve the fleet BEFORE opening any handle: an unbound-fleet launch must
+        // fail fast with nothing to clean up (design D-2 — broker launches happen
+        // only inside crtrd, or a test harness that explicitly bound a fleet).
+        const fleet = boundFleet();
+        // The ledger is the ONE admission gate for a broker process: every launch
+        // path (revive, spawn, recycle, reset) funnels through here, so claiming
+        // the slot before anything is opened — and giving it back on any path that
+        // does not end in a registered handle — is what makes the cap real rather
+        // than advisory. A caller that cannot proceed without a slot sees this
+        // typed refusal; a caller that can wait catches it and freezes instead.
+        if (!await fleet.reserveSlot(nodeId)) {
+            throw brokerCapReached(brokerThresholdsForDaemon().automaticReviveCap, await fleet.occupancy());
+        }
+        let logFd = null;
+        let child;
+        let registered = false;
+        try {
+            // Redirect the detached broker's stdout+stderr to a per-node log under the
+            // node's existing job/ dir. It retains arbitrary engine/process residue and
+            // failed-canonical fatal fallback output. Append-mode preserves crash-revive history.
+            const logDir = jobDir(nodeId);
+            mkdirSync(logDir, { recursive: true });
+            logFd = openSync(join(logDir, 'broker.log'), 'a');
+            // 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 = { ...await 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;
+                // The same seam names the test lane's Postgres: a broker reads the person's model rows from the database, and without
+                // the lane's URL it would look for the production cluster's socket.
+                const testDatabase = inv.env['CRTR_TEST_PG_URL'] ?? process.env['CRTR_TEST_PG_URL'];
+                if (testDatabase !== undefined)
+                    childEnv['CRTR_TEST_PG_URL'] = testDatabase;
+            }
+            if (eventSource() === undefined)
+                bindBrokerEventSource(nodeId);
+            // `--canvas-home` declares broker ownership in argv so the daemon's
+            // startup epoch census can match its own canvas' brokers exactly (crtrd's
+            // brokerCommandDeclaresCanvasHome) instead of inferring from install
+            // paths; `--epoch` stamps WHICH daemon epoch launched it, so the next
+            // daemon's census reaps every prior-epoch broker without adoption (D-8).
+            // Both precede the node id: the node id is by contract the FINAL argv
+            // token (both broker-cli and the ps census parse it that way).
+            const runId = (await getNode(nodeId))?.run_id;
+            if (runId) {
+                const root = await getNode(runId);
+                if (!root || root.deleting_at)
+                    throw new Error('run is deleting');
+            }
+            const executionId = inv.env['CRTR_EXECUTION_ID'];
+            if (!executionId)
+                throw new Error('broker launch has no execution id');
+            const nodeToken = await withCanvasWrite((db) => mintNodeToken(db, executionId, nodeId, new Date().toISOString()));
+            const sandboxed = isolatedBrokerLauncherAvailable();
+            if ((await getNode(nodeId))?.isolated === true && !sandboxed) {
+                throw new Error('isolated broker requires the Linux root launcher');
+            }
+            if (process.platform === 'linux' && process.env['CRTR_LAUNCHER_SOCKET'] && !sandboxed) {
+                throw new Error('root launcher socket is unavailable; refusing an unsandboxed broker');
+            }
+            if (sandboxed) {
+                const row = await getNode(nodeId);
+                if (!row)
+                    throw new Error(`missing node ${nodeId}`);
+                const app = row.grantee ?? 'app:terminal';
+                // Backstop for launches that did not come through spawn or revive (recycle, reset): the caller's own admission
+                // left a ticket, which makes this admit; the memo is skipped so it cannot hide that ticket.
+                const memory = await admitBrokerMemory(nodeId, { useMemo: false });
+                if (memory.verdict === 'denied')
+                    throw appMemoryFull(memory);
+                if (memory.verdict === 'too_small')
+                    throw appMemoryTooSmall(memory);
+                const space = await ensureAppSpace(app);
+                Object.assign(childEnv, sandboxCacheEnv(app));
+                const owner = { uid: process.getuid(), gid: space.gid };
+                const runDir = nodeRunDir(nodeId);
+                for (const [root, path] of [[appSpace(app).nodes, nodeAgentDir(nodeId, app)], [appSpace(app).nodes, contextDir(nodeId, app)], [runDir, nodeRunJobDir(nodeId)]]) {
+                    withDirBeneath(root, path, () => undefined, true);
+                    setModeBeneath(root, path, 0o2770, owner);
+                }
+                setModeBeneath(runDir, join(runDir, 'broker-launch.json'), 0o640, owner);
+                if (existsBeneath(runDir, scopesFilePath(nodeId)))
+                    setModeBeneath(runDir, scopesFilePath(nodeId), 0o640, owner);
+                const promptPath = join(runDir, 'system-prompt.md');
+                if (existsBeneath(runDir, promptPath))
+                    setModeBeneath(runDir, promptPath, 0o660, owner);
+                // The daemon wrote these as crtrd:crtrd (umask 007); the broker, a different uid whose
+                // only group is crtr-data, must read them or it never declares `submit_result`.
+                for (const shared of ['output-schema.json', 'situational-context.md']) {
+                    const sharedPath = join(runDir, shared);
+                    if (existsBeneath(runDir, sharedPath))
+                        setModeBeneath(runDir, sharedPath, 0o660, owner);
+                }
+                // A node of an isolated run gets its own home inside its node folder (Silas, 2026-09-30).
+                const isolatedHome = row.isolated === true;
+                const home = nodeHome(nodeId, app, isolatedHome);
+                if (isolatedHome) {
+                    withDirBeneath(appSpace(app).nodes, home, () => undefined, true);
+                    setModeBeneath(appSpace(app).nodes, home, 0o2770, owner);
+                    childEnv['HOME'] = home;
+                    childEnv['PI_CODING_AGENT_DIR'] = join(home, '.pi', 'agent');
+                }
+                const agentDir = join(home, '.pi', 'agent');
+                withDirBeneath(home, agentDir, () => undefined, true);
+                writeBrokerModels(home, agentDir);
+                const settingsPath = join(agentDir, 'settings.json');
+                const extensionPackage = join(dirname(resolveBrokerEntry()), '../../builtin-pi-packages/pi-crtr-extensions');
+                writeFileBeneath(home, settingsPath, `${JSON.stringify({ packages: [extensionPackage] })}\n`, { atomic: true, mode: 0o660 });
+                setModeBeneath(home, settingsPath, 0o660);
+                const tokenPath = join(nodeRunDir(nodeId), `token-${executionId}`);
+                const tokenFd = openSync(tokenPath, 'wx+', 0o600);
+                unlinkSync(tokenPath);
+                writeSync(tokenFd, nodeToken);
+                // A separate read descriptor of the unlinked file starts at byte zero.
+                // The second serves the one relaunch a grant sync during launch can force.
+                const readFds = [openSync(`/proc/self/fd/${tokenFd}`, 'r'), openSync(`/proc/self/fd/${tokenFd}`, 'r')];
+                closeSync(tokenFd);
+                const launchNode = { nodeId, app, sub: row.sub ?? personId(), grantId: row.grant_id ?? null,
+                    scopes: row.scopes ?? null, isolated: row.isolated === true,
+                    ...(row.isolated === true ? { cwd: row.cwd } : {}),
+                    command: [process.execPath, resolveBrokerEntry(), '--canvas-home', crtrHome(), '--epoch', fleet.epoch(), nodeId],
+                    env: Object.fromEntries(Object.entries({ ...childEnv,
+                        ...(row.isolated === true ? { PWD: row.cwd } : {}),
+                    }).filter((entry) => entry[1] !== undefined)),
+                    auditMissing: (source) => emitEvent({ level: 'warn', event: 'broker.mount.missing', node_id: nodeId, fields: { source } }),
+                };
+                try {
+                    let launched;
+                    for (const readFd of readFds) {
+                        const generation = await grantsGeneration();
+                        const spec = await compileLaunch(launchNode);
+                        spec.broker = true;
+                        const reply = await launcherRequest({ operation: 'launch', spec }, [readFd]);
+                        if (!('pid' in reply))
+                            throw new Error('launcher did not return a pid');
+                        // A sync that committed while this launch was compiled or started may
+                        // have revoked a mount the spec holds; the sweep may already have run.
+                        if (await grantsGeneration() === generation || await launchStillGranted(launchNode, spec)) {
+                            launched = reply.pid;
+                            break;
+                        }
+                        emitEvent({ level: 'info', event: 'broker.launch.regranted', node_id: nodeId, fields: { pid: reply.pid } });
+                        await launcherRequest({ operation: 'stop', pid: reply.pid, signal: 'SIGKILL' }).catch(() => undefined);
+                    }
+                    if (launched === undefined)
+                        throw new Error('grant changed during every launch attempt');
+                    const pid = launched;
+                    const launchedAt = Date.now();
+                    const exited = new Promise(resolve => {
+                        const poll = setInterval(() => {
+                            if (isPidAlive(pid))
+                                return;
+                            clearInterval(poll);
+                            // The launcher saw the sandbox end and read its cgroup's memory.events.
+                            void launcherRequest({ operation: 'exit.status', pid }).then(reply => 'oomKilled' in reply ? { oomKilled: reply.oomKilled, code: reply.code ?? null, signal: reply.signal ?? null } : { oomKilled: false, code: null, signal: null }, () => ({ oomKilled: false, code: null, signal: null })).then(({ oomKilled, code, signal }) => {
+                                emitEvent({ level: oomKilled || code !== 0 ? 'warn' : 'info', event: 'broker.exited', node_id: nodeId, fields: { pid, code, signal, uptime_ms: Date.now() - launchedAt, oom_killed: oomKilled } });
+                                resolve({ code, signal, ...(oomKilled ? { oomKilled: true } : {}) });
+                            });
+                        }, 250);
+                        poll.unref();
+                    });
+                    closeSync(logFd);
+                    logFd = null;
+                    const handle = { pid, exited };
+                    fleet.register(nodeId, handle);
+                    registered = true;
+                    void exited.then(async (status) => await fleet.onChildExit(nodeId, status, executionId));
+                    return handle;
+                }
+                finally {
+                    for (const fd of readFds)
+                        closeSync(fd);
+                }
+            }
+            const brokerExec = await hostExecPathFresh();
+            const spawned = spawn(brokerExec, [resolveBrokerEntry(), '--canvas-home', crtrHome(), '--epoch', fleet.epoch(), nodeId], {
+                cwd: opts.cwd,
+                detached: true,
+                stdio: ['ignore', logFd, logFd, 'pipe'],
+                env: childEnv,
+            });
+            child = spawned;
+            const tokenPipe = spawned.stdio[3];
+            if (!tokenPipe || !('end' in tokenPipe))
+                throw new Error('broker token pipe did not open');
+            tokenPipe.on('error', (error) => emitEvent({ event: 'broker.token_pipe.failed', level: 'error', node_id: nodeId, error }));
+            tokenPipe.end(nodeToken);
+            // The child holds its own dup of the fd; release the parent's copy so the
+            // launching process (CLI or daemon) never leaks it.
+            closeSync(logFd);
+            logFd = null;
+            // ONE seam for every launch path (revive/spawn/recycle/reset): record the
+            // child's real exit status as a canonical event. Readiness waits consume
+            // `exited` for fail-fast and then discard it, so before this a broker that
+            // was SIGKILLed out from under crouter left NO trace anywhere — an external
+            // kill was indistinguishable from a silent early return, and post-mortems
+            // were unprovable (see the 2026-07-27 "brokers die at startup" RCA).
+            // Emitted through the ordinary bound source: in the daemon (the process
+            // that actually launches brokers) that is the daemon stream carrying
+            // `node_id`, which is how every other daemon-observed broker event
+            // (broker.wedge.detected, broker.yield_stall.*) is recorded and how a
+            // node-scoped log query finds it. The node's own job/log.jsonl is the
+            // BROKER's stream — the reader rejects any non-broker-component line there
+            // (events/read.ts descriptorMatches) — so the daemon must not write into
+            // it. A process already bound to this node's broker source (in-process
+            // revive) naturally lands there instead.
+            const launchedAt = Date.now();
+            const exited = new Promise((resolve) => {
+                let settled = false;
+                const finish = (state) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    resolve(state);
+                };
+                spawned.once('exit', (code, signal) => {
+                    emitEvent({
+                        level: code === 0 ? 'info' : 'warn',
+                        event: 'broker.exited',
+                        node_id: nodeId,
+                        fields: { code, signal, uptime_ms: Date.now() - launchedAt },
+                    });
+                    finish({ code, signal });
+                });
+                spawned.once('error', (error) => {
+                    emitEvent({
+                        level: 'error',
+                        event: 'broker.launch.failed',
+                        node_id: nodeId,
+                        error,
+                        fields: { uptime_ms: Date.now() - launchedAt },
+                    });
+                    finish({ code: null, signal: null });
+                });
+            });
+            spawned.unref();
+            const handle = { pid: spawned.pid ?? null, exited };
+            // Register the live handle synchronously — the fleet entry IS the node's
+            // liveness from here on, and its real `exit` event (never a pid probe)
+            // drives dead-node policy. A null pid (spawn itself failed) registers
+            // nothing: the `exited` promise resolves via the 'error' event and the
+            // caller's own null-pid check surfaces the failure.
+            if (handle.pid !== null) {
+                fleet.register(nodeId, handle);
+                registered = true;
+                void exited.then(async (status) => await fleet.onChildExit(nodeId, status, executionId));
+            }
+            return handle;
+        }
+        catch (error) {
+            if (!registered && child?.pid != null) {
+                try {
+                    child.kill('SIGTERM');
+                }
+                catch { /* no fleet handle exists to tear down */ }
+            }
+            throw error;
+        }
+        finally {
+            if (!registered)
+                fleet.releaseReservation(nodeId);
+            if (logFd !== null)
+                closeSync(logFd);
+        }
+    },
+    async isAlive(node) {
+        return isPidAlive((typeof node === 'string' ? await getNode(node) : node)?.pi_pid);
+    },
+    async teardown(nodeId, opts = {}) {
+        try {
+            return runPreparedBrokerTeardown(await prepareBrokerTeardown(nodeId, opts));
+        }
+        catch (error) {
+            return Promise.resolve({
+                confirmed: false,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
+    },
+    async signal(nodeId, sig) {
+        const pid = (await getNode(nodeId))?.pi_pid;
+        if (pid != null) {
+            try {
+                process.kill(pid, sig);
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    },
+};