@decibelsystems/tools 2.1.4 → 3.0.0

package/dist/runtime/circuitBreaker.js

@@ -0,0 +1,178 @@
+/**
+ * Per-facade circuit breaker.
+ *
+ * The failure this exists for: one facade's dependency wedges — Mother's
+ * Postgres stops accepting connections, Supabase hangs, a disk mount goes
+ * away — and every call into that facade sits on a socket until it times out.
+ * With six clients sharing one runtime that is enough to make the whole
+ * runtime feel dead, even though twenty other facades are fine. The breaker
+ * turns a slow, repeated failure into a fast, local one.
+ *
+ * WHAT COUNTS AS A FAULT is the whole design, because Decibel's tools rarely
+ * throw. `senken_trade_summary` catches its own Postgres error and returns
+ * `{isError: true}` (src/tools/senken.ts:117), so a breaker that only counted
+ * exceptions would never trip on the exact case it was built for. But counting
+ * every `isError` is worse: `create_issue` missing a title is an `isError`
+ * too, and five bad calls in a row from one confused agent must not take the
+ * sentinel facade offline for everyone.
+ *
+ * So the signal is *unresponsiveness*, not *unhappiness*:
+ *
+ *   - a thrown exception is always a fault (the handler didn't handle it)
+ *   - an `isError` result that took longer than `slowFailureMs` is a fault
+ *     (a dependency that times out is slow; a rejected argument is not)
+ *   - an `isError` result that came back fast is neither fault nor proof of
+ *     health — it leaves the counters exactly where they were
+ *   - a success closes the circuit and clears the count
+ *
+ * State machine: closed → (threshold consecutive faults) → open → (cooldown
+ * elapses) → half-open → success closes it, fault re-opens it. Half-open
+ * admits exactly one probe; concurrent callers are rejected until it lands, so
+ * a recovering database gets one connection attempt rather than six.
+ *
+ * The breaker never converts a working call into a failure — it only refuses
+ * calls it has good reason to believe would fail slowly.
+ */
+const DEFAULTS = {
+    failureThreshold: 5,
+    cooldownMs: 30_000,
+    slowFailureMs: 2_000,
+};
+export class CircuitBreakerRegistry {
+    circuits = new Map();
+    failureThreshold;
+    cooldownMs;
+    slowFailureMs;
+    now;
+    constructor(opts = {}) {
+        this.failureThreshold = opts.failureThreshold ?? DEFAULTS.failureThreshold;
+        this.cooldownMs = opts.cooldownMs ?? DEFAULTS.cooldownMs;
+        this.slowFailureMs = opts.slowFailureMs ?? DEFAULTS.slowFailureMs;
+        this.now = opts.now ?? Date.now;
+    }
+    /**
+     * Ask whether a call to `key` may proceed. Transitions open → half_open when
+     * the cooldown has elapsed, and reserves the half-open probe for the caller
+     * it says yes to.
+     */
+    beforeCall(key) {
+        const c = this.circuits.get(key);
+        if (!c || c.state === 'closed')
+            return { allowed: true };
+        if (c.state === 'open') {
+            const elapsed = this.now() - c.openedAt;
+            if (elapsed < this.cooldownMs) {
+                return {
+                    allowed: false,
+                    retryAfterMs: this.cooldownMs - elapsed,
+                    lastError: c.lastError,
+                    openedAt: new Date(c.openedAt).toISOString(),
+                };
+            }
+            // Cooldown elapsed — this caller becomes the probe.
+            c.state = 'half_open';
+            c.probeInFlight = true;
+            return { allowed: true };
+        }
+        // half_open: one probe at a time.
+        if (c.probeInFlight) {
+            return {
+                allowed: false,
+                retryAfterMs: this.cooldownMs,
+                lastError: c.lastError,
+                openedAt: new Date(c.openedAt).toISOString(),
+            };
+        }
+        c.probeInFlight = true;
+        return { allowed: true };
+    }
+    /**
+     * Report what happened. `threw` and `durationMs` decide whether this was a
+     * fault; see the module comment for why `isError` alone is not enough and
+     * not too much.
+     */
+    afterCall(key, outcome) {
+        const fault = outcome.threw || (outcome.isError && outcome.durationMs >= this.slowFailureMs);
+        if (fault) {
+            this.recordFault(key, outcome.error);
+            return;
+        }
+        if (outcome.isError) {
+            // Fast domain error: says nothing about the dependency's health. Release
+            // the probe if we were half-open, but leave the fault count alone.
+            const c = this.circuits.get(key);
+            if (c?.state === 'half_open')
+                this.close(key);
+            else if (c)
+                c.probeInFlight = false;
+            return;
+        }
+        this.recordSuccess(key);
+    }
+    recordSuccess(key) {
+        const c = this.circuits.get(key);
+        if (!c)
+            return;
+        this.close(key);
+    }
+    recordFault(key, error) {
+        const c = this.circuits.get(key) ?? {
+            state: 'closed',
+            faults: 0,
+            openedAt: 0,
+            probeInFlight: false,
+        };
+        c.lastError = error;
+        c.probeInFlight = false;
+        if (c.state === 'half_open') {
+            // The probe failed — straight back to open, full cooldown.
+            c.state = 'open';
+            c.openedAt = this.now();
+            this.circuits.set(key, c);
+            return;
+        }
+        c.faults += 1;
+        if (c.faults >= this.failureThreshold) {
+            c.state = 'open';
+            c.openedAt = this.now();
+        }
+        this.circuits.set(key, c);
+    }
+    state(key) {
+        return this.circuits.get(key)?.state ?? 'closed';
+    }
+    /** Open circuits only — a healthy runtime reports `{}`. */
+    snapshot() {
+        const out = {};
+        for (const [key, c] of this.circuits) {
+            if (c.state === 'closed' && c.faults === 0)
+                continue;
+            out[key] = {
+                state: c.state,
+                consecutive_faults: c.faults,
+                ...(c.state === 'closed' ? {} : {
+                    opened_at: new Date(c.openedAt).toISOString(),
+                    retry_after_ms: Math.max(0, this.cooldownMs - (this.now() - c.openedAt)),
+                }),
+                ...(c.lastError ? { last_error: c.lastError } : {}),
+            };
+        }
+        return out;
+    }
+    reset(key) {
+        if (key === undefined)
+            this.circuits.clear();
+        else
+            this.circuits.delete(key);
+    }
+    close(key) {
+        const c = this.circuits.get(key);
+        if (!c)
+            return;
+        c.state = 'closed';
+        c.faults = 0;
+        c.probeInFlight = false;
+        c.openedAt = 0;
+    }
+}
+//# sourceMappingURL=circuitBreaker.js.map

