@north-light/crouter 0.3.318 → 0.3.320

package/dist/core/runtime/host.js

@@ -1,457 +1 @@
-// 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 { spawn } from 'node:child_process';
-import { mkdirSync, writeFileSync, readFileSync, existsSync, unlinkSync, openSync, closeSync } from 'node:fs';
-import { dirname, join, resolve, isAbsolute } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { connect } from 'node:net';
-import { getNode } from '../canvas/index.js';
-import { crtrHome, nodeDir, jobDir, viewSocketPath } from '../canvas/paths.js';
-import { encodeFrame } from './broker-protocol.js';
-import { buildBrokerEnv } from './spawn-env.js';
-import { hostExecPath } from './branded-host.js';
-import { isPidAlive, killProcessTreePids, isAnyPidAlive, captureTeardownSnapshot } from '../canvas/pid.js';
-import { assertMandatoryCanvasExtensions } from './canvas-extensions.js';
-import { boundFleet, brokerCapReached, brokerThresholdsForDaemon } from './fleet.js';
-import { emitEvent } from '../events/emit.js';
-import { bindBrokerEventSource, eventSource } from '../events/source.js';
-import { envBrokerEngine } from '../../shared/env.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';
-/** 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);
-}
-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);
-    if (!existsSync(sessionPath)) {
-        const label = flag === '--session' ? 'session file' : 'fork source';
-        throw new Error(`[broker] refusing to launch ${nodeId}: launch recipe references missing ${label} '${value}' (${sessionPath})`);
-    }
-}
-/** 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 function preflightBrokerLaunch(nodeId, inv, cwd) {
-    const dir = nodeDir(nodeId);
-    mkdirSync(dir, { recursive: true });
-    const launchPath = join(dir, 'broker-launch.json');
-    writeFileSync(launchPath, JSON.stringify(inv));
-    const raw = readFileSync(launchPath, '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;
-        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. */
-function prepareBrokerTeardown(nodeId, opts) {
-    const node = 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,
-        sockPath: viewSocketPath(nodeId),
-    };
-}
-async function runPreparedBrokerTeardown(prepared) {
-    // 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 {
-                if (existsSync(prepared.sockPath))
-                    unlinkSync(prepared.sockPath);
-            }
-            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 = connect(prepared.sockPath);
-        sock.once('error', () => {
-            if (connected)
-                return;
-            cleanupSocket();
-            finish(false);
-        });
-        sock.once('connect', () => {
-            connected = true;
-            try {
-                sock.write(encodeFrame({ type: 'shutdown' }));
-            }
-            catch {
-                /* the broker may have raced us to exit */
-            }
-            sock.end();
-            cleanupSocket();
-            finish(true);
-        });
-    });
-}
-const requestedTeardowns = new Map();
-/** Queue broker teardown after the close response settles. Completion includes
- * any post-teardown work, which lets the daemon drain it during shutdown. */
-export function requestBrokerTeardown(nodeId, opts = {}, after) {
-    const existing = requestedTeardowns.get(nodeId);
-    if (existing !== undefined) {
-        if (after !== undefined)
-            existing.after.push(after);
-        return existing.completion;
-    }
-    let resolve;
-    const completion = new Promise((done) => { resolve = done; });
-    const request = { completion, resolve, after: after === undefined ? [] : [after] };
-    requestedTeardowns.set(nodeId, request);
-    let prepared;
-    try {
-        prepared = prepareBrokerTeardown(nodeId, opts);
-    }
-    catch (error) {
-        const failure = { confirmed: false, error: error instanceof Error ? error : new Error(String(error)) };
-        requestedTeardowns.delete(nodeId);
-        emitEvent({ level: 'error', event: 'broker.teardown.unconfirmed', node_id: nodeId, error: failure.error });
-        request.resolve(failure);
-        return completion;
-    }
-    setImmediate(() => {
-        requestedTeardowns.delete(nodeId);
-        void runPreparedBrokerTeardown(prepared).then(async (result) => {
-            if (result.confirmed) {
-                for (const callback of request.after) {
-                    try {
-                        await callback();
-                    }
-                    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 });
-            }
-            request.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 });
-            request.resolve(failure);
-        });
-    });
-    return completion;
-}
-export const headlessBrokerHost = {
-    launch(nodeId, inv, opts) {
-        // Fast-fail known launch errors before we detach a broker process.
-        preflightBrokerLaunch(nodeId, inv, opts.cwd);
-        // 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 (!fleet.reserveSlot(nodeId)) {
-            throw brokerCapReached(brokerThresholdsForDaemon().automaticReviveCap, fleet.size());
-        }
-        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 = { ...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;
-            }
-            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 spawned = spawn(hostExecPath(), [resolveBrokerEntry(), '--canvas-home', crtrHome(), '--epoch', fleet.epoch(), nodeId], {
-                cwd: opts.cwd,
-                detached: true,
-                stdio: ['ignore', logFd, logFd],
-                env: childEnv,
-            });
-            child = spawned;
-            // 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((status) => fleet.onChildExit(nodeId, status));
-            }
-            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);
-        }
-    },
-    isAlive(node) {
-        return isPidAlive((typeof node === 'string' ? getNode(node) : node)?.pi_pid);
-    },
-    teardown(nodeId, opts = {}) {
-        try {
-            return runPreparedBrokerTeardown(prepareBrokerTeardown(nodeId, opts));
-        }
-        catch (error) {
-            return Promise.resolve({
-                confirmed: false,
-                error: error instanceof Error ? error : new Error(String(error)),
-            });
-        }
-    },
-    signal(nodeId, sig) {
-        const pid = getNode(nodeId)?.pi_pid;
-        if (pid != null) {
-            try {
-                process.kill(pid, sig);
-            }
-            catch {
-                /* already gone */
-            }
-        }
-    },
-};
+var A=Object.defineProperty;var a=(e,t)=>A(e,"name",{value:t,configurable:!0});import{spawn as G}from"node:child_process";import{mkdirSync as R,writeFileSync as j,readFileSync as C,existsSync as k,unlinkSync as F,openSync as K,closeSync as T}from"node:fs";import{dirname as M,join as g,resolve as W,isAbsolute as q}from"node:path";import{fileURLToPath as O}from"node:url";import{connect as H}from"node:net";import{getNode as _}from"../canvas/index.js";import{crtrHome as U,nodeDir as J,jobDir as z,viewSocketPath as Q}from"../canvas/paths.js";import{encodeFrame as V}from"./broker-protocol.js";import{buildBrokerEnv as X}from"./spawn-env.js";import{hostExecPath as Y}from"./branded-host.js";import{isPidAlive as Z,killProcessTreePids as N,isAnyPidAlive as I,captureTeardownSnapshot as ee}from"../canvas/pid.js";import{assertMandatoryCanvasExtensions as re}from"./canvas-extensions.js";import{boundFleet as ne,brokerCapReached as te,brokerThresholdsForDaemon as oe}from"./fleet.js";import{emitEvent as m}from"../events/emit.js";import{bindBrokerEventSource as ie,eventSource as se}from"../events/source.js";import{envBrokerEngine as ce}from"../../shared/env.js";function x(){const e=M(O(import.meta.url));return g(e,"broker-cli.js")}a(x,"resolveBrokerEntry");const ae="@earendil-works/pi-coding-agent";function B(e){return e.env.CRTR_BROKER_ENGINE??ce()}a(B,"resolveEngineSpec");function D(e){return e.includes("/")||e.endsWith(".jsonl")}a(D,"isPlainLaunchSessionPath");function le(e,t){return q(e)?e:W(t,e)}a(le,"resolvePlainLaunchPath");function fe(e,t,r,n){if(r==="--session"&&!D(n))throw new Error(`[broker] refusing to launch ${e}: launch recipe passes bare --session id '${n}' \u2014 the broker fatally rejects bare ids; pass the .jsonl path instead.`);if(!D(n))return;const o=le(n,t);if(!k(o)){const u=r==="--session"?"session file":"fork source";throw new Error(`[broker] refusing to launch ${e}: launch recipe references missing ${u} '${n}' (${o})`)}}a(fe,"preflightLaunchSessionArg");function ue(e,t,r){const n=J(e);R(n,{recursive:!0});const o=g(n,"broker-launch.json");j(o,JSON.stringify(t));const u=C(o,"utf8"),l=JSON.parse(u);if(!Array.isArray(l.argv))throw new Error(`[broker] refusing to launch ${e}: broker-launch.json is missing the argv array`);const f=B(t);try{const s=import.meta.resolve(f);if(s.startsWith("file:")&&!k(O(s)))throw new Error(`resolved to missing file ${s}`)}catch(s){throw new Error(`[broker] refusing to launch ${e}: cannot resolve broker engine '${f}' from ${x()} \u2014 ${s.message}`)}const i=l.argv,c=[];for(let s=0;s<i.length;s++){const d=i[s];if(d==="-e"){const p=i[++s];p!==void 0&&c.push(p);continue}if(d!=="--session"&&d!=="--fork")continue;const v=i[++s];v!==void 0&&fe(e,r,d,v)}try{re(c)}catch(s){throw new Error(`[broker] refusing to launch ${e}: ${s.message}`)}}a(ue,"preflightBrokerLaunch");const de=2e3,he=2e3,me=150;async function S(e,t){const r=Date.now()+t;for(;I(e);){const n=r-Date.now();if(n<=0)return!1;await new Promise(o=>setTimeout(o,Math.min(me,n)))}return!0}a(S,"waitForTreeExit");async function pe(e,t,r){return e.length===0?{confirmed:!0}:r&&await S(e,de)?{confirmed:!0}:(N(e,"SIGTERM",t),await S(e,he)?{confirmed:!0}:(N(e,"SIGKILL",t),await S(e,5e3)?{confirmed:!0}:{confirmed:!1,error:new Error(`broker process tree for ${e.join(", ")} remained alive after SIGKILL`)}))}a(pe,"terminateBrokerTree");function $(e,t){const r=_(e),n=r?.pi_pid,o=n!=null?ee(n,r?.pi_pid_identity??null,t.excludePid):null;return o?.reused===!0&&m({level:"warn",event:"broker.teardown.pid_reuse_refused",node_id:e,fields:{recorded_pid:n,expected_identity:r?.pi_pid_identity??null}}),{tree:o?.tree??[],identities:o?.identities??null,sockPath:Q(e)}}a($,"prepareBrokerTeardown");async function L(e){return new Promise(t=>{let r=!1,n=!1;const o=a(i=>{n||(n=!0,t(i))},"settle"),u=a(()=>{try{k(e.sockPath)&&F(e.sockPath)}catch{}},"cleanupSocket"),l=a(i=>{pe(e.tree,e.identities,i).then(o,c=>o({confirmed:!1,error:c instanceof Error?c:new Error(String(c))}))},"finish"),f=H(e.sockPath);f.once("error",()=>{r||(u(),l(!1))}),f.once("connect",()=>{r=!0;try{f.write(V({type:"shutdown"}))}catch{}f.end(),u(),l(!0)})})}a(L,"runPreparedBrokerTeardown");const E=new Map;function $e(e,t={},r){const n=E.get(e);if(n!==void 0)return r!==void 0&&n.after.push(r),n.completion;let o;const u=new Promise(i=>{o=i}),l={completion:u,resolve:o,after:r===void 0?[]:[r]};E.set(e,l);let f;try{f=$(e,t)}catch(i){const c={confirmed:!1,error:i instanceof Error?i:new Error(String(i))};return E.delete(e),m({level:"error",event:"broker.teardown.unconfirmed",node_id:e,error:c.error}),l.resolve(c),u}return setImmediate(()=>{E.delete(e),L(f).then(async i=>{if(i.confirmed)for(const c of l.after)try{await c()}catch(s){m({level:"error",event:"broker.teardown.after_failed",node_id:e,error:s})}else m({level:"error",event:"broker.teardown.unconfirmed",node_id:e,error:i.error});l.resolve(i)},i=>{const c={confirmed:!1,error:i instanceof Error?i:new Error(String(i))};m({level:"error",event:"broker.teardown.unconfirmed",node_id:e,error:c.error}),l.resolve(c)})}),u}a($e,"requestBrokerTeardown");const Le={launch(e,t,r){ue(e,t,r.cwd);const n=ne();if(!n.reserveSlot(e))throw te(oe().automaticReviveCap,n.size());let o=null,u,l=!1;try{const f=z(e);R(f,{recursive:!0}),o=K(g(f,"broker.log"),"a");const i=B(t),c={...X(t),CRTR_BROKER_ENGINE:i};if(i!==ae){const w=t.env.NODE_OPTIONS??process.env.NODE_OPTIONS;w!==void 0&&(c.NODE_OPTIONS=w)}se()===void 0&&ie(e);const s=G(Y(),[x(),"--canvas-home",U(),"--epoch",n.epoch(),e],{cwd:r.cwd,detached:!0,stdio:["ignore",o,o],env:c});u=s,T(o),o=null;const d=Date.now(),v=new Promise(w=>{let y=!1;const b=a(h=>{y||(y=!0,w(h))},"finish");s.once("exit",(h,P)=>{m({level:h===0?"info":"warn",event:"broker.exited",node_id:e,fields:{code:h,signal:P,uptime_ms:Date.now()-d}}),b({code:h,signal:P})}),s.once("error",h=>{m({level:"error",event:"broker.launch.failed",node_id:e,error:h,fields:{uptime_ms:Date.now()-d}}),b({code:null,signal:null})})});s.unref();const p={pid:s.pid??null,exited:v};return p.pid!==null&&(n.register(e,p),l=!0,v.then(w=>n.onChildExit(e,w))),p}catch(f){if(!l&&u?.pid!=null)try{u.kill("SIGTERM")}catch{}throw f}finally{l||n.releaseReservation(e),o!==null&&T(o)}},isAlive(e){return Z((typeof e=="string"?_(e):e)?.pi_pid)},teardown(e,t={}){try{return L($(e,t))}catch(r){return Promise.resolve({confirmed:!1,error:r instanceof Error?r:new Error(String(r))})}},signal(e,t){const r=_(e)?.pi_pid;if(r!=null)try{process.kill(r,t)}catch{}}};export{Le as headlessBrokerHost,ue as preflightBrokerLaunch,$e as requestBrokerTeardown};

