@north-light/crouter 0.3.154

package/dist/core/runtime/branded-host.js

@@ -0,0 +1,342 @@
+// branded-host.ts — a crouter-branded copy of the `node` binary, so the
+// long-lived engine processes (brokers + the crtrd daemon) show "crouter" in
+// macOS' TCC / Full Disk Access list instead of the generic "node".
+//
+// WHY a real copied binary (not a symlink, not process.title): macOS keys a
+// Full Disk Access entry on the Mach-O binary's *filename* — not argv[0], not
+// process.title, and symlinks resolve to their realpath. So the ONLY way to show
+// a branded name is to launch the engine from a real Mach-O file whose filename
+// is the brand. We copy the node launcher to `~/.crouter/host/crouter`.
+//
+// WHY self-contained (libnode beside it): a Homebrew node is a small (~70 KB)
+// launcher that dynamically loads `@rpath/libnode.<abi>.dylib` (~70 MB). node's
+// LC_RPATH includes `@loader_path`, so a copy of that dylib placed *beside* the
+// branded binary resolves with no DYLD_* env var (which SIP can strip) and no
+// dependency on the Cellar path surviving — even after a `brew uninstall` of the
+// old keg, the branded copy keeps running. A statically-linked node (nodejs.org)
+// has no separate libnode; we just copy the binary. The remaining absolute
+// `/opt/homebrew/opt/...` deps resolve by their baked-in absolute paths.
+//
+// SELF-HEAL: ensureBrandedHost() rebuilds the copy whenever the live node drifts
+// (a `brew upgrade node` moves realpath(execPath) to a new Cellar version) or the
+// copy is missing. The drift check is a cheap marker compare — no subprocess, no
+// copy — on the happy path.
+import { copyFileSync, mkdirSync, existsSync, readFileSync, writeFileSync, chmodSync, readdirSync, renameSync, realpathSync, unlinkSync, rmSync, statSync, linkSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { CRTR_DIR_NAME } from '../../types.js';
+import { emitEvent } from '../events/emit.js';
+/** The filename the FDA / TCC entry is shown under. */
+const BRANDED_BIN_NAME = 'crouter';
+/** Machine-global host dir. Deliberately NOT under `CRTR_HOME` (tests override
+ *  that to an isolated temp): the branded binary is a per-machine artifact keyed
+ *  to the installed node, shared across every canvas home. */
+export function brandedHostDir() {
+    return join(homedir(), CRTR_DIR_NAME, 'host');
+}
+export function brandedHostBin() {
+    return join(brandedHostDir(), BRANDED_BIN_NAME);
+}
+function markerPath() {
+    return join(brandedHostDir(), '.source.json');
+}
+/** Locate the `libnode.<abi>.dylib` a Homebrew node loads via `@rpath`. node's
+ *  rpaths are `@loader_path` and `@loader_path/../lib`, so check the binary's own
+ *  dir first, then the sibling `lib/`. Returns the absolute path, or null for a
+ *  statically-linked node that has no separate libnode. */
+function findLibnode(nodeBin) {
+    const binDir = dirname(nodeBin);
+    for (const dir of [binDir, join(binDir, '..', 'lib')]) {
+        if (!existsSync(dir))
+            continue;
+        const hit = readdirSync(dir).find((f) => f.startsWith('libnode.') && f.endsWith('.dylib'));
+        if (hit !== undefined)
+            return join(dir, hit);
+    }
+    return null;
+}
+/** Copy `src` → `dst` via a unique temp + atomic rename, so a failed copy
+ * never leaves a half-written artifact. Host-wide concurrency is serialized by
+ * the dedicated reconcile lock below. */
+function atomicCopy(src, dst, mode) {
+    const tmp = `${dst}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+    copyFileSync(src, tmp);
+    if (mode !== undefined)
+        chmodSync(tmp, mode);
+    renameSync(tmp, dst);
+}
+function readMarker(path = markerPath()) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+const HOST_LOCK_TIMEOUT_MS = 30_000;
+const HOST_LOCK_POLL_MS = 25;
+const UNOWNED_LOCK_GRACE_MS = 1_000;
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function reclaimDeadHostLock(lockPath) {
+    let reclaimable = false;
+    try {
+        const owner = JSON.parse(readFileSync(join(lockPath, 'owner.json'), 'utf8'));
+        reclaimable = typeof owner.pid === 'number' && !processIsAlive(owner.pid);
+    }
+    catch {
+        try {
+            reclaimable = Date.now() - statSync(lockPath).mtimeMs > UNOWNED_LOCK_GRACE_MS;
+        }
+        catch {
+            return true;
+        }
+    }
+    if (!reclaimable)
+        return false;
+    const stalePath = `${lockPath}.stale.${process.pid}.${Math.random().toString(36).slice(2)}`;
+    try {
+        renameSync(lockPath, stalePath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return true;
+        return false;
+    }
+    rmSync(stalePath, { recursive: true, force: true });
+    return true;
+}
+/** Serialize reconciliation of the one machine-global host tuple. This lock is
+ * deliberately separate from the immutable runtime-generation install lock. */
+function withBrandedHostLock(run) {
+    const root = join(homedir(), CRTR_DIR_NAME);
+    const lockPath = join(root, 'host.lock');
+    const token = `${process.pid}.${Math.random().toString(36).slice(2)}`;
+    const candidatePath = `${lockPath}.candidate.${token}`;
+    mkdirSync(root, { recursive: true });
+    mkdirSync(candidatePath);
+    writeFileSync(join(candidatePath, 'owner.json'), JSON.stringify({ pid: process.pid, token }));
+    const deadline = Date.now() + HOST_LOCK_TIMEOUT_MS;
+    for (;;) {
+        try {
+            // The owner record and lock become visible together, so another process
+            // can never mistake an in-progress live acquisition for an abandoned lock.
+            renameSync(candidatePath, lockPath);
+            break;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'EEXIST' && code !== 'ENOTEMPTY') {
+                rmSync(candidatePath, { recursive: true, force: true });
+                throw error;
+            }
+            if (reclaimDeadHostLock(lockPath))
+                continue;
+            if (Date.now() > deadline) {
+                rmSync(candidatePath, { recursive: true, force: true });
+                throw new Error(`timed out waiting for branded host lock: ${lockPath}`);
+            }
+            sleepSync(HOST_LOCK_POLL_MS);
+        }
+    }
+    try {
+        return run();
+    }
+    finally {
+        try {
+            const owner = JSON.parse(readFileSync(join(lockPath, 'owner.json'), 'utf8'));
+            if (owner.token === token)
+                rmSync(lockPath, { recursive: true, force: true });
+        }
+        catch {
+            /* A reclaimed/replaced lock is not ours to remove. */
+        }
+        rmSync(candidatePath, { recursive: true, force: true });
+    }
+}
+/** macOS keys FDA grants on the Mach-O cdhash. A real developer identity
+ *  keeps that hash stable across branded-host rebuilds; ad-hoc signing is the
+ *  portable default for machines without a local signing certificate. */
+export function codesignIdentitiesForBrandedHost(opts = {}) {
+    const configured = opts.configured?.trim();
+    if (configured)
+        return [configured];
+    const discovered = opts.discovered?.trim();
+    return [discovered || '-'];
+}
+function discoverCodesignIdentity() {
+    if (process.platform !== 'darwin')
+        return null;
+    const res = spawnSync('security', ['find-identity', '-v', '-p', 'codesigning'], { stdio: ['pipe', 'pipe', 'pipe'] });
+    if (res.status !== 0)
+        return null;
+    const stdout = (res.stdout ?? '').toString();
+    const identities = stdout
+        .split('\n')
+        .map((line) => line.match(/\)\s+[A-Fa-f0-9]{40}\s+"([^"]+)"/)?.[1] ?? null)
+        .filter((identity) => identity !== null);
+    return identities.find((identity) => identity.startsWith('Apple Development:'))
+        ?? identities.find((identity) => identity.startsWith('Developer ID Application:'))
+        ?? identities[0]
+        ?? null;
+}
+function runCodesign(binPath, identity) {
+    const res = spawnSync('codesign', ['-s', identity, '--deep', '--force', binPath], { stdio: ['pipe', 'pipe', 'pipe'] });
+    return { ok: res.status === 0, stderr: (res.stderr ?? '').toString().trim() };
+}
+function signBrandedHost(binPath) {
+    if (process.platform !== 'darwin')
+        return;
+    const identities = codesignIdentitiesForBrandedHost({
+        configured: process.env['CRTR_CODESIGN_IDENTITY'],
+        discovered: discoverCodesignIdentity(),
+    });
+    let lastError = '';
+    for (const identity of identities) {
+        const res = runCodesign(binPath, identity);
+        if (res.ok)
+            return;
+        lastError = res.stderr;
+    }
+    if (lastError && !lastError.includes('valid on disk')) {
+        emitEvent({ event: 'host.codesign.failed', level: 'debug', error: lastError });
+    }
+    throw new Error(`codesign failed for ${binPath}: ${lastError || 'codesign did not exit successfully'}`);
+}
+export function signBrandedHostArtifacts(binPath, libnodePath, sign = signBrandedHost) {
+    if (libnodePath !== null)
+        sign(libnodePath);
+    sign(binPath);
+}
+export function brandedHostWorks(binPath, timeoutMs = 5_000) {
+    try {
+        const res = spawnSync(binPath, ['-e', ''], {
+            stdio: 'ignore',
+            timeout: timeoutMs,
+        });
+        return res.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Ensure the branded host binary exists and matches the live node; return its
+ *  absolute path. Idempotent and self-healing. Throws on a genuine build failure
+ *  (disk full / permissions) — branding is load-bearing for FDA, so a failure is
+ *  surfaced, never silently masked by falling back to `node`. */
+export function ensureBrandedHost() {
+    return withBrandedHostLock(() => {
+        const hostDir = brandedHostDir();
+        const dst = brandedHostBin();
+        const src = realpathSync(process.execPath);
+        // If THIS process is already running as the branded host (the daemon or a
+        // broker spawning a child), don't rebuild from ourselves — we can't see the
+        // real node from here, and the live process proves the copy works. Drift is
+        // healed by the next real-`node` CLI invocation.
+        if (existsSync(dst) && realpathSync(dst) === src)
+            return dst;
+        const marker = readMarker();
+        const libnodeSrc = findLibnode(src);
+        const libnodeName = libnodeSrc !== null ? libnodeSrc.split('/').pop() : null;
+        const tupleExists = (candidate) => existsSync(dst) &&
+            candidate !== null &&
+            candidate.version === 2 &&
+            (candidate.libnode === null || existsSync(join(hostDir, candidate.libnode)));
+        const tupleMatches = (candidate) => tupleExists(candidate) && candidate.source === src && candidate.libnode === libnodeName;
+        if (tupleMatches(marker) && brandedHostWorks(dst))
+            return dst;
+        // Build and validate a complete tuple privately. Failures before publication
+        // leave any previous valid host untouched.
+        mkdirSync(hostDir, { recursive: true });
+        const stageDir = join(hostDir, `.reconcile.${process.pid}.${Math.random().toString(36).slice(2)}`);
+        const backupDir = join(stageDir, 'previous');
+        mkdirSync(stageDir);
+        let publicationStarted = false;
+        const previousTupleIsValid = tupleExists(marker) && brandedHostWorks(dst);
+        try {
+            const stageBin = join(stageDir, BRANDED_BIN_NAME);
+            const stageLibnode = libnodeName !== null ? join(stageDir, libnodeName) : null;
+            if (libnodeSrc !== null && stageLibnode !== null)
+                atomicCopy(libnodeSrc, stageLibnode);
+            atomicCopy(src, stageBin, 0o755);
+            signBrandedHostArtifacts(stageBin, stageLibnode);
+            if (!brandedHostWorks(stageBin)) {
+                throw new Error(`rebuilt branded host failed its startup check: ${stageBin}`);
+            }
+            if (previousTupleIsValid)
+                backupHostTuple(backupDir, dst, marker);
+            publicationStarted = true;
+            if (stageLibnode !== null)
+                renameSync(stageLibnode, join(hostDir, libnodeName));
+            renameSync(stageBin, dst);
+            atomicCopyMarker({ version: 2, source: src, libnode: libnodeName });
+            if (!tupleMatches(readMarker()) || !brandedHostWorks(dst)) {
+                throw new Error(`published branded host tuple failed validation: ${dst}`);
+            }
+            // Cleanup follows successful marker-last publication and validation.
+            if (marker?.libnode != null && marker.libnode !== libnodeName) {
+                try {
+                    unlinkSync(join(hostDir, marker.libnode));
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+            return dst;
+        }
+        catch (error) {
+            if (publicationStarted && previousTupleIsValid)
+                restoreHostTuple(backupDir, dst, marker);
+            throw error;
+        }
+        finally {
+            rmSync(stageDir, { recursive: true, force: true });
+        }
+    });
+}
+function atomicCopyMarker(marker) {
+    const path = markerPath();
+    const tmp = `${path}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+    writeFileSync(tmp, JSON.stringify(marker));
+    renameSync(tmp, path);
+}
+function backupHostTuple(backupDir, binPath, marker) {
+    mkdirSync(backupDir);
+    linkSync(binPath, join(backupDir, BRANDED_BIN_NAME));
+    if (marker.libnode !== null)
+        linkSync(join(brandedHostDir(), marker.libnode), join(backupDir, marker.libnode));
+    writeFileSync(join(backupDir, '.source.json'), JSON.stringify(marker));
+}
+function restoreHostTuple(backupDir, binPath, marker) {
+    if (marker.libnode !== null)
+        renameSync(join(backupDir, marker.libnode), join(brandedHostDir(), marker.libnode));
+    renameSync(join(backupDir, BRANDED_BIN_NAME), binPath);
+    renameSync(join(backupDir, '.source.json'), markerPath());
+    if (!brandedHostWorks(binPath))
+        throw new Error(`failed to restore previous branded host tuple: ${binPath}`);
+}
+/** The path the engine (broker / daemon) should be launched from. On macOS in a
+ * compiled (production) build this is the validated branded host; otherwise —
+ * non-darwin (TCC is macOS-only), source/tsx (dev + the test suite: never copy
+ * 70 MB into the real ~/.crouter), or the explicit `CRTR_BRANDED_HOST=0`
+ * opt-out — it is the live node. */
+export function hostExecPath() {
+    if (process.env['CRTR_BRANDED_HOST'] === '0')
+        return process.execPath;
+    if (process.platform !== 'darwin')
+        return process.execPath;
+    if (import.meta.url.endsWith('.ts'))
+        return process.execPath;
+    return ensureBrandedHost();
+}

package/dist/core/runtime/broker-cli.d.ts

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

package/dist/core/runtime/broker-cli.js

@@ -0,0 +1,81 @@
+// broker-cli.ts — the headless broker's dedicated detached entry (plan T4 /
+// decision §1.13). Spawned directly via `spawn(execPath, [thisFile, nodeId], …)`
+// by HeadlessBrokerHost.launch (T6) — NEVER routed through src/cli.ts, which
+// would run the whole bootstrap chain (auto-update / scope-init / slash-template
+// rewrite) on every broker boot. Mirrors src/daemon/crtrd-cli.ts: parse the one
+// positional arg and hand off; keep this file a thin shim.
+import { isSafeNodeId } from '../canvas/paths.js';
+import { emitEvent } from '../events/emit.js';
+import { mark, timingProc } from '../timing.js';
+// Record this before dynamically importing broker.ts: ESM static imports finish
+// evaluating before module bodies run, so a static broker import would hide its
+// cold import graph from the boot trace. runBroker binds the canonical event
+// source as its own first line and emits the cli_entry/module_loaded startup
+// events from these captured timestamps; this file only validates raw argv
+// defense-in-depth before that module even loads.
+const startupAt = process.hrtime.bigint();
+const startupTs = new Date().toISOString();
+// The node id is by contract the FINAL argv token — the ps-based daemon
+// census parses the same way, and the `--canvas-home <path>` / `--epoch <id>`
+// ownership tags the host inserts before it (host.ts launch) are transparent
+// here.
+const nodeId = process.argv.length > 2 ? process.argv.at(-1) : undefined;
+if (nodeId === undefined || !isSafeNodeId(nodeId)) {
+    process.stderr.write('[broker] usage: broker-cli [--canvas-home <path>] [--epoch <id>] <nodeId>\n');
+    process.exit(1);
+}
+timingProc('broker');
+mark('broker.entry', { node: nodeId });
+const { runBroker, disposeActiveSession } = await import('./broker.js');
+mark('broker.module_loaded');
+// M3 (scout mq5thyli): dispose the live engine before a FATAL exit. The bash tool
+// spawns children `detached` (own pgid); only session.dispose() (→ abortBash /
+// agent.abort → killProcessTree) reaps them. The graceful path (shutdownHandler /
+// SIGTERM → disposeAndExit) already disposes; this routes the crash path —
+// uncaughtException / unhandledRejection / a runBroker reject — through dispose
+// too, so a fatal error never ORPHANS in-flight bash subprocesses. dispose is
+// idempotent + a no-op once the graceful path has run.
+function disposeAndExit(code) {
+    try {
+        disposeActiveSession();
+    }
+    catch {
+        /* dispose must not block the fatal exit */
+    }
+    process.exit(code);
+}
+// Last-resort safety net (review N-4): a stray throw/rejection from the SDK event
+// stream or an extension's async hook would otherwise crash the broker on Node's
+// default handler. One canonical-first helper serves all three fatal origins:
+// it attempts exactly one `broker.runtime.fatal` canonical event, and mirrors a
+// formatted stack to stderr (the host redirects broker stderr to the node's
+// job/broker.log) ONLY when that canonical append returns false or throws —
+// i.e. no broker source could be bound/used, which is the normal case for a
+// pre-bind import/module failure and the fallback for any other append failure.
+function reportFatal(origin, err) {
+    let reported;
+    try {
+        reported = emitEvent({ level: 'error', event: 'broker.runtime.fatal', error: err, fields: { origin } });
+    }
+    catch {
+        reported = false;
+    }
+    if (!reported) {
+        process.stderr.write(`[broker] fatal (${origin}): ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    }
+}
+// The daemon-owned ChildProcess exit lands in the fleet policy lane. Before
+// session_start the sessionless row is a surfaced boot failure (row 8); after
+// session_start the durable session is resumed or cycled from row state.
+process.on('uncaughtException', (err) => {
+    reportFatal('uncaughtException', err);
+    disposeAndExit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    reportFatal('unhandledRejection', reason);
+    disposeAndExit(1);
+});
+runBroker(nodeId, startupAt, startupTs).catch((err) => {
+    reportFatal('run_failure', err);
+    disposeAndExit(1);
+});