@north-light/api 0.0.0-stage → 0.3.414

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

@@ -0,0 +1,485 @@
+// 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), the
+// copy is missing, or the copy no longer starts. The last case matters because
+// the copied libnode does NOT protect the other absolute Homebrew deps (e.g.
+// libsimdjson.<n>.dylib): a `brew upgrade` that bumps one leaves the branded host
+// aborting in dyld while its marker still matches. That holds even when the
+// caller is itself running as the branded host (crtrd, a broker): it then
+// rebuilds from a real node found via findRealNode(), never from itself.
+//
+// FALLBACK: inside the host, childNodeExecPath() / hostExecPath() use a real
+// node (same native-module ABI) while the host cannot start, probing
+// asynchronously and rebuilding the host in a detached child — the daemon's
+// event loop never blocks on it.
+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 { execFile, spawn, 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); hostExecPath() turns that into a logged fallback to
+ *  a real node so a broken host never blocks launching. */
+export function ensureBrandedHost(opts = {}) {
+    return withBrandedHostLock(() => {
+        const hostDir = brandedHostDir();
+        const dst = brandedHostBin();
+        let src = realpathSync(opts.execPath ?? process.execPath);
+        // If THIS process is running as the branded host (the daemon or a broker),
+        // the live process proves only that the copy *was* loadable. It says nothing
+        // about whether a fresh process can start it: a moved Homebrew dylib breaks
+        // every new exec while the running one carries on. So re-check, and when the
+        // copy is broken rebuild from a real node — we can't copy ourselves.
+        if (existsSync(dst) && realpathSync(dst) === src) {
+            if (brandedHostWorks(dst))
+                return dst;
+            const real = findRealNode();
+            if (real === null) {
+                throw new Error(`branded host cannot start and no working node was found to rebuild it from: ${dst}`);
+            }
+            src = real;
+        }
+        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));
+            // Both artifacts were validated together in the stage dir. A libnode keeps
+            // its filename only when its ABI is unchanged (the name embeds it), so a
+            // launcher that starts between these two renames pairs the old stub with a
+            // same-ABI libnode, which loads; a changed ABI gets a new name and never
+            // replaces the old file in place.
+            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}`);
+}
+/** True when `execPath` is the branded host copy (so a child exec'd from it
+ *  inherits the copy's dyld dependencies). */
+function isBrandedHostExec(execPath) {
+    try {
+        const hostDir = realpathSync(brandedHostDir());
+        return dirname(realpathSync(execPath)) === hostDir;
+    }
+    catch {
+        return false;
+    }
+}
+/** Candidate real nodes, most trustworthy first: the installed Homebrew node
+ *  (the one an upgrade just put in place), this process's own node when it is
+ *  not the host, PATH entries, then the marker's recorded source (an older keg
+ *  after an upgrade, so last). */
+function realNodeCandidates() {
+    const candidates = ['/opt/homebrew/bin/node', '/usr/local/bin/node'];
+    if (!isBrandedHostExec(process.execPath))
+        candidates.push(process.execPath);
+    for (const dir of (process.env['PATH'] ?? '').split(':'))
+        if (dir !== '')
+            candidates.push(join(dir, 'node'));
+    const marker = readMarker();
+    if (marker !== null && typeof marker.source === 'string')
+        candidates.push(marker.source);
+    const seen = new Set();
+    const real = [];
+    for (const candidate of candidates) {
+        let resolved;
+        try {
+            resolved = realpathSync(candidate);
+        }
+        catch {
+            continue;
+        }
+        if (seen.has(resolved) || isBrandedHostExec(resolved))
+            continue;
+        seen.add(resolved);
+        real.push(resolved);
+    }
+    return real;
+}
+/** A candidate is acceptable only if it starts AND speaks this process's native
+ *  module ABI, so addons and engine features built for the running Node keep
+ *  working — a merely-startable older nvm node is not a fallback. */
+const ABI_PROBE_ARGS = ['-p', 'process.versions.modules'];
+function abiMatches(stdout) {
+    return stdout !== null && stdout.trim() === process.versions.modules;
+}
+/** Find a working, ABI-compatible, non-branded `node` to rebuild from. Blocking:
+ *  for CLI / explicit reconcile only, never the daemon's event loop (use
+ *  findRealNodeAsync there). Returns null when none works. */
+export function findRealNode() {
+    for (const candidate of realNodeCandidates()) {
+        try {
+            const res = spawnSync(candidate, ABI_PROBE_ARGS, { encoding: 'utf8', timeout: 5_000, stdio: ['ignore', 'pipe', 'ignore'] });
+            if (res.status === 0 && abiMatches(res.stdout))
+                return candidate;
+        }
+        catch {
+            /* try the next candidate */
+        }
+    }
+    return null;
+}
+function execFileProbe(bin, args, timeoutMs) {
+    return new Promise((resolve) => {
+        try {
+            execFile(bin, args, { encoding: 'utf8', timeout: timeoutMs }, (error, stdout) => resolve(error === null ? stdout : null));
+        }
+        catch {
+            resolve(null);
+        }
+    });
+}
+/** Non-blocking findRealNode for the daemon's event loop. */
+export async function findRealNodeAsync() {
+    for (const candidate of realNodeCandidates()) {
+        if (abiMatches(await execFileProbe(candidate, ABI_PROBE_ARGS, 5_000)))
+            return candidate;
+    }
+    return null;
+}
+// Health of the branded host as seen from a process RUNNING as that host (crtrd,
+// a broker). It is refreshed asynchronously — never a blocking probe on the
+// event loop — and a fork that dies forces an immediate re-probe, so the first
+// failed fork heals instead of waiting out a TTL.
+const HEALTH_TTL_MS = 15_000;
+const HEAL_THROTTLE_MS = 60_000;
+const hostHealth = { checkedAt: 0, fallback: null, probing: null, lastHealAt: 0 };
+/** Forget remembered host health (tests). */
+export function resetBrandedHostHealthCache() {
+    hostHealth.checkedAt = 0;
+    hostHealth.fallback = null;
+    hostHealth.probing = null;
+    hostHealth.lastHealAt = 0;
+}
+/** Rebuild the host from a real node in a detached child, off this process's
+ *  event loop (copy + codesign are blocking). Throttled. Skipped in source/tsx
+ *  runs, which never use the host. */
+function healBrandedHostInBackground(realNode) {
+    if (import.meta.url.endsWith('.ts'))
+        return;
+    const now = Date.now();
+    if (now - hostHealth.lastHealAt < HEAL_THROTTLE_MS)
+        return;
+    hostHealth.lastHealAt = now;
+    try {
+        const script = `import(${JSON.stringify(import.meta.url)}).then((m) => m.ensureBrandedHost())`;
+        const child = spawn(realNode, ['--input-type=module', '-e', script], { detached: true, stdio: 'ignore' });
+        child.on('error', () => undefined);
+        child.unref();
+    }
+    catch {
+        /* healing is best-effort; the fallback node already keeps launches working */
+    }
+}
+function refreshHostHealth(host) {
+    if (hostHealth.probing !== null)
+        return hostHealth.probing;
+    hostHealth.probing = (async () => {
+        try {
+            if ((await execFileProbe(host, ['-e', ''], 5_000)) !== null) {
+                hostHealth.fallback = null;
+                return;
+            }
+            const real = await findRealNodeAsync();
+            if (real !== hostHealth.fallback && real !== null) {
+                emitEvent({ event: 'host.fallback.node', level: 'warn', fields: { host, node: real } });
+            }
+            hostHealth.fallback = real;
+            if (real !== null)
+                healBrandedHostInBackground(real);
+        }
+        finally {
+            hostHealth.checkedAt = Date.now();
+            hostHealth.probing = null;
+        }
+    })();
+    return hostHealth.probing;
+}
+/** The node to exec for a short-lived helper child (forked worker, bash
+ *  supervisor, probe). Outside the branded host this is `process.execPath`
+ *  untouched. Inside it, a host that no longer starts (dyld cannot resolve a
+ *  moved Homebrew dependency) would abort every child, so a real node is used
+ *  instead. Never blocks: it returns the last known answer and refreshes it in
+ *  the background. A fork that still dies calls recheckChildNode() to learn the
+ *  truth at once. */
+export function childNodeExecPath(execPath = process.execPath) {
+    if (!isBrandedHostExec(execPath))
+        return execPath;
+    if (Date.now() - hostHealth.checkedAt > HEALTH_TTL_MS && hostHealth.probing === null)
+        void refreshHostHealth(execPath);
+    return hostHealth.fallback ?? execPath;
+}
+/** Re-probe the host now (after a child died) and return the node to retry on;
+ *  equals `execPath` when the host is fine or no real node exists. */
+export async function recheckChildNode(execPath = process.execPath) {
+    if (!isBrandedHostExec(execPath))
+        return execPath;
+    await refreshHostHealth(execPath);
+    return hostHealth.fallback ?? execPath;
+}
+/** Like childNodeExecPath(), but first awaits a probe no older than `maxAgeMs`
+ *  (coalesced with any probe in flight). Use it right before a fork whose death
+ *  would lose work (a broker, a bash job, the inventory child) so a host broken
+ *  since the last probe is caught before the exec, not after. The probe is a
+ *  non-blocking `node -e ''`; outside the branded host this costs nothing. */
+export async function freshChildNodeExecPath(execPath = process.execPath, maxAgeMs = 1_000) {
+    if (!isBrandedHostExec(execPath))
+        return execPath;
+    if (hostHealth.probing === null && Date.now() - hostHealth.checkedAt >= maxAgeMs)
+        await refreshHostHealth(execPath);
+    else if (hostHealth.probing !== null)
+        await hostHealth.probing;
+    return hostHealth.fallback ?? execPath;
+}
+/** hostExecPath() for async launchers: inside the host it is verified fresh
+ *  rather than taken from the cache. */
+export async function hostExecPathFresh() {
+    if (process.env['CRTR_BRANDED_HOST'] === '0' || process.platform !== 'darwin' || import.meta.url.endsWith('.ts'))
+        return hostExecPath();
+    if (isBrandedHostExec(process.execPath))
+        return freshChildNodeExecPath();
+    return hostExecPath();
+}
+/** 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;
+    // Running AS the host (crtrd spawning a broker): never block this event loop.
+    // The host is used while it starts and a real node otherwise, with a
+    // background rebuild — see childNodeExecPath().
+    if (isBrandedHostExec(process.execPath))
+        return childNodeExecPath();
+    try {
+        return ensureBrandedHost();
+    }
+    catch (error) {
+        // A host that cannot be (re)built must not stop every node from launching.
+        // This process is a real node, so run unbranded and say so.
+        emitEvent({ event: 'host.fallback.node', level: 'warn', error, fields: { host: brandedHostBin(), node: process.execPath } });
+        return process.execPath;
+    }
+}

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 {};