package/dist/runtime/circuitBreaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuitBreaker.js","sourceRoot":"","sources":["../../src/runtime/circuitBreaker.ts"],"names":[],"mappings":"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"}

package/dist/runtime/ensureRuntime.d.ts

@@ -0,0 +1,103 @@
+/**
+ * ensureRuntime — the one lifecycle primitive.
+ *
+ * Every surface that needs the Decibel runtime (MCP adapters, the CLI, the
+ * VS Code extension, shell hooks) calls this. None of them should carry their
+ * own "is the daemon up? should I start it?" logic — that duplication is how
+ * five subtly different startup behaviours end up in one codebase.
+ *
+ * Two things this deliberately does NOT do:
+ *
+ *   1. It does not use the PID file as the source of truth. `~/.decibel/daemon.pid`
+ *      goes stale — an unclean exit leaves a pid pointing at nothing, or worse,
+ *      at a recycled pid belonging to an unrelated process. A successful
+ *      `/health` response is the only proof the runtime is actually serving.
+ *
+ *   2. It does not check-then-spawn. When six clients start at once, six
+ *      "is it running? no → start it" sequences race and you get six daemons
+ *      fighting over one port. Startup is arbitrated by an atomic O_EXCL lock
+ *      file: exactly one caller wins the right to spawn, and the losers wait
+ *      for the winner's daemon rather than starting their own.
+ */
+/** Default port the daemon binds. Overridden by daemon.meta or DECIBEL_DAEMON_PORT. */
+export declare const DEFAULT_RUNTIME_PORT = 4888;
+export interface RuntimeHealth {
+    status: string;
+    version: string;
+    protocol_version?: string;
+    pid: number;
+    uptime_ms: number;
+    facade_count: number;
+    license_tier: string;
+    [key: string]: unknown;
+}
+export interface RuntimeHandle {
+    /** Base URL, e.g. `http://127.0.0.1:4888`. No trailing slash. */
+    url: string;
+    port: number;
+    /** PID of the serving runtime — reported by /health, not read from a pid file. */
+    pid: number;
+    /** Package version of the running runtime. */
+    version: string;
+    /** Wire protocol the running runtime speaks. */
+    protocolVersion: string;
+    licenseTier: string;
+    /** True when this call started the runtime; false when it was already up. */
+    spawned: boolean;
+    health: RuntimeHealth;
+}
+export interface EnsureRuntimeOptions {
+    /** Protocol version this client requires. Defaults to the compiled-in version. */
+    protocolVersion?: string;
+    /** Port override. Falls back to daemon.meta, then DECIBEL_DAEMON_PORT, then 4888. */
+    port?: number;
+    /** Total time to wait for a runtime to become healthy. */
+    timeoutMs?: number;
+    /**
+     * When false, never spawn — probe only, and throw if nothing is serving.
+     * Used by callers that must not have side effects (status commands, health
+     * checks, anything running inside a hook with a hard timeout).
+     */
+    autoStart?: boolean;
+    /** Absolute path to the runtime entry point. Defaults to this package's dist/server.js. */
+    serverEntry?: string;
+}
+/** Thrown when a runtime is serving but speaks an incompatible protocol. */
+export declare class RuntimeProtocolMismatchError extends Error {
+    readonly serverVersion: string | undefined;
+    readonly clientVersion: string;
+    constructor(serverVersion: string | undefined, clientVersion: string, reason: string);
+}
+/** Thrown when no runtime is serving and one could not be started. */
+export declare class RuntimeUnavailableError extends Error {
+    constructor(port: number, detail: string);
+}
+/**
+ * Resolve the port to talk to, in precedence order:
+ *   explicit option → DECIBEL_DAEMON_PORT → daemon.meta → default.
+ *
+ * daemon.meta is a *hint*, not proof of life — it records the port the daemon
+ * last bound. We still confirm with /health before trusting anything.
+ */
+export declare function resolveRuntimePort(explicit?: number): number;
+/**
+ * GET /health. Returns null when nothing is listening or the response is not a
+ * usable health payload — callers treat null as "no runtime here", never as an
+ * error worth surfacing.
+ */
+export declare function probeRuntime(port: number): Promise<RuntimeHealth | null>;
+/**
+ * Return a handle to a healthy, protocol-compatible runtime, starting one if
+ * needed.
+ *
+ * Throws rather than degrading:
+ *   - RuntimeProtocolMismatchError when something is serving but speaks a
+ *     contract this client does not understand.
+ *   - RuntimeUnavailableError when nothing is serving and none could be started.
+ *
+ * Callers must not silently fall back to doing the work in-process. A client
+ * that quietly becomes a second writer is exactly the failure this runtime
+ * exists to prevent.
+ */
+export declare function ensureRuntime(options?: EnsureRuntimeOptions): Promise<RuntimeHandle>;
+//# sourceMappingURL=ensureRuntime.d.ts.map

