@crouter/api 0.3.387 → 0.3.389

package/dist/core/render.js

@@ -0,0 +1,138 @@
+// Default stdout rendering: the result a leaf returns is written FOR the model
+// to act on, not as data to parse. Output is a continuation of the agent's
+// prompt — PLAIN MARKDOWN, no XML wrapper. Scalars list as `- name: value`
+// bullets in output-schema order, prose fields render as paragraphs, and arrays
+// become a count lead-in plus a markdown table (objects) or bullets (scalars).
+// The raw JSON object is still available behind the `--json` global for tooling.
+//
+// A leaf may hand `defineLeaf` a bespoke `render(result)` for instruction-shaped
+// output that leads with the outcome (see `node new`, `push`).
+// Everything else falls through to the schema-driven generic renderer here, so
+// every command obeys the markdown paradigm without a hand-written renderer.
+// `renderError` is the one sanctioned exception: a failure is a different domain
+// from a result, so it keeps its `<error>` block.
+// Field names whose value is prose the agent reads, not a scalar it keys on —
+// these always render as their own paragraph, never as a `- name: value` bullet.
+const PROSE_FIELDS = new Set([
+    'follow_up', 'digest', 'message', 'next', 'result', 'content', 'body', 'guide',
+    'summary', 'note', 'reason', 'detail', 'details', 'hint', 'instruction',
+    'instructions', 'prompt', 'roadmap', 'report', 'answer', 'response', 'text',
+]);
+/** Minimal attribute-value sanitization: values here are controlled (ids,
+ *  statuses, counts), so collapse quotes rather than entity-escape. */
+function attrEsc(s) {
+    return String(s).replace(/"/g, "'").replace(/\n/g, ' ');
+}
+function scalarStr(v) {
+    if (v === null || v === undefined)
+        return '';
+    if (Array.isArray(v))
+        return v.map(scalarStr).join(', ');
+    if (typeof v === 'object')
+        return JSON.stringify(v);
+    return String(v);
+}
+function fencedJson(value) {
+    const json = JSON.stringify(value, null, 2);
+    let fence = '```';
+    while (json.includes(fence))
+        fence += '`';
+    return `${fence}json\n${json}\n${fence}`;
+}
+/** A string field is prose when it is named as such, spans lines, or is long
+ *  enough that it reads as a sentence rather than an identifier. */
+function isProse(name, v) {
+    if (typeof v !== 'string')
+        return false;
+    if (PROSE_FIELDS.has(name))
+        return true;
+    return v.includes('\n') || v.length > 80;
+}
+/** Keep a value safe inside a markdown table cell: pipes would split columns,
+ *  newlines would break the row. */
+function cellEsc(v) {
+    return scalarStr(v).replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+/** An array renders as a count lead-in followed by the collection: a markdown
+ *  table when every element is an object, plain bullets otherwise. */
+function renderArray(name, arr) {
+    if (arr.length === 0)
+        return `0 ${name}.`;
+    const lead = `${arr.length} ${name}:`;
+    const allObjects = arr.every((x) => x !== null && typeof x === 'object' && !Array.isArray(x));
+    if (allObjects) {
+        const rows = arr;
+        const cols = [];
+        for (const r of rows)
+            for (const k of Object.keys(r))
+                if (!cols.includes(k))
+                    cols.push(k);
+        const head = `| ${cols.join(' | ')} |`;
+        const sep = `| ${cols.map(() => '---').join(' | ')} |`;
+        const body = rows.map((r) => `| ${cols.map((c) => cellEsc(r[c])).join(' | ')} |`).join('\n');
+        return `${lead}\n\n${head}\n${sep}\n${body}`;
+    }
+    const items = arr.map((x) => `- ${scalarStr(x)}`).join('\n');
+    return `${lead}\n${items}`;
+}
+/** Schema-driven fallback: turn a result object into agent-ready plain markdown.
+ *  Field order follows the leaf's declared output schema; any extra keys append
+ *  after. Scalars (and nested objects) list as `- name: value` bullets, prose
+ *  fields render as paragraphs, and arrays become a count lead-in plus a table
+ *  or bullets. No root tag — the result is read as a continuation of the prompt. */
+export function renderResult(result, help) {
+    const order = help.output.map((f) => f.name);
+    for (const k of Object.keys(result))
+        if (!order.includes(k))
+            order.push(k);
+    const bullets = [];
+    const proseFields = [];
+    const arrays = [];
+    for (const name of order) {
+        const v = result[name];
+        if (v === undefined || v === null)
+            continue;
+        if (Array.isArray(v)) {
+            arrays.push(renderArray(name, v));
+            continue;
+        }
+        if (isProse(name, v)) {
+            proseFields.push({ name, text: v });
+            continue;
+        }
+        // Scalars and nested objects alike list as a bullet (objects via compact JSON).
+        bullets.push(`- ${name}: ${scalarStr(v)}`);
+    }
+    const parts = [];
+    if (bullets.length > 0)
+        parts.push(bullets.join('\n'));
+    // Label prose only when more than one block would otherwise blur together.
+    const labelProse = proseFields.length > 1;
+    for (const { name, text } of proseFields) {
+        parts.push(labelProse ? `**${name}:** ${text}` : text);
+    }
+    for (const block of arrays)
+        parts.push(block);
+    return parts.join('\n\n');
+}
+/** Render a structured failure as an instruction-shaped block: what broke, what
+ *  was received, and the recovery road sign — the same recovery info the JSON
+ *  payload carries, shaped for the model to act on. */
+export function renderError(p) {
+    const lines = [p.message];
+    if (p.received !== undefined && p.received !== null && p.received !== '') {
+        lines.push(`received: ${scalarStr(p.received)}`);
+    }
+    if (p.field !== undefined)
+        lines.push(`field: ${p.field}`);
+    // Its own labeled line: a transport status is a fact about the call, not about
+    // the value the caller supplied.
+    if (p.http_status !== undefined)
+        lines.push(`http status: ${p.http_status}`);
+    if ('primaryCompleted' in p && p.primaryCompleted === true) {
+        lines.push('primaryCompleted: true');
+        lines.push(`Primary result (the command already completed):\n${fencedJson(p.result)}`);
+    }
+    lines.push(`Next: ${p.next}`);
+    return `<error code="${attrEsc(p.error)}">\n${lines.join('\n')}\n</error>`;
+}

package/dist/core/resolver.d.ts

@@ -0,0 +1,14 @@
+import type { InstalledMarketplace, InstalledPlugin, Scope } from '../types.js';
+export { listInstalledPluginsInRoot } from './installed-plugins.js';
+export declare function listInstalledPlugins(scope: Scope): InstalledPlugin[];
+export declare function listAllPlugins(): InstalledPlugin[];
+export declare function findPluginByName(name: string, scope?: Scope): InstalledPlugin | null;
+export interface ParsedSkillQualifier {
+    scope?: Scope;
+    segments: string[];
+}
+export declare function parseSkillQualifier(raw: string): ParsedSkillQualifier;
+export declare function listInstalledMarketplaces(scope: Exclude<Scope, 'builtin'>): InstalledMarketplace[];
+export declare function listAllMarketplaces(): InstalledMarketplace[];
+export declare function findMarketplaceByName(name: string, scope?: Exclude<Scope, 'builtin'>): InstalledMarketplace | null;
+export declare function scopeRootsLabel(): string;

package/dist/core/resolver.js

@@ -0,0 +1,111 @@
+import { join } from 'node:path';
+import { readConfig } from './config.js';
+import { listDirs, pathExists } from './fs-utils.js';
+import { readMarketplaceManifest } from './manifest.js';
+import { InputError } from './io.js';
+import { marketplacesDir, projectScopeRoot, scopeRoot, userScopeRoot, } from './scope.js';
+// Moved to installed-plugins.ts (a leaf module below config.ts) so
+// `readMergedLaunchConfig` can layer plugin-declared kinds without an import
+// cycle; re-exported here for this module's existing callers.
+export { listInstalledPluginsInRoot } from './installed-plugins.js';
+import { listInstalledPluginsInRoot } from './installed-plugins.js';
+export function listInstalledPlugins(scope) {
+    // The builtin scope has no scopeRoot, so this returns [] — builtin content is
+    // the shipped documents, not plugins.
+    const root = scopeRoot(scope);
+    if (!root)
+        return [];
+    return listInstalledPluginsInRoot(scope, root);
+}
+export function listAllPlugins() {
+    const scopes = [];
+    if (projectScopeRoot())
+        scopes.push('project');
+    scopes.push('user');
+    scopes.push('builtin');
+    return scopes.flatMap(listInstalledPlugins);
+}
+export function findPluginByName(name, scope) {
+    if (scope) {
+        return listInstalledPlugins(scope).find((p) => p.name === name) ?? null;
+    }
+    for (const s of ['project', 'user', 'builtin'].filter((sc) => sc === 'project' ? projectScopeRoot() !== null : true)) {
+        const match = listInstalledPlugins(s).find((p) => p.name === name);
+        if (match)
+            return match;
+    }
+    return null;
+}
+const SCOPE_QUALIFIERS = new Set(['user', 'project']);
+// Accepted identifier forms:
+//   <name>                         — bare name; scope-root first, then plugins
+//   <plugin>/<name>                — explicit plugin (plugin may contain slashes)
+//   <scope>/<name>                 — scope-root in a specific scope
+//   <scope>/<plugin>/<name>        — fully qualified
+export function parseSkillQualifier(raw) {
+    if (raw.includes(':')) {
+        const suggested = raw.replace(/:/g, '/');
+        throw new InputError({
+            error: 'invalid_qualifier',
+            message: "mixed separators ':' and '/' no longer supported; use slashes throughout",
+            received: raw,
+            field: 'name',
+            next: `Use ${suggested}.`,
+        });
+    }
+    const segments = raw.split('/');
+    if (SCOPE_QUALIFIERS.has(segments[0])) {
+        const scope = segments[0];
+        return { scope, segments: segments.slice(1) };
+    }
+    return { segments };
+}
+export function listInstalledMarketplaces(scope) {
+    const dir = marketplacesDir(scope);
+    if (!dir || !pathExists(dir))
+        return [];
+    const cfg = readConfig(scope);
+    const out = [];
+    for (const name of listDirs(dir)) {
+        const root = join(dir, name);
+        const manifest = readMarketplaceManifest(root);
+        if (!manifest)
+            continue;
+        const entry = cfg.marketplaces[name];
+        const url = entry && entry.url !== undefined ? entry.url : '';
+        const ref = entry && entry.ref !== undefined ? entry.ref : 'main';
+        out.push({
+            name,
+            scope,
+            root,
+            manifest,
+            url,
+            ref,
+        });
+    }
+    return out;
+}
+export function listAllMarketplaces() {
+    const scopes = [];
+    if (projectScopeRoot())
+        scopes.push('project');
+    scopes.push('user');
+    return scopes.flatMap(listInstalledMarketplaces);
+}
+export function findMarketplaceByName(name, scope) {
+    if (scope) {
+        return listInstalledMarketplaces(scope).find((m) => m.name === name) ?? null;
+    }
+    for (const s of ['project', 'user']) {
+        if (s === 'project' && !projectScopeRoot())
+            continue;
+        const found = listInstalledMarketplaces(s).find((m) => m.name === name);
+        if (found)
+            return found;
+    }
+    return null;
+}
+export function scopeRootsLabel() {
+    const proj = projectScopeRoot();
+    return proj ? `project=${proj}, user=${userScopeRoot()}` : `user=${userScopeRoot()}`;
+}

package/dist/core/runtime/branded-host.d.ts

@@ -0,0 +1,25 @@
+/** Machine-global host dir in this process owner’s HOME. Only the daemon reconciles it; agents do not install the branded host. 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 declare function brandedHostDir(): string;
+export declare function brandedHostBin(): string;
+/** 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 declare function codesignIdentitiesForBrandedHost(opts?: {
+    configured?: string | null;
+    discovered?: string | null;
+}): string[];
+export declare function signBrandedHostArtifacts(binPath: string, libnodePath: string | null, sign?: (path: string) => void): void;
+export declare function brandedHostWorks(binPath: string, timeoutMs?: number): boolean;
+/** 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 declare function ensureBrandedHost(): string;
+/** 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 declare function hostExecPath(): string;

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

@@ -0,0 +1,264 @@
+// 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, 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';
+import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
+/** The filename the FDA / TCC entry is shown under. */
+const BRANDED_BIN_NAME = 'crouter';
+/** Machine-global host dir in this process owner’s HOME. Only the daemon reconciles it; agents do not install the branded host. 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;
+/** 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');
+    mkdirSync(root, { recursive: true });
+    return withExclusiveDirectoryLock(lockPath, run, {
+        timeoutMs: HOST_LOCK_TIMEOUT_MS,
+        timeoutError: () => new Error(`timed out waiting for branded host lock: ${lockPath}`),
+    });
+}
+/** 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/daemon-ops.d.ts

@@ -0,0 +1,65 @@
+import { type BrokerSignalCachedNode } from '../../../daemon/broker-signals/bus.js';
+import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerParkActivityResultDTO, BrokerParkCompleteRequest, BrokerPersonaAckRequest, BrokerPersonaAckResultDTO, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest, BrokerTelemetryRequest } from '../../../api/dto/broker-ops.js';
+import type { AcknowledgeMailResultDTO, ClaimMailResultDTO, MailReceiptDTO } from '../../../api/dto/mail.js';
+import type { BrokerFaultInputDTO, BrokerFaultRequest, BrokerFaultResultDTO, BrokerProviderRetryRequest, BrokerProviderRetryResultDTO, BrokerTurnRequest, BrokerTurnResultDTO, RecoveryStateDTO } from '../../../api/dto/recovery.js';
+import type { RelaunchRootResultDTO } from '../../../api/dto/lifecycle.js';
+import type { PushReportRequest } from '../../../api/dto/reports.js';
+import type { BackgroundedJobDTO, BackgroundedJobRequest, DeliveryRequest, DeliveryResponse } from '../../../api/dto/delivery.js';
+import type { NodeLogAppendResultDTO, NodeMessageBodyDTO, NodePushedFinalResultDTO, NodeTelemetryRecordRequest } from '../../../api/dto/node-records.js';
+export declare function appendBrokerLog(nodeId: string, record: string): Promise<NodeLogAppendResultDTO>;
+export declare function putBrokerTelemetry(nodeId: string, telemetry: Omit<NodeTelemetryRecordRequest, 'expected_execution_id'>): Promise<void>;
+export declare function putBrokerRecap(nodeId: string, briefing: string): Promise<void>;
+/** The body of a direct message the daemon spilled into this node's records. */
+export declare function readBrokerPassiveMessage(nodeId: string, ref: string): Promise<NodeMessageBodyDTO>;
+export declare function clearBrokerPushedFinal(nodeId: string): Promise<NodePushedFinalResultDTO>;
+export declare function consumeBrokerPushedFinal(nodeId: string): Promise<NodePushedFinalResultDTO>;
+export declare function startBrokerBashJob(nodeId: string, request: {
+    job_id: string;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}): Promise<{
+    pid: number;
+}>;
+/** Record a command the valve just backgrounded as this node's job object. */
+export declare function recordBackgroundedJob(nodeId: string, jobId: string, request: BackgroundedJobRequest): Promise<BackgroundedJobDTO>;
+export declare function stopBrokerBashJob(nodeId: string, jobId: string): Promise<void>;
+export declare function brokerExecutionId(): string;
+export declare function bindBrokerSession(nodeId: string, request: Omit<BrokerSessionBoundRequest, 'executionId'>): Promise<BrokerSessionBoundResultDTO>;
+type BrokerInput<T> = T extends unknown ? Omit<T, 'expected_execution_id'> : never;
+export declare function settleBroker(nodeId: string, request: BrokerInput<BrokerSettleRequest>): Promise<BrokerSettleDirective>;
+export declare function completeBrokerPark(nodeId: string, request: BrokerInput<BrokerParkCompleteRequest>): Promise<BrokerSettleDirective>;
+export declare function recordBrokerParkActivity(nodeId: string): Promise<BrokerParkActivityResultDTO>;
+export declare function recordBrokerTelemetry(nodeId: string, request: Omit<BrokerTelemetryRequest, 'expected_execution_id'>): Promise<void>;
+export declare function claimBrokerMail(nodeId: string, channel: 'wake' | 'passive' | 'deferred_run', reportBodies: Map<string, Promise<string>>): Promise<ClaimMailResultDTO>;
+export declare function acknowledgeBrokerMail(nodeId: string, deliveries: MailReceiptDTO[]): Promise<AcknowledgeMailResultDTO>;
+export declare function recordBrokerTurn(nodeId: string, request: Omit<BrokerTurnRequest, 'expected_execution_id'>): Promise<BrokerTurnResultDTO>;
+export declare function mutateBrokerProviderRetry(nodeId: string, request: Omit<BrokerProviderRetryRequest, 'expected_execution_id'>): Promise<BrokerProviderRetryResultDTO>;
+export declare function mutateBrokerFault(nodeId: string, request: Omit<BrokerFaultRequest, 'expected_execution_id'>): Promise<BrokerFaultResultDTO>;
+export declare function brokerRecovery(nodeId: string): Promise<RecoveryStateDTO>;
+/** Node-scoped fault writes are for non-broker clients such as attach transport.
+ * Broker-owned recovery mutations use the execution-fenced wrappers above. */
+export declare function recordNodeFault(nodeId: string, input: BrokerFaultInputDTO): Promise<BrokerFaultResultDTO>;
+export declare function clearNodeFault(nodeId: string, opts?: {
+    link?: BrokerFaultInputDTO['link'];
+    preserveEpisode?: boolean;
+}): Promise<boolean>;
+/** Fixed canvas projection for broker extension rendering. It deliberately
+ * exposes no generic node/database facade. */
+export declare function commitBrokerModel(nodeId: string, request: BrokerInput<BrokerModelCommitRequest>): Promise<BrokerModelCommitResultDTO>;
+export declare function brokerExtensionState(nodeId: string): Promise<BrokerExtensionStateDTO>;
+/** Only node-owned fields are cached. A disconnected or stopped stream cannot
+ * guarantee freshness, so events at those boundaries read the daemon instead. */
+export declare function cachedBrokerNode(nodeId: string): Promise<BrokerSignalCachedNode>;
+/** The node's one delivery route: every rule-driven document delivery the
+ *  broker applies, recorded by crtrd in the same request. */
+export declare function brokerDelivery(nodeId: string, request: BrokerInput<DeliveryRequest>): Promise<DeliveryResponse>;
+export declare function commitBrokerGeneratedName(nodeId: string, request: BrokerInput<BrokerGeneratedNameRequest>): Promise<BrokerGeneratedNameResultDTO>;
+export declare function commitBrokerPersonaAck(nodeId: string, request: BrokerInput<BrokerPersonaAckRequest>): Promise<BrokerPersonaAckResultDTO>;
+/** Reports still use the canonical daemon report handler; this broker adapter
+ * only preserves terminal structured output's idempotent finalization result. */
+export declare function publishBrokerReport(nodeId: string, request: PushReportRequest): Promise<void>;
+/** Root `/new` remains on the dedicated relaunch operation because it launches
+ * a replacement broker and tears down this broker. Callers must not await it
+ * from Pi's session-start dispatch. */
+export declare function relaunchBrokerRoot(nodeId: string): Promise<RelaunchRootResultDTO>;
+export {};