@north-light/crouter 0.3.154

package/dist/core/runtime/host.js

@@ -0,0 +1,432 @@
+// 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 } from './fleet.js';
+import { emitEvent } from '../events/emit.js';
+import { bindBrokerEventSource, eventSource } from '../events/source.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'] ?? process.env['CRTR_BROKER_ENGINE'] ?? DEFAULT_BROKER_ENGINE;
+}
+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 (crouter#98 review finding 3). */
+const TEARDOWN_POLL_MS = 150;
+/** Poll `isAlive` every `TEARDOWN_POLL_MS` until it reports dead. If it is
+ *  STILL alive once `timeoutMs` elapses, fire `onTimeout` exactly once (the
+ *  next escalation rung) and keep polling so the caller can confirm that
+ *  rung actually worked — up to `hardCeilingMs` total, after which this gives
+ *  up (an unkillable/D-state descendant is out of scope for this primitive).
+ *
+ *  Deliberately a recursive, NEVER-`.unref()`'d `setTimeout` rather than a
+ *  fixed unref'd wait (crouter#98 review finding 3): most teardown callers
+ *  are short-lived CLI subprocesses (`node lifecycle close`, `canvas prune`)
+ *  that would otherwise exit before an unref'd SIGKILL timer ever fires,
+ *  silently skipping the last-resort rung. Polling (instead of a blind fixed
+ *  wait) is what keeps the happy path cheap despite being ref'd. */
+function pollUntil(isAlive, timeoutMs, onTimeout, hardCeilingMs = timeoutMs + 5_000) {
+    const start = Date.now();
+    let escalated = false;
+    const tick = () => {
+        if (!isAlive())
+            return; // confirmed dead — stop polling
+        const elapsed = Date.now() - start;
+        if (!escalated && elapsed >= timeoutMs) {
+            escalated = true;
+            onTimeout();
+        }
+        if (elapsed >= hardCeilingMs)
+            return; // best-effort exhausted — give up
+        setTimeout(tick, TEARDOWN_POLL_MS);
+    };
+    tick();
+}
+/** Escalate teardown of a broker/tree that did not exit cleanly off the
+ *  graceful `shutdown` frame (or was never reachable at all): SIGTERM the
+ *  whole tree, then — once `BROKER_SIGKILL_GRACE_MS` has elapsed with the tree
+ *  still alive — SIGKILL the whole tree as the last resort.
+ *
+ *  Takes an ALREADY-CAPTURED `tree` (pid list) and `identities` (a
+ *  `captureTeardownSnapshot` identity map over that same list) — both taken
+ *  ONCE by `teardown()` synchronously at its very top, before EITHER
+ *  escalation path (connect-error or post-shutdown-frame) can run, and
+ *  threaded through here unchanged (crouter#98 review finding 1). This
+ *  function must NEVER re-walk the process tree itself: `launch()` spawns the
+ *  broker `detached: true`, so
+ *  signaling the broker's OWN group (the first thing `killProcessTreePids`
+ *  does) typically kills the broker itself almost immediately — and the
+ *  kernel reparents any surviving child away from the broker's pid the
+ *  INSTANT the broker exits, severing the very ppid link a fresh
+ *  `descendantPids` walk depends on. Re-deriving descendants at ANY point
+ *  after the broker may have exited (including a per-rung re-walk here, or a
+ *  poll that re-derives instead of checking this fixed list) would silently
+ *  "lose" a still-alive detached descendant — e.g. the pi bash tool's shell
+ *  child, itself `detached: true` and thus its own group leader, distinct
+ *  from the broker's group, so a plain `kill(-brokerPid)` never reaches it
+ *  either (crouton-labs/crouter#98). `identities` guards each signal against
+ *  PID REUSE across the multi-second escalation window (review finding 3) —
+ *  see `killProcessTreePids`. `null` means the initial `captureTeardownSnapshot`
+ *  probe itself failed (no baseline to compare against) — `killProcessTreePids`
+ *  falls through to its normal unguarded signal path in that case, never
+ *  reading a probe failure as proof the pid is gone or reused. */
+function escalateBrokerTeardown(tree, identities) {
+    killProcessTreePids(tree, 'SIGTERM', identities);
+    pollUntil(() => isAnyPidAlive(tree), BROKER_SIGKILL_GRACE_MS, () => killProcessTreePids(tree, 'SIGKILL', identities));
+}
+export const headlessBrokerHost = {
+    launch(nodeId, inv, opts) {
+        // Fast-fail known launch errors before we detach a broker process.
+        preflightBrokerLaunch(nodeId, inv, opts.cwd);
+        // 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 });
+        const 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);
+        // Resolve the fleet BEFORE spawning: 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();
+        // `--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 child = spawn(hostExecPath(), [resolveBrokerEntry(), '--canvas-home', crtrHome(), '--epoch', fleet.epoch(), nodeId], {
+            cwd: opts.cwd,
+            detached: true,
+            stdio: ['ignore', logFd, logFd],
+            env: childEnv,
+        });
+        // The child holds its own dup of the fd; release the parent's copy so the
+        // launching process (CLI or daemon) never leaks it.
+        closeSync(logFd);
+        // 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);
+            };
+            child.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 });
+            });
+            child.once('error', () => finish({ code: null, signal: null }));
+        });
+        child.unref();
+        const handle = { pid: child.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);
+            void exited.then((status) => fleet.onChildExit(nodeId, status));
+        }
+        return handle;
+    },
+    isAlive(node) {
+        return isPidAlive((typeof node === 'string' ? getNode(node) : node)?.pi_pid);
+    },
+    teardown(nodeId) {
+        // Graceful: connect to view.sock + send a `shutdown` frame → the broker
+        // dispose()s the engine, unlinks the socket, exits 0. Status is already
+        // flipped done/canceled by the caller (crash-safe ordering), so the daemon
+        // won't revive. On connect failure (broker dead/crashed/wedged) fall back
+        // to escalateBrokerTeardown — a tree-wide SIGTERM now, a tree-wide SIGKILL
+        // as the last resort — so no orphaned descendant of a dead/wedged broker
+        // survives the node (crouton-labs/crouter#98) — + unlink the stale socket.
+        //
+        // Capture the broker pid ONCE, synchronously, right here — never re-query
+        // `getNode(nodeId)` inside the async callbacks/timers below. Callers such
+        // as placement.ts's `reapIfEmpty()` call `teardown()` then immediately
+        // `deleteNode()` in the same tick; by the time an async callback fires the
+        // row can already be gone, so a re-query would silently resolve to
+        // `undefined` and skip escalation entirely (crouter#98 review finding 2).
+        const node = getNode(nodeId);
+        const pid = node?.pi_pid;
+        // Snapshot the full descendant TREE (crouter#98 review finding 1) — the
+        // root pid plus every transitive descendant — and a stable identity
+        // fingerprint for every pid in it (review finding 3), BOTH from ONE `ps`
+        // table read (`captureTeardownSnapshot`, final review: closes the small
+        // race between two separate probes), exactly ONCE, right here, while the
+        // broker (if alive) still holds parentage over any detached descendant.
+        // EVERY escalation path below — connect-error AND post-shutdown-frame —
+        // reuses this ONE fixed snapshot; neither may re-walk `ps` by ppid once
+        // the broker might have exited, because the kernel reparents any
+        // surviving child away from `pid` the INSTANT the broker exits, severing
+        // the ppid link a fresh walk depends on — exactly the reparenting hazard
+        // this fix closes. (If the broker is ALREADY dead when `teardown()`
+        // starts, its detached descendants were already reparented before we ever
+        // got here — unrecoverable by ppid, and out of scope: the #98 repro is
+        // the wedged-but-ALIVE broker, which this covers.)
+        //
+        // `node?.pi_pid_identity` is the LAUNCH-time baseline `recordPid` captured
+        // the instant this broker was spawned/bound (final review, Fix 1): if
+        // `pid` has ALREADY been recycled for an unrelated process before
+        // teardown ever ran — the pid-reuse hazard this guard exists for — the
+        // snapshot's `reused: true` comes back with an EMPTY tree, so nothing
+        // below ever signals the stranger (or walks its process tree looking for
+        // "descendants", which would be the stranger's children, not ours).
+        const snapshot = pid != null ? captureTeardownSnapshot(pid, node?.pi_pid_identity ?? null) : 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,
+                },
+            });
+        }
+        const tree = snapshot?.tree ?? [];
+        const identities = snapshot?.identities ?? null;
+        const sockPath = viewSocketPath(nodeId);
+        const cleanupSocket = () => {
+            try {
+                if (existsSync(sockPath))
+                    unlinkSync(sockPath);
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+        };
+        const sock = connect(sockPath);
+        let connected = false;
+        sock.on('error', () => {
+            // A post-connect error (broker exiting after we sent shutdown) is benign
+            // and swallowed; only a connect failure triggers the escalation fallback.
+            if (connected)
+                return;
+            if (tree.length > 0)
+                escalateBrokerTeardown(tree, identities);
+            cleanupSocket();
+        });
+        sock.once('connect', () => {
+            connected = true;
+            try {
+                sock.write(encodeFrame({ type: 'shutdown' }));
+            }
+            catch {
+                /* the broker may have raced us to exit */
+            }
+            sock.end();
+            cleanupSocket();
+            // Bounded exit confirmation: a broker that connects fine but then HANGS
+            // inside session.dispose() (disposeAndExit catches a throw, not a hang)
+            // would leak the process holding the sole .jsonl writer — and any
+            // bash→test→app descendants it spawned along the way (crouter#98). Poll
+            // the whole process TREE (not just the broker's own pid) for up to
+            // `BROKER_SHUTDOWN_GRACE_MS`, UNCONDITIONAL on the broker's own liveness
+            // (crouter#98 review finding 1): a broker that exits cleanly can still
+            // leave a live descendant behind (dispose() partially failed, or never
+            // reached a detached SDK child), which is exactly the shape this
+            // closes. `pollUntil` is ref'd — not `.unref()`'d — so a short-lived
+            // CLI caller stays alive long enough for the SIGKILL rung to actually
+            // fire, while the happy path (tree already dead) still pays only a
+            // couple of poll ticks.
+            //
+            // Checks `isAnyPidAlive(tree)` against the FIXED pre-signal snapshot,
+            // NEVER a fresh `isProcessTreeAlive`/`descendantPids` re-walk (crouter#98
+            // review finding 1, fixed): the broker can exit at any point during this
+            // grace window while leaving a detached descendant alive, and the
+            // instant it does, the kernel reparents that descendant away from `pid`
+            // — a re-walk-by-ppid would then find nothing and silently skip
+            // escalation, even though the descendant is still very much alive. The
+            // fixed `tree` snapshot (taken before the shutdown frame was even sent)
+            // has no such blind spot.
+            if (tree.length > 0) {
+                pollUntil(() => isAnyPidAlive(tree), BROKER_SHUTDOWN_GRACE_MS, () => escalateBrokerTeardown(tree, identities));
+            }
+        });
+    },
+    signal(nodeId, sig) {
+        const pid = getNode(nodeId)?.pi_pid;
+        if (pid != null) {
+            try {
+                process.kill(pid, sig);
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    },
+};

package/dist/core/runtime/interactive-deliver.d.ts

@@ -0,0 +1,15 @@
+/** Which engine call the broker routed a live deliver to (its ack `detail`):
+ *  idle → `prompt`, turn in flight → `steer`. */
+export type LiveDeliverRoute = 'prompt' | 'steer';
+/** What a live abort actually interrupted (its ack `detail`): an in-flight
+ *  agent turn, a running `!` bash command, or nothing (`idle`). */
+export type LiveInterruptOutcome = 'turn' | 'bash' | 'idle';
+/** 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. */
+export declare function deliverLive(nodeId: string, text: string): Promise<LiveDeliverRoute>;
+/** 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 declare function interruptLive(nodeId: string): Promise<LiveInterruptOutcome>;

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

@@ -0,0 +1,41 @@
+// 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. */
+export function deliverLive(nodeId, text) {
+    return oneShotControllerRequest({
+        nodeId,
+        what: 'the interactive delivery',
+        ackFor: 'deliver',
+        correlated: true,
+        frame: (id) => ({ type: 'deliver', id, text }),
+        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'),
+    });
+}

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

@@ -0,0 +1,53 @@
+import { type NodeMeta } from '../canvas/index.js';
+import { type WakeOrigin } from './bearings.js';
+/** The goal file — the prompt/task a node was spawned with, persisted at birth
+ *  so a fresh revive can re-read its mandate. */
+export declare function goalPath(nodeId: string): string;
+export declare function readGoal(nodeId: string): string | null;
+/** Persist the spawning prompt as the node's goal. No-op for an empty prompt
+ *  (e.g. a bare root). Idempotent enough — call once at spawn/boot. */
+export declare function writeGoal(nodeId: string, text: string): void;
+/** Write the goal ONLY if the node has none yet. This is how a bare root (no
+ *  spawn prompt) acquires its mandate: the first real user message becomes the
+ *  goal. Returns true when it wrote one, false when a goal already existed or
+ *  the text was empty. Guarded so a later message never clobbers the mandate. */
+export declare function captureGoalIfAbsent(nodeId: string, text: string): boolean;
+/** Sentinel opening the fresh-revive kickoff message (see buildReviveKickoff).
+ *  The goal-capture extension skips any input starting with this so a kickoff
+ *  prompt is never mistaken for a user's first mandate. */
+export declare const REVIVE_KICKOFF_SENTINEL = "You have been revived fresh after a context refresh";
+/** Injected only when a broker cleanly persisted an aborted in-flight turn
+ * before a daemon restart. The transcript already carries the full picture, so
+ * this is a bare nudge — a longer explanation only destabilizes the resume. */
+export declare const RUNTIME_RESTART_CONTINUATION = "continue";
+/** The yield-message file — a short note `crtr node yield` records for the next
+ *  fresh/cycling revive ("on wake, do X"). It remains durable through failed
+ *  launch attempts and is cleared only when session_start confirms a boot. */
+export declare function yieldMessagePath(nodeId: string): string;
+export declare function writeYieldMessage(nodeId: string, text: string): void;
+/** Read the pending yield message without mutating its confirmation state. */
+export declare function readYieldMessage(nodeId: string): string | null;
+/** Idempotently commit delivery of the yield message after a confirmed boot. */
+export declare function clearYieldMessage(nodeId: string): void;
+/** List the node's context/ dir (filenames, sorted). Empty when absent. */
+export declare function listContextDir(nodeId: string): string[];
+export interface ReviveBearings {
+    /** The one-shot yield note left by the prior self, pending boot confirmation. */
+    yieldMsg: string | null;
+    /** Coalesced digest of unread reports, or null when the feed was empty. The
+     *  cursor now records the last physically covered entry. */
+    unreadDigest: string | null;
+    /** Persona-transition guidance to surface when the node's role was changed
+     *  while it was away (its ack has already been committed), else null. */
+    driftGuidance: string | null;
+}
+/** Capture revive bearings for `meta`: read the pending yield note, advance the
+ *  feed cursor past unread reports, and capture+commit external persona drift.
+ *  Revive paths call it once, then pass the result to the pure kickoff builder. */
+export declare function drainBearings(meta: NodeMeta): ReviveBearings;
+/** Assemble the auto-injected first message for a FRESH revive of `meta` from its
+ *  already-drained `bearings` (see drainBearings) plus pure on-disk reads of the
+ *  node's goal, roadmap, and context dir, framed so the revived node can rebuild
+ *  its bearings in one turn. PURE: no state mutation, so calling it twice yields
+ *  the same string and consumes nothing — drainBearings owns the one-shot reads. */
+export declare function buildReviveKickoff(meta: NodeMeta, bearings: ReviveBearings, wakeReason?: WakeOrigin): string;