@north-light/crouter 0.3.154

package/dist/daemon/manage.js

@@ -0,0 +1,389 @@
+// Daemon management helpers — importable without the full command tree.
+//
+// spawnDaemon() is the low-level spawn call shared by `crtr sys daemon start` and
+// ensureDaemon(). ensureDaemon() is the silent "start if not running" front-
+// door helper called by the canvas runtime before spawning child nodes.
+import { spawn, execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { existsSync, lstatSync, mkdirSync, openSync, closeSync } from 'node:fs';
+import { crtrHome } from '../core/canvas/paths.js';
+import { bindDaemonEventSource, eventSource } from '../core/events/source.js';
+import { hostExecPath } from '../core/runtime/branded-host.js';
+// Pulled from the lean db-free pidfile module (NOT crtrd.js, whose module graph
+// reaches openDb) so the CLI daemon front door stays canvas.db-free (plan B-0).
+import { isDaemonRunning, readPidfile, isPidAlive } from './pidfile.js';
+// ---------------------------------------------------------------------------
+// Daemon env sanitization
+// ---------------------------------------------------------------------------
+/** Env keys that must NEVER reach the daemon process. Restarting crtrd is
+ *  overwhelmingly done from inside an agent node's own bash tool (`crtr sys
+ *  daemon stop && start`), which inherits that node's FULL env — its identity
+ *  (`CRTR_NODE_ID`/`CRTR_KIND`/…, the `nodeEnv()` shape in `core/runtime/
+ *  nodes.ts`), its front-door recursion-guard flag, and any pi-engine
+ *  resolution seam a prior test/dev session left exported. The daemon is a
+ *  singleton supervisor, never "a node" itself, so none of this belongs in its
+ *  env regardless of whether today's code happens to read it — and at least one
+ *  of these IS actively read: `host.ts`'s broker-engine resolution falls back to
+ *  `process.env['CRTR_BROKER_ENGINE']` verbatim (nodeEnv() never sets that key,
+ *  so nothing overrides it per child launch), so a daemon that inherits a
+ *  stale/dev override throws inside `headlessBrokerHost.launch()` on EVERY
+ *  relaunch it ever attempts, for its whole lifetime — the 2026-07-06 diagnosis
+ *  root cause behind 19 nodes killed with "failed to relaunch and is now dead". */
+export const DAEMON_ENV_STRIP_KEYS = [
+    // Node identity (nodeEnv() shape) — meaningless for a process supervising
+    // many nodes rather than being one.
+    'CRTR_NODE_ID',
+    'CRTR_KIND',
+    'CRTR_MODE',
+    'CRTR_LIFECYCLE',
+    'CRTR_NODE_CWD',
+    'CRTR_CONTEXT_DIR',
+    'CRTR_CYCLES',
+    'CRTR_PROFILE_ID',
+    'CRTR_PARENT_NODE_ID',
+    // Recursion-guard flag — only meaningful inside a pi engine process.
+    'CRTR_FRONT_DOOR',
+    // Ambient tmux identity of whatever shell first autostarted the daemon. The
+    // daemon is a headless supervisor with no pane of its own, but `spawnNode`
+    // reads `currentTmux()` for a --root's foreground viewer placement; a stale
+    // inherited $TMUX makes that resolve to an arbitrary "current" pane, so a
+    // front-door root (created through crtrd) opens a SECOND viewer window and
+    // focuses it — stealing focus from the front door's own inline attach in the
+    // user's pane.
+    // Strip them so the daemon is truly paneless and leaves root-viewer placement
+    // to the front door. Explicit `-t <target>` tmux ops (focus/window mgmt) are
+    // unaffected — the tmux CLI reaches the server via its default socket.
+    'TMUX',
+    'TMUX_PANE',
+    // Engine-resolution seams NOT overridden per child launch — the proven and
+    // suspected poison vectors.
+    'CRTR_BROKER_ENGINE',
+    'CRTR_PI_BINARY',
+    'CRTR_FAULT_RETRY_PROBE',
+    // Generic Node.js env poisoning (a stray dev/debug flag from the restarting
+    // shell).
+    'NODE_OPTIONS',
+];
+/** A copy of `process.env` with every `DAEMON_ENV_STRIP_KEYS` entry removed.
+ *  Deliberate global config the user actually wants the daemon to see —
+ *  `CRTR_HOME`, `CRTR_SUBTREE`, `CRTR_LOG`, `CRTR_DEBUG`, etc. — passes through
+ *  untouched; only the node-identity/engine-poisoning surface is stripped. */
+export function sanitizedDaemonEnv() {
+    const env = { ...process.env };
+    for (const key of DAEMON_ENV_STRIP_KEYS)
+        delete env[key];
+    return env;
+}
+// ---------------------------------------------------------------------------
+// Entry point resolution
+// ---------------------------------------------------------------------------
+/** Locate the package or generation root from a regular build, the standalone
+ *  attach bundle, or a tsx source checkout. */
+function generationRoot() {
+    for (let current = dirname(fileURLToPath(import.meta.url));; current = dirname(current)) {
+        if (existsSync(join(current, 'bin', 'runtime-generation-manifest.mjs')))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            throw new Error(`cannot locate the crouter generation root from ${import.meta.url}`);
+    }
+}
+/** Resolve crtrd's launch argv through the same selector as `bin/crtrd`. The
+ *  selector may choose an ABI-compatible sibling of `runtime/selected`, but
+ *  never the caller's pinned generation. With no selection, a source checkout
+ *  launches through tsx; every other selection failure remains fatal. */
+async function resolveDaemonLaunch() {
+    const root = generationRoot();
+    const manifestUrl = pathToFileURL(join(root, 'bin', 'runtime-generation-manifest.mjs')).href;
+    const { runtimeHome } = (await import(manifestUrl));
+    try {
+        lstatSync(join(runtimeHome(), 'selected'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        const tsxLoader = pathToFileURL(createRequire(import.meta.url).resolve('tsx/esm')).href;
+        // `crtr-src` maps the package's `#` subpath imports to src/*.ts; without it
+        // a source-checkout launch would silently resolve them into a stale dist/.
+        return ['--conditions', 'crtr-src', '--import', tsxLoader, join(root, 'src', 'daemon', 'crtrd-cli.ts')];
+    }
+    const selectorUrl = pathToFileURL(join(root, 'bin', 'runtime-selector.mjs')).href;
+    const { tryResolveRuntime } = (await import(selectorUrl));
+    const result = tryResolveRuntime('daemon');
+    if (!result.ok) {
+        throw new Error(`cannot resolve the selected runtime generation's daemon entry: ${result.error}`);
+    }
+    return [result.runtime.entryPath];
+}
+// ---------------------------------------------------------------------------
+// Stray-daemon sweep
+// ---------------------------------------------------------------------------
+/** A crtrd declares its owning canvas in argv, so ownership is an exact match
+ *  on this process's canvas home. Untagged daemons retain their own
+ *  supervision and are never counted or killed here. */
+export function daemonCommandDeclaresCanvasHome(command, home) {
+    return command.includes(` --canvas-home ${home} `) || command.endsWith(` --canvas-home ${home}`);
+}
+/** Every crtrd process on this host that declares ownership of this process's
+ *  canvas home, by pid. The `daemon/crtrd` argv segment distinguishes daemons
+ *  from brokers. `ps` is best-effort: failures return no matches, and the
+ *  current process is always excluded. */
+export function findDaemonPids() {
+    let stdout;
+    try {
+        stdout = execFileSync('ps', ['-ax', '-o', 'pid=,command='], { encoding: 'utf8', timeout: 2000 });
+    }
+    catch {
+        return [];
+    }
+    const home = crtrHome();
+    const pids = [];
+    for (const line of stdout.split('\n')) {
+        if (!line.includes('daemon/crtrd'))
+            continue;
+        if (!daemonCommandDeclaresCanvasHome(line, home))
+            continue; // another install/canvas owns it
+        const trimmed = line.trim();
+        const firstSpace = trimmed.indexOf(' ');
+        if (firstSpace < 0)
+            continue;
+        const pid = Number.parseInt(trimmed.slice(0, firstSpace), 10);
+        if (Number.isInteger(pid) && pid !== process.pid)
+            pids.push(pid);
+    }
+    return pids;
+}
+/** SIGTERM (then SIGKILL after a short grace) every crtrd daemon process EXCEPT
+ *  `keepPid`. This is the backstop the pidfile alone cannot provide: a daemon
+ *  that survived a prior stop (ignored SIGTERM, or released its ownership lock
+ *  without exiting) keeps running a supervise loop — reviving brokers and
+ *  contending for canvas state — while never appearing in the pidfile again, so
+ *  `stop`'s single recorded-pid signal can never reach it. Returns the pids it
+ *  reaped. Best-effort throughout: a pid that dies between enumeration and signal
+ *  just no-ops. */
+export function sweepStrayDaemons(keepPid) {
+    const strays = findDaemonPids().filter((pid) => pid !== keepPid);
+    for (const pid of strays) {
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch { /* already gone */ }
+    }
+    if (strays.length === 0)
+        return strays;
+    // Give SIGTERM handlers a beat, then SIGKILL any that ignored it — a stray
+    // daemon that hung its shutdown is exactly the failure mode this exists for.
+    const deadline = Date.now() + 2_000;
+    while (Date.now() < deadline) {
+        if (!strays.some((pid) => isPidAlive(pid)))
+            break;
+        execFileSync('sleep', ['0.1']);
+    }
+    for (const pid of strays) {
+        if (isPidAlive(pid)) {
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch { /* already gone */ }
+        }
+    }
+    return strays;
+}
+// Daemon lifecycle transitions are bounded so callers never claim a state
+// change before the pidfile and process liveness agree.
+//
+// #508: a cold boot right after `install-runtime` (empty module cache, fresh
+// generation, possible pending db migration) can take several seconds to
+// reach writePidfile() — a fixed 5s window produced false "did not become
+// ready" failures on a daemon that was in fact starting up fine. Widened to
+// tolerate that slow-but-valid cold start; a process exit (signal/non-zero
+// code) still fails immediately regardless of this window.
+// Exported so `commands/api-client.ts` can align the CLI-side `CrtrClient`'s
+// cold-start `/healthz` poll window with this authoritative valid-startup bound
+// (issue #508 follow-up) instead of the two windows drifting independently.
+export const DAEMON_VERIFY_WINDOW_MS = 20_000;
+const DAEMON_VERIFY_POLL_MS = 10;
+function sleepMs(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/** Tiny bounded post-spawn guard: wait for the daemon pidfile and live pid to
+ *  appear before reporting success. This catches the "started:true but not yet
+ *  plausibly alive" race without turning startup into a retry loop.
+ *
+ *  One deadline, owner-first polling. A signal or non-zero child exit fails
+ *  immediately. A clean code-0 exit is treated only as a possible ownership-
+ *  claim loser (never readiness on its own): polling continues on the SAME
+ *  deadline for a different live pidfile owner — the winner may publish its
+ *  pidfile deliberately late — and fails at that deadline if none appears. No
+ *  deadline extension and no retry spawn.
+ *
+ *  Returns null when the spawned pid owns the pidfile; returns a different live
+ *  daemon pid when startup lost the race to an already-running daemon. */
+export async function verifyDaemonStartup(pid, timeoutMs = DAEMON_VERIFY_WINDOW_MS, deps = {}) {
+    const read = deps.readPidfile ?? readPidfile;
+    const alive = deps.isPidAlive ?? isPidAlive;
+    const exited = deps.childExited;
+    const sleep = deps.sleepMs ?? sleepMs;
+    const now = deps.now ?? Date.now;
+    const deadline = now() + timeoutMs;
+    while (now() <= deadline) {
+        const owner = read();
+        if (owner !== null && alive(owner))
+            return owner === pid ? null : owner;
+        const exitState = exited?.();
+        if (exitState !== null && exitState !== undefined) {
+            if (exitState.signal !== null) {
+                throw new Error(`daemon ${pid} exited before becoming ready (by ${exitState.signal})`);
+            }
+            if (exitState.code !== 0) {
+                throw new Error(`daemon ${pid} exited before becoming ready (with exit code ${exitState.code ?? '?'})`);
+            }
+            // Clean code-0 exit: a possible ownership-claim loser, not readiness.
+            // Keep polling the same deadline for a different live pidfile owner; the
+            // loop's timeout throw below fires if none appears.
+        }
+        await sleep(DAEMON_VERIFY_POLL_MS);
+    }
+    throw new Error(`daemon ${pid} did not become ready within ${timeoutMs}ms`);
+}
+/** Wait until a signaled daemon has exited and relinquished its pidfile. This
+ *  makes a following start safe to claim the singleton rather than racing its
+ *  previous owner. */
+export async function waitForDaemonExit(pid, timeoutMs = DAEMON_VERIFY_WINDOW_MS, deps = {}) {
+    const read = deps.readPidfile ?? readPidfile;
+    const alive = deps.isPidAlive ?? isPidAlive;
+    const sleep = deps.sleepMs ?? sleepMs;
+    const now = deps.now ?? Date.now;
+    const deadline = now() + timeoutMs;
+    while (now() <= deadline) {
+        if (!alive(pid) && read() !== pid)
+            return;
+        await sleep(DAEMON_VERIFY_POLL_MS);
+    }
+    throw new Error(`daemon ${pid} did not exit and release its pidfile within ${timeoutMs}ms`);
+}
+/** How long a SIGKILL'd daemon gets to actually leave the process table before
+ *  `stopDaemonProcess` gives up. A killed process is reaped by the kernel, so
+ *  this only absorbs scheduling latency (or an uninterruptible wait). */
+const DAEMON_KILL_WINDOW_MS = 2_000;
+/** Stop the RECORDED daemon: SIGTERM, and if it does not exit within the wait
+ *  window, escalate to SIGKILL exactly as `sweepStrayDaemons` does for a stray.
+ *
+ *  The escalation is the point. `stop` used to send SIGTERM, wait, and throw on
+ *  timeout — before ever reaching the stray sweep — so the one daemon `stop` is
+ *  actually aimed at was the only crtrd process exempt from the SIGKILL backstop.
+ *  A daemon whose shutdown hung (or outran the window) then became permanently
+ *  unstoppable from the CLI: every retry re-sent a SIGTERM it was already
+ *  ignoring, and `start` kept refusing as "already running".
+ *
+ *  A SIGKILL'd daemon runs no exit handler, so it leaves its pidfile behind
+ *  pointing at a dead pid. That is a stale record, not an owner: `readPidfile`
+ *  callers gate on `isPidAlive`, and the next `start` overwrites it. So this
+ *  waits on process death alone after a kill, never on pidfile release.
+ *
+ *  Returns how the daemon went down, for a truthful report. */
+export async function stopDaemonProcess(pid, timeoutMs = DAEMON_VERIFY_WINDOW_MS, deps = {}) {
+    const alive = deps.isPidAlive ?? isPidAlive;
+    const sleep = deps.sleepMs ?? sleepMs;
+    const now = deps.now ?? Date.now;
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch { /* already gone */ }
+    try {
+        await waitForDaemonExit(pid, timeoutMs, deps);
+        return 'terminated';
+    }
+    catch {
+        // Ignored or hung SIGTERM — the exact failure the stray sweep already kills for.
+    }
+    try {
+        process.kill(pid, 'SIGKILL');
+    }
+    catch { /* already gone */ }
+    const deadline = now() + DAEMON_KILL_WINDOW_MS;
+    while (now() <= deadline) {
+        if (!alive(pid))
+            return 'killed';
+        await sleep(DAEMON_VERIFY_POLL_MS);
+    }
+    throw new Error(`daemon ${pid} survived both SIGTERM and SIGKILL`);
+}
+/** Spawn crtrd detached. Returns immediately; the child outlives this process.
+ *
+ *  If the daemon is already running, returns {started:false, existing_pid}.
+ *  If spawning fails (e.g. missing dist — run `npm run build` first), throws. */
+export async function spawnDaemon() {
+    if (isDaemonRunning()) {
+        return { started: false, existing_pid: readPidfile() ?? undefined };
+    }
+    // Ensure the canvas home directory exists so the daemon can write its pidfile.
+    mkdirSync(crtrHome(), { recursive: true });
+    // Launch from the crouter-branded host binary so the daemon shows "crouter"
+    // in macOS Full Disk Access, not "node" (see branded-host). NOTE: when crtrd
+    // is launchd-owned, the plist's ProgramArguments must point at the branded
+    // binary too — this path only covers a manual `crtr sys daemon start`.
+    const launchArgs = await resolveDaemonLaunch();
+    // Route stdout+stderr to an append-mode file instead of discarding them
+    // (stdio:'ignore'). This fd is RAW RESIDUE only — third-party/runtime
+    // output the daemon doesn't control, plus the narrow set of authorized raw
+    // `[crtrd] …` bootstrap/fatal lines that by construction predate or escape
+    // canonical event emission (the pre-bind losing-claim line and a cleanup-
+    // fatal write in crtrd.ts): all used to go to /dev/null for any manually-
+    // started daemon, the common case (only a launchd-owned daemon had a
+    // logging plist). Every other daemon diagnostic — including per-node
+    // supervise/relaunch failures — is a canonical `emitEvent` write, not raw
+    // stderr; this file is not where those live. Mirrors host.ts's broker.log
+    // pattern: one fd, both streams, append so a restart keeps history.
+    const errLogPath = join(crtrHome(), 'crtrd.err');
+    const errFd = openSync(errLogPath, 'a');
+    if (eventSource() === undefined)
+        bindDaemonEventSource();
+    // `--canvas-home` declares this daemon's canvas ownership in argv so
+    // findDaemonPids()/sweepStrayDaemons (above) can match its own daemon
+    // exactly instead of scanning the whole machine (#518). crtrd-cli.ts's argv
+    // parsing only looks for `--tcp`, so this extra pair of tokens is inert
+    // there — it exists purely for `ps` visibility.
+    const child = spawn(hostExecPath(), [...launchArgs, '--canvas-home', crtrHome()], {
+        detached: true,
+        stdio: ['ignore', errFd, errFd],
+        env: sanitizedDaemonEnv(),
+    });
+    // The child holds its own dup of the fd; release the parent's copy so the
+    // launching process never leaks it.
+    closeSync(errFd);
+    const pid = child.pid;
+    if (pid === undefined) {
+        throw new Error('daemon spawn did not return a pid');
+    }
+    let exitState = null;
+    child.once('exit', (code, signal) => {
+        exitState = { code, signal };
+    });
+    child.unref();
+    const existingPid = await verifyDaemonStartup(pid, DAEMON_VERIFY_WINDOW_MS, {
+        childExited: () => exitState,
+    });
+    if (existingPid !== null) {
+        return { started: false, existing_pid: existingPid };
+    }
+    return { started: true, pid };
+}
+// ---------------------------------------------------------------------------
+// ensureDaemon — fire-and-forget front-door helper
+// ---------------------------------------------------------------------------
+/** Start the daemon if it is not already running. No-op if already up.
+ *  Silently swallows spawn errors (the canvas still works without the daemon;
+ *  nodes just won't be auto-revived). */
+export function ensureDaemon() {
+    if (!isDaemonRunning()) {
+        void spawnDaemon().catch(() => {
+            // Intentionally silent — a missing dist/daemon/crtrd-cli.js (dev mode,
+            // pre-build) must not break the calling command.
+        });
+    }
+}

package/dist/daemon/pidfile.d.ts

@@ -0,0 +1,8 @@
+import { isPidAlive } from '../core/canvas/pid.js';
+export { isPidAlive };
+/** Absolute path to crtrd's pidfile. `CRTR_PIDFILE` overrides for tests. */
+export declare function pidfilePath(): string;
+/** Read the pid stored in the pidfile, or null if absent / malformed. */
+export declare function readPidfile(): number | null;
+/** True when a crtrd process is already running (pidfile exists + pid alive). */
+export declare function isDaemonRunning(): boolean;

package/dist/daemon/pidfile.js

@@ -0,0 +1,37 @@
+// pidfile.ts — the lean crtrd pidfile + liveness helpers, split out of crtrd.ts
+// so the CLI's daemon front door (`daemon/manage.ts` → `ensureDaemon`) can
+// resolve "is the daemon up?" WITHOUT importing crtrd.ts, whose module graph
+// pulls the entire canvas state store (`core/canvas/index.js` → `openDb`). A
+// `crtr` CLI process asking whether crtrd is running must not, by that question
+// alone, open canvas.db — this module keeps that path fs/process-only.
+//
+// PURITY: Node built-ins + `core/canvas/paths.ts` (pure path builder) + the
+// db-free `core/canvas/pid.ts` liveness probe. Never `openDb` / crtrd.ts / any
+// canvas state accessor. crtrd.ts imports + re-exports these to preserve its
+// historical export surface (tests, `commands/sys/daemon.ts`).
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { crtrHome } from '../core/canvas/paths.js';
+import { isPidAlive } from '../core/canvas/pid.js';
+// Re-exported so `isPidAlive` stays reachable from the daemon layer's public
+// surface (crtrd.ts already re-exports it; callers may reach it either way).
+export { isPidAlive };
+/** Absolute path to crtrd's pidfile. `CRTR_PIDFILE` overrides for tests. */
+export function pidfilePath() {
+    const override = process.env['CRTR_PIDFILE'];
+    return override !== undefined && override !== '' ? override : join(crtrHome(), 'crtrd.pid');
+}
+/** Read the pid stored in the pidfile, or null if absent / malformed. */
+export function readPidfile() {
+    const p = pidfilePath();
+    if (!existsSync(p))
+        return null;
+    const raw = readFileSync(p, 'utf8').trim();
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+/** True when a crtrd process is already running (pidfile exists + pid alive). */
+export function isDaemonRunning() {
+    const pid = readPidfile();
+    return pid !== null && isPidAlive(pid);
+}

package/dist/daemon/supervise-cadence.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_INTERVAL_MS = 2000;

package/dist/daemon/supervise-cadence.js

@@ -0,0 +1,6 @@
+// The single source of truth for the daemon supervise-loop cadence. crtrd's
+// supervise loop runs on this interval; the health/status endpoint echoes it as
+// an informational `tick_interval_ms`. Kept in its own tiny module so both the
+// loop (crtrd.ts) and the API handler (handlers/health.ts) read ONE constant
+// without a crtrd↔handler import cycle.
+export const DEFAULT_INTERVAL_MS = 2000;

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export { reviveNode } from './core/runtime/revive.js';
+export type { ReviveResult } from './core/runtime/revive.js';
+export { closeNode } from './core/runtime/close.js';
+export type { CloseNodeResult } from './core/runtime/close.js';
+export { appendInbox } from './core/feed/inbox.js';
+export type { InboxEntry, InboxTier, InboxKind } from './core/feed/inbox.js';
+export { appendSituationalContext } from './core/runtime/situational-context.js';
+export { getNode, listNodes } from './core/canvas/canvas.js';
+export { nodeDir } from './core/canvas/paths.js';
+export type { NodeMeta, NodeRow, NodeStatus, Lifecycle, Mode, } from './core/canvas/types.js';
+export { ticketCountsForNodes, ticketsAcrossCanvas } from './core/canvas/attention.js';
+export type { TicketEntry } from './core/canvas/attention.js';
+export { readTelemetry, readContextTokens } from './core/canvas/telemetry.js';
+export type { Telemetry } from './core/canvas/telemetry.js';
+export { BrokerClient, BrokerUnavailableError } from './core/broker-client/index.js';
+export { encodeFrame, FrameDecoder, FrameOverflowError, CLIENT_READ_CAPS, BROKER_READ_CAPS, } from './core/runtime/broker-protocol.js';
+export type { FrameDecoderCaps, BrokerSnapshot, ClientRole, WelcomeFrame, AckFrame, ErrorFrame, ExtensionUIRequestFrame, BrokerToClient, HelloFrame, PromptFrame, SteerFrame, FollowUpFrame, AbortFrame, ByeFrame, ShutdownFrame, SetModelFrame, CycleModelFrame, SetThinkingLevelFrame, SetAutoRetryFrame, SetAutoCompactionFrame, CompactFrame, NewSessionFrame, SwitchSessionFrame, ForkFrame, SetSessionNameFrame, GetCommandsFrame, NavigateTreeFrame, ReloadFrame, ExportFrame, ClientToBroker, RpcExtensionUIRequest, RpcExtensionUIResponse, ExtensionUIResponseFrame, } from './core/runtime/broker-protocol.js';
+export type { SessionStats } from '@earendil-works/pi-coding-agent';
+export { general } from './core/errors.js';
+export type { CrtrError } from './core/errors.js';
+export { nowIso } from './core/fs-utils.js';
+export { validateOperationId, buildEnvelope, operationIdContext, errorClassCodes, serializeEventRecord, errorClassFromError, } from './core/events/index.js';
+export type { BuildEnvelopeInput, ErrorClass, ErrorClassCode, ErrorClassHints, EventComponent, EventEnvelope, EventError, EventField, EventLevel, EventOutcome, OperationId, OperationIdContext, RetryDisposition, } from './core/events/index.js';

package/dist/index.js

@@ -0,0 +1,44 @@
+// @north-light/crouter — the sanctioned library surface (design D1).
+//
+// This barrel is the ONLY supported way to import crouter as a library; the
+// `exports` map gates off deep subpath imports, so consumers depend on exactly
+// the symbols re-exported here — notably the in-tree web client, which reaches
+// the runtime through the `@north-light/crouter/web` seam.
+// Everything below is a stable, server-facing surface: runtime control that
+// keeps the canvas-row ⇄ pi-session lockstep guarantees, read-only canvas/
+// telemetry queries, and the broker socket client + wire protocol. Nothing
+// internal (CLI plumbing, helpers) is exported. This module has no load-time
+// side effects and no circular imports — keep it that way.
+// ── Runtime control ──────────────────────────────────────────────────────
+// Sanctioned launchers/mutators. reviveNode is the ONLY sanctioned launcher of
+// the broker engine; every node is broker-hosted (no host_kind choice). Broker
+// launches are daemon-owned (fleet-bound): spawn verbs are NOT exported here —
+// an out-of-process consumer creates nodes through the /v1 client like every
+// other caller (D-9), because an unbound launch throws by design (D-2).
+export { reviveNode } from './core/runtime/revive.js';
+export { closeNode } from './core/runtime/close.js';
+export { appendInbox } from './core/feed/inbox.js';
+// Hidden ambient "current situation" sidecar (see runtime/situational-context.ts) —
+// upsert-only, narrow surface so an external composer (e.g. Hearth) never needs to
+// learn the storage file itself.
+export { appendSituationalContext } from './core/runtime/situational-context.js';
+// ── Canvas reads ─────────────────────────────────────────────────────────
+export { getNode, listNodes } from './core/canvas/canvas.js';
+export { nodeDir } from './core/canvas/paths.js';
+export { ticketCountsForNodes, ticketsAcrossCanvas } from './core/canvas/attention.js';
+export { readTelemetry, readContextTokens } from './core/canvas/telemetry.js';
+// ── Broker client ────────────────────────────────────────────────────────
+export { BrokerClient, BrokerUnavailableError } from './core/broker-client/index.js';
+// ── Broker wire protocol (codec + frame/protocol types) ──────────────────
+export { encodeFrame, FrameDecoder, FrameOverflowError, CLIENT_READ_CAPS, BROKER_READ_CAPS, } from './core/runtime/broker-protocol.js';
+// ── Utility exports ───────────────────────────────────────────────────────
+// Small side-effect-free helpers consumed by external callers that assemble
+// on top of crtr primitives (e.g. a guest-side process reading crtr's error
+// shape and timestamp convention). Intentionally narrow: only `general` (not
+// `CrtrError`/`notFound`/`usage`/the other error helpers) and `nowIso`.
+export { general } from './core/errors.js';
+export { nowIso } from './core/fs-utils.js';
+// ── Event contract ───────────────────────────────────────────────────────
+// Pure envelope helpers only. Local source binding and canonical append remain
+// internal so package consumers cannot select crouter runtime file paths.
+export { validateOperationId, buildEnvelope, operationIdContext, errorClassCodes, serializeEventRecord, errorClassFromError, } from './core/events/index.js';

package/dist/pi-extensions/__tests__/canvas-bash-valve.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/pi-extensions/__tests__/canvas-bash-valve.test.js

@@ -0,0 +1,31 @@
+// Run with: node --import tsx/esm --test src/pi-extensions/__tests__/canvas-bash-valve.test.ts
+//
+// BUG REGRESSION: After a node cleaned up its merged worktree, the bash tool
+// still spawned commands with that deleted directory as cwd. child_process
+// then failed before bash could run, leaving the node unable to use its shell.
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import { createValveOperations } from '../canvas-bash-valve.js';
+test('bash falls back to home after its worktree cwd was removed', { timeout: 5_000 }, async () => {
+    const root = mkdtempSync(join(tmpdir(), 'crtr-bash-valve-'));
+    const contextDir = join(root, 'context');
+    const removedWorktree = join(root, 'removed-worktree');
+    mkdirSync(contextDir);
+    try {
+        const output = [];
+        const result = await createValveOperations('test-node', contextDir).exec('printf %s "$PWD"', removedWorktree, {
+            onData: (data) => output.push(data),
+        });
+        const text = Buffer.concat(output).toString();
+        assert.equal(result.exitCode, 0);
+        assert.match(text, new RegExp(`working directory no longer exists: ${removedWorktree}`));
+        assert.match(text, new RegExp(`running from ${homedir()}`));
+        assert.match(text, new RegExp(`${homedir()}$`));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});

package/dist/pi-extensions/__tests__/canvas-context-intro.test.d.ts

@@ -0,0 +1 @@
+export {};