package/dist/core/runtime/interactive-deliver.js

@@ -1,51 +1 @@
-// interactive-deliver.ts — one-shot server-client delivery + interrupt against
-// a LIVE node broker over its view.sock. The daemon's interactive REST
-// vocabulary (`POST /v1/nodes/{id}/messages` with `delivery:'interactive'`, and
-// `POST /v1/nodes/{id}/interrupt`) rides these instead of the durable inbox, so
-// a live conversation's send and stop share the broker's ONE serialized frame
-// loop — the same ordering a tmux viewer gets — closing the send/abort race the
-// two-channel inbox path had (send rode the watcher's ~1.8s inject; stop rode a
-// direct abort frame; no shared ordering).
-//
-// Both ride the shared one-shot writable round-trip (broker-request.ts):
-// connect → `hello` as controller → send the correlated frame → await its ack.
-// A connection failure BEFORE establishment surfaces as `BrokerUnreachableError`
-// so the caller can fall back to the durable path.
-import { oneShotControllerRequest } from './broker-request.js';
-/** Deliver `text` to a LIVE node's engine on its serialized frame loop. The
- *  broker routes it itself (idle → prompt, streaming → steer) and acks once
- *  routed; resolves with the route taken. `cards` are rendered runtime-card
- *  envelopes placed ahead of the body inside that same frame handling, and
- *  `origin` is the authorship the broker stamps onto the persisted message —
- *  it rides the same frame as the body it describes. */
-export function deliverLive(nodeId, text, opts = {}) {
-    const cards = opts.cards ?? [];
-    return oneShotControllerRequest({
-        nodeId,
-        what: 'the interactive delivery',
-        ackFor: 'deliver',
-        correlated: true,
-        frame: (id) => ({
-            type: 'deliver',
-            id,
-            text,
-            ...(cards.length > 0 ? { cards: [...cards] } : {}),
-            ...(opts.origin !== undefined ? { origin: opts.origin } : {}),
-        }),
-        result: (detail) => (detail === 'steer' ? 'steer' : 'prompt'),
-    });
-}
-/** Abort whatever a LIVE node's engine is doing (turn or `!` bash). Resolves
- *  once the broker has PROCESSED the abort — which, on the single frame loop,
- *  also implies every earlier-accepted deliver was already routed (so a
- *  just-delivered send cannot start its turn after this resolves un-aborted). */
-export function interruptLive(nodeId) {
-    return oneShotControllerRequest({
-        nodeId,
-        what: 'the interrupt',
-        ackFor: 'abort',
-        correlated: true,
-        frame: (id) => ({ type: 'abort', id }),
-        result: (detail) => (detail === 'turn' || detail === 'bash' ? detail : 'idle'),
-    });
-}
+var u=Object.defineProperty;var e=(t,r)=>u(t,"name",{value:r,configurable:!0});import{oneShotControllerRequest as a}from"./broker-request.js";function l(t,r,i={}){const o=i.cards??[];return a({nodeId:t,what:"the interactive delivery",ackFor:"deliver",correlated:!0,frame:e(n=>({type:"deliver",id:n,text:r,...o.length>0?{cards:[...o]}:{},...i.origin!==void 0?{origin:i.origin}:{}}),"frame"),result:e(n=>n==="steer"?"steer":"prompt","result")})}e(l,"deliverLive");function s(t){return a({nodeId:t,what:"the interrupt",ackFor:"abort",correlated:!0,frame:e(r=>({type:"abort",id:r}),"frame"),result:e(r=>r==="turn"||r==="bash"?r:"idle","result")})}e(s,"interruptLive");export{l as deliverLive,s as interruptLive};

package/dist/core/runtime/invocation.js

@@ -1,10 +0,0 @@
-// The broker-launch recipe shape, alone in a dependency-free module.
-//
-// `launch.ts` builds a PiInvocation and therefore reaches canvas state; the
-// modules that only need to READ the recipe shape (spawn-env, host) must not.
-// A type-only import is erased at compile time, but the shipped broker
-// extensions are gated on their STATIC import graph — the gate cannot tell an
-// erased edge from a live one, so an extension that reaches spawn-env would
-// read as reaching canvas.db through launch.ts. Keeping the interface here
-// makes the graph say what the runtime already does.
-export {};