package/dist/runtime/ensureRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensureRuntime.d.ts","sourceRoot":"","sources":["../../src/runtime/ensureRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAcH,uFAAuF;AACvF,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAczC,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,2FAA2F;IAC3F,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,4EAA4E;AAC5E,qBAAa,4BAA6B,SAAQ,KAAK;IAEnD,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS;IAC1C,QAAQ,CAAC,aAAa,EAAE,MAAM;gBADrB,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,aAAa,EAAE,MAAM,EAC9B,MAAM,EAAE,MAAM;CASjB;AAED,sEAAsE;AACtE,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAQzC;AAMD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAiB5D;AAMD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAW9E;AAgHD;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,aAAa,CAAC,CAkExB"}

package/dist/runtime/ensureRuntime.js

@@ -0,0 +1,281 @@
+/**
+ * ensureRuntime — the one lifecycle primitive.
+ *
+ * Every surface that needs the Decibel runtime (MCP adapters, the CLI, the
+ * VS Code extension, shell hooks) calls this. None of them should carry their
+ * own "is the daemon up? should I start it?" logic — that duplication is how
+ * five subtly different startup behaviours end up in one codebase.
+ *
+ * Two things this deliberately does NOT do:
+ *
+ *   1. It does not use the PID file as the source of truth. `~/.decibel/daemon.pid`
+ *      goes stale — an unclean exit leaves a pid pointing at nothing, or worse,
+ *      at a recycled pid belonging to an unrelated process. A successful
+ *      `/health` response is the only proof the runtime is actually serving.
+ *
+ *   2. It does not check-then-spawn. When six clients start at once, six
+ *      "is it running? no → start it" sequences race and you get six daemons
+ *      fighting over one port. Startup is arbitrated by an atomic O_EXCL lock
+ *      file: exactly one caller wins the right to spawn, and the losers wait
+ *      for the winner's daemon rather than starting their own.
+ */
+import { spawn } from 'child_process';
+import { openSync, closeSync, writeSync, readFileSync, unlinkSync, statSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { RUNTIME_PROTOCOL_VERSION, isProtocolCompatible } from './protocol.js';
+import { localJson } from './localHttp.js';
+const DECIBEL_HOME = join(homedir(), '.decibel');
+const META_PATH = join(DECIBEL_HOME, 'daemon.meta');
+const LOCK_PATH = join(DECIBEL_HOME, 'runtime.lock');
+/** Default port the daemon binds. Overridden by daemon.meta or DECIBEL_DAEMON_PORT. */
+export const DEFAULT_RUNTIME_PORT = 4888;
+/** A lock older than this is presumed abandoned (holder crashed mid-spawn). */
+const LOCK_STALE_MS = 30_000;
+/** How long to wait for a runtime — ours or someone else's — to become healthy. */
+const DEFAULT_STARTUP_TIMEOUT_MS = 15_000;
+/** Gap between `/health` polls while waiting for startup. */
+const POLL_INTERVAL_MS = 150;
+/** Per-probe HTTP timeout. Short: a healthy local daemon answers in single-digit ms. */
+const PROBE_TIMEOUT_MS = 1_500;
+/** Thrown when a runtime is serving but speaks an incompatible protocol. */
+export class RuntimeProtocolMismatchError extends Error {
+    serverVersion;
+    clientVersion;
+    constructor(serverVersion, clientVersion, reason) {
+        super(`Decibel runtime protocol mismatch: ${reason}. ` +
+            `Restart the runtime so it matches this client (\`decibel-tools --daemon restart\`), ` +
+            `or upgrade the client to match the running runtime.`);
+        this.serverVersion = serverVersion;
+        this.clientVersion = clientVersion;
+        this.name = 'RuntimeProtocolMismatchError';
+    }
+}
+/** Thrown when no runtime is serving and one could not be started. */
+export class RuntimeUnavailableError extends Error {
+    constructor(port, detail) {
+        super(`Decibel runtime is not available on 127.0.0.1:${port}: ${detail}. ` +
+            `Start it manually with \`decibel-tools --daemon\` and check ` +
+            `~/.decibel/logs/daemon.log for why it did not come up.`);
+        this.name = 'RuntimeUnavailableError';
+    }
+}
+// ============================================================================
+// Port discovery
+// ============================================================================
+/**
+ * Resolve the port to talk to, in precedence order:
+ *   explicit option → DECIBEL_DAEMON_PORT → daemon.meta → default.
+ *
+ * daemon.meta is a *hint*, not proof of life — it records the port the daemon
+ * last bound. We still confirm with /health before trusting anything.
+ */
+export function resolveRuntimePort(explicit) {
+    if (explicit)
+        return explicit;
+    const fromEnv = process.env.DECIBEL_DAEMON_PORT;
+    if (fromEnv) {
+        const parsed = Number(fromEnv);
+        if (Number.isInteger(parsed) && parsed > 0 && parsed < 65536)
+            return parsed;
+    }
+    try {
+        const meta = JSON.parse(readFileSync(META_PATH, 'utf-8'));
+        if (Number.isInteger(meta?.port))
+            return meta.port;
+    }
+    catch {
+        // No meta file, or unreadable — fall through to the default.
+    }
+    return DEFAULT_RUNTIME_PORT;
+}
+// ============================================================================
+// Health probe
+// ============================================================================
+/**
+ * GET /health. Returns null when nothing is listening or the response is not a
+ * usable health payload — callers treat null as "no runtime here", never as an
+ * error worth surfacing.
+ */
+export async function probeRuntime(port) {
+    try {
+        const res = await localJson(`http://127.0.0.1:${port}/health`, {
+            timeoutMs: PROBE_TIMEOUT_MS,
+        });
+        if (!res.ok)
+            return null;
+        if (typeof res.body?.status !== 'string')
+            return null;
+        return res.body;
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Startup arbitration
+// ============================================================================
+/**
+ * Try to become the process responsible for spawning the runtime.
+ *
+ * `wx` is O_EXCL: the create either succeeds atomically or fails because
+ * someone else holds it. That is the whole arbitration mechanism — no
+ * read-then-write window for a second caller to slip through.
+ *
+ * A lock whose mtime is older than LOCK_STALE_MS is presumed abandoned (its
+ * holder crashed between acquiring and spawning) and is removed so startup can
+ * proceed. Without that, one crashed spawn would wedge every future client.
+ */
+function tryAcquireStartupLock() {
+    mkdirSync(DECIBEL_HOME, { recursive: true });
+    try {
+        const fd = openSync(LOCK_PATH, 'wx');
+        writeSync(fd, JSON.stringify({ pid: process.pid, at: new Date().toISOString() }));
+        closeSync(fd);
+        return true;
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST')
+            throw err;
+    }
+    // Held by someone. Abandoned?
+    try {
+        const age = Date.now() - statSync(LOCK_PATH).mtimeMs;
+        if (age > LOCK_STALE_MS) {
+            unlinkSync(LOCK_PATH);
+            return tryAcquireStartupLock();
+        }
+    }
+    catch {
+        // Vanished between our EEXIST and the stat — the holder finished. Retry once.
+        try {
+            const fd = openSync(LOCK_PATH, 'wx');
+            writeSync(fd, JSON.stringify({ pid: process.pid, at: new Date().toISOString() }));
+            closeSync(fd);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+function releaseStartupLock() {
+    try {
+        unlinkSync(LOCK_PATH);
+    }
+    catch {
+        // Already gone (stolen as stale, or cleaned up elsewhere). Nothing to do.
+    }
+}
+/** Default runtime entry point: dist/server.js in this package. */
+function defaultServerEntry() {
+    // src/runtime/ensureRuntime.ts → dist/runtime/ensureRuntime.js at runtime,
+    // so ../server.js resolves to dist/server.js in both layouts.
+    return join(dirname(fileURLToPath(import.meta.url)), '..', 'server.js');
+}
+/**
+ * Spawn the daemon fully detached so it outlives this client. A runtime that
+ * dies when the terminal that happened to start it closes is not a shared
+ * runtime.
+ */
+function spawnRuntime(port, serverEntry) {
+    const child = spawn(process.execPath, [serverEntry, '--daemon', '--port', String(port)], {
+        detached: true,
+        stdio: 'ignore',
+        env: process.env,
+    });
+    child.unref();
+}
+/** Poll /health until it answers compatibly, or the deadline passes. */
+async function waitForHealthy(port, clientProtocol, deadline) {
+    while (Date.now() < deadline) {
+        const health = await probeRuntime(port);
+        if (health) {
+            const compat = isProtocolCompatible(health.protocol_version, clientProtocol);
+            if (!compat.compatible) {
+                throw new RuntimeProtocolMismatchError(health.protocol_version, clientProtocol, compat.reason);
+            }
+            return health;
+        }
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    }
+    return null;
+}
+// ============================================================================
+// Entry point
+// ============================================================================
+/**
+ * Return a handle to a healthy, protocol-compatible runtime, starting one if
+ * needed.
+ *
+ * Throws rather than degrading:
+ *   - RuntimeProtocolMismatchError when something is serving but speaks a
+ *     contract this client does not understand.
+ *   - RuntimeUnavailableError when nothing is serving and none could be started.
+ *
+ * Callers must not silently fall back to doing the work in-process. A client
+ * that quietly becomes a second writer is exactly the failure this runtime
+ * exists to prevent.
+ */
+export async function ensureRuntime(options = {}) {
+    const clientProtocol = options.protocolVersion ?? RUNTIME_PROTOCOL_VERSION;
+    const port = resolveRuntimePort(options.port);
+    const autoStart = options.autoStart !== false;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+    // Fast path: something is already serving.
+    const existing = await probeRuntime(port);
+    if (existing) {
+        const compat = isProtocolCompatible(existing.protocol_version, clientProtocol);
+        if (!compat.compatible) {
+            throw new RuntimeProtocolMismatchError(existing.protocol_version, clientProtocol, compat.reason);
+        }
+        return toHandle(existing, port, false);
+    }
+    if (!autoStart) {
+        throw new RuntimeUnavailableError(port, 'nothing is listening and autoStart is disabled');
+    }
+    const deadline = Date.now() + timeoutMs;
+    // Arbitrate. Exactly one caller spawns; the rest wait for that one.
+    const isSpawner = tryAcquireStartupLock();
+    if (!isSpawner) {
+        const health = await waitForHealthy(port, clientProtocol, deadline);
+        if (health)
+            return toHandle(health, port, false);
+        throw new RuntimeUnavailableError(port, 'another process holds the startup lock but no runtime became healthy before the timeout');
+    }
+    try {
+        // Re-probe under the lock. Between our first probe and acquiring the lock,
+        // a previous holder may have finished starting one.
+        const raced = await probeRuntime(port);
+        if (raced) {
+            const compat = isProtocolCompatible(raced.protocol_version, clientProtocol);
+            if (!compat.compatible) {
+                throw new RuntimeProtocolMismatchError(raced.protocol_version, clientProtocol, compat.reason);
+            }
+            return toHandle(raced, port, false);
+        }
+        spawnRuntime(port, options.serverEntry ?? defaultServerEntry());
+        const health = await waitForHealthy(port, clientProtocol, deadline);
+        if (health)
+            return toHandle(health, port, true);
+        throw new RuntimeUnavailableError(port, `spawned a runtime but it did not report healthy within ${timeoutMs}ms`);
+    }
+    finally {
+        releaseStartupLock();
+    }
+}
+function toHandle(health, port, spawned) {
+    return {
+        url: `http://127.0.0.1:${port}`,
+        port,
+        pid: health.pid,
+        version: health.version,
+        protocolVersion: health.protocol_version ?? 'unknown',
+        licenseTier: health.license_tier,
+        spawned,
+        health,
+    };
+}
+//# sourceMappingURL=ensureRuntime.js.map

package/dist/runtime/ensureRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensureRuntime.js","sourceRoot":"","sources":["../../src/runtime/ensureRuntime.ts"],"names":[],"mappings":"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"}

package/dist/runtime/extensions.d.ts

@@ -0,0 +1,57 @@
+import type { FacadeSpec } from '../facades/types.js';
+import type { ToolSpec } from '../tools/types.js';
+export interface DecibelExtensionManifest {
+    /** Facade-style identifier, e.g. "senken". Must not collide with a core facade. */
+    name: string;
+    /** The extension's own version, independent of the runtime's. */
+    version: string;
+    /** Runtime wire contract this extension was built against. See protocol.ts. */
+    protocolVersion: string;
+    /** Extensions are never core — core is what ships in the package. */
+    tier: 'pro' | 'apps';
+}
+export interface DecibelExtension {
+    manifest: DecibelExtensionManifest;
+    facades: FacadeSpec[];
+    tools: ToolSpec[];
+}
+export interface RejectedExtension {
+    /** The allowlist entry as written, so the owner can find it in their config. */
+    entry: string;
+    reason: string;
+}
+export interface ExtensionLoadResult {
+    extensions: DecibelExtension[];
+    facades: FacadeSpec[];
+    tools: ToolSpec[];
+    rejected: RejectedExtension[];
+}
+/**
+ * Read the extension allowlist from ~/.decibel/config.yaml.
+ *
+ * Deliberately config-only. Reading a path from the environment would let
+ * anything that can set an env var — a plist, a shell profile, a parent
+ * process — choose code that runs in-process with full access, which is
+ * exactly the property the allowlist exists to provide.
+ */
+export declare function readAllowlist(): string[];
+/** Path rules, split out so the test suite can exercise them without a filesystem. */
+export declare function checkAllowlistEntry(entry: string): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Load every allowlisted extension.
+ *
+ * Never throws. A broken extension is reported in `rejected` and the runtime
+ * boots without it — one bad private module must not take down core. Callers
+ * that care (the daemon's startup log, /health) surface the rejections.
+ *
+ * @param reservedNames Facade names already registered. An extension may not
+ *   shadow one; that would let a private module silently replace `sentinel`.
+ */
+export declare function loadExtensions(reservedNames?: ReadonlySet<string>): Promise<ExtensionLoadResult>;
+//# sourceMappingURL=extensions.d.ts.map

package/dist/runtime/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../src/runtime/extensions.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AASlD,MAAM,WAAW,wBAAwB;IACvC,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,eAAe,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,wBAAwB,CAAC;IACnC,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AA6FD;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAKxC;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAsB7G;AAMD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,aAAa,GAAE,WAAW,CAAC,MAAM,CAAa,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAyDjH"}