@martinloop/mcp 0.3.8 → 0.5.0

package/dist/vendor/core/context-shadow.js

@@ -0,0 +1,200 @@
+/**
+ * Context Shadow Compiler — A-CTX-0
+ *
+ * Deterministic shadow manifest emitter. Observes the compiled prompt and
+ * records what a context-aware selector would have chosen, without altering
+ * the actual provider input in any way.
+ *
+ * Invariants:
+ *   - nowMs is always a captured input; Date.now() is never called internally
+ *   - No source text appears in any output type
+ *   - Required segments are always preferred first
+ *   - required-over-budget is recorded, never thrown
+ *   - Manifest hash covers metadata only (no content)
+ */
+import { createHash } from "node:crypto";
+import { CONTEXT_SHADOW_MANIFEST_VERSION, CONTEXT_C5_VERSION } from "../contracts/index.js";
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function sha256(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function canonicalize(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonicalize);
+    }
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => [k, canonicalize(v)]));
+    }
+    return value;
+}
+function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+export function estimateContextTokens(text) {
+    if (text.length === 0)
+        return 0;
+    return Math.max(1, Math.ceil(Buffer.byteLength(text, "utf8") / 4));
+}
+// ─── Compiler ────────────────────────────────────────────────────────────────
+export function compileContextShadow(input) {
+    const { runId, adapter, nowMs, shadowBudgetTokens, segments } = input;
+    // Validate: all segmentIds must be non-empty and unique
+    const seen = new Set();
+    for (const seg of segments) {
+        if (!seg.segmentId || seg.segmentId.trim() === "") {
+            throw new Error("compileContextShadow: segmentId must be non-empty");
+        }
+        if (seen.has(seg.segmentId)) {
+            throw new Error(`compileContextShadow: duplicate segmentId "${seg.segmentId}"`);
+        }
+        seen.add(seg.segmentId);
+    }
+    // Hash each segment's content — never expose the text itself
+    const hashed = segments.map((seg) => ({
+        segmentId: seg.segmentId,
+        kind: seg.kind,
+        required: seg.required,
+        contentHash: sha256(seg.text),
+        estimatedTokens: estimateContextTokens(seg.text)
+    }));
+    // Compute actualPromptHash from all segments in original order
+    const actualPromptHash = sha256(canonicalJson(hashed.map((h) => ({ segmentId: h.segmentId, contentHash: h.contentHash }))));
+    const actualEstimatedTokens = hashed.reduce((sum, h) => sum + h.estimatedTokens, 0);
+    // Compute compilerInputHash — includes nowMs for cross-run determinism
+    const compilerInputHash = sha256(canonicalJson({
+        adapter,
+        nowMs,
+        segments: hashed.map((h) => ({
+            segmentId: h.segmentId,
+            kind: h.kind,
+            required: h.required,
+            contentHash: h.contentHash,
+            estimatedTokens: h.estimatedTokens
+        })),
+        shadowBudgetTokens,
+        ...(input.taskId === undefined ? {} : { taskId: input.taskId }),
+        ...(input.model === undefined ? {} : { model: input.model })
+    }));
+    // Shadow selection: required first (in original order), then optional
+    const required = hashed.filter((h) => h.required);
+    const optional = hashed.filter((h) => !h.required);
+    let remaining = shadowBudgetTokens;
+    const decisions = [];
+    // Required segments — always included even if over budget
+    let requiredOverBudget = false;
+    const requiredTokens = required.reduce((s, h) => s + h.estimatedTokens, 0);
+    if (requiredTokens > shadowBudgetTokens) {
+        requiredOverBudget = true;
+    }
+    for (const h of required) {
+        const included = !requiredOverBudget;
+        decisions.push({
+            segmentId: h.segmentId,
+            kind: h.kind,
+            contentHash: h.contentHash,
+            estimatedTokens: h.estimatedTokens,
+            actuallyIncluded: true,
+            proposedDecision: included ? "included" : "excluded",
+            reason: requiredOverBudget ? "required_over_budget" : "required"
+        });
+        if (!requiredOverBudget) {
+            remaining -= h.estimatedTokens;
+        }
+    }
+    // Optional segments — include while budget remains
+    for (const h of optional) {
+        if (h.estimatedTokens <= remaining) {
+            decisions.push({
+                segmentId: h.segmentId,
+                kind: h.kind,
+                contentHash: h.contentHash,
+                estimatedTokens: h.estimatedTokens,
+                actuallyIncluded: true,
+                proposedDecision: "included",
+                reason: "within_shadow_budget"
+            });
+            remaining -= h.estimatedTokens;
+        }
+        else {
+            decisions.push({
+                segmentId: h.segmentId,
+                kind: h.kind,
+                contentHash: h.contentHash,
+                estimatedTokens: h.estimatedTokens,
+                actuallyIncluded: true,
+                proposedDecision: "excluded",
+                reason: "shadow_budget_exhausted"
+            });
+        }
+    }
+    // Restore original segment order in decisions list
+    const orderMap = new Map(segments.map((s, i) => [s.segmentId, i]));
+    decisions.sort((a, b) => (orderMap.get(a.segmentId) ?? 0) - (orderMap.get(b.segmentId) ?? 0));
+    const proposedEstimatedTokens = decisions
+        .filter((d) => d.proposedDecision === "included")
+        .reduce((s, d) => s + d.estimatedTokens, 0);
+    const capturedAt = new Date(nowMs).toISOString();
+    const manifestId = sha256(`${runId}:${compilerInputHash}:${capturedAt}`);
+    // Manifest hash covers metadata only — no content
+    const manifestHashInput = canonicalJson({
+        adapter,
+        capturedAt,
+        compilerInputHash,
+        manifestId,
+        mode: "shadow",
+        modelWindowEvidence: input.modelWindowEvidence ?? "unknown",
+        modelWindowTokens: input.modelWindowTokens ?? null,
+        requiredOverBudget,
+        runId,
+        shadowBudgetTokens,
+        ...(input.taskId === undefined ? {} : { taskId: input.taskId }),
+        ...(input.model === undefined ? {} : { model: input.model })
+    });
+    const manifestHash = sha256(manifestHashInput);
+    const includedCount = decisions.filter((d) => d.proposedDecision === "included").length;
+    const excludedCount = decisions.filter((d) => d.proposedDecision === "excluded").length;
+    const manifest = {
+        schemaVersion: CONTEXT_SHADOW_MANIFEST_VERSION,
+        manifestId,
+        manifestHash,
+        compilerInputHash,
+        runId,
+        adapter,
+        capturedAt,
+        mode: "shadow",
+        modelWindowTokens: input.modelWindowTokens ?? null,
+        modelWindowEvidence: input.modelWindowEvidence ?? "unknown",
+        shadowBudgetTokens,
+        actualPromptHash,
+        actualEstimatedTokens,
+        proposedEstimatedTokens,
+        requiredOverBudget,
+        decisions,
+        ...(input.taskId === undefined ? {} : { taskId: input.taskId }),
+        ...(input.model === undefined ? {} : { model: input.model })
+    };
+    const receipt = {
+        schemaVersion: CONTEXT_C5_VERSION,
+        resource: "context",
+        event: "shadow_compiled",
+        runId,
+        manifestId,
+        manifestHash,
+        mode: "shadow",
+        adapter,
+        actualEstimatedTokens,
+        proposedEstimatedTokens,
+        candidateCount: decisions.length,
+        includedCount,
+        excludedCount,
+        requiredOverBudget,
+        modelWindowTokens: input.modelWindowTokens ?? null,
+        modelWindowEvidence: input.modelWindowEvidence ?? "unknown",
+        createdAt: capturedAt,
+        ...(input.taskId === undefined ? {} : { taskId: input.taskId }),
+        ...(input.model === undefined ? {} : { model: input.model })
+    };
+    return { manifest, receipt };
+}

package/dist/vendor/core/exit-signal.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Durable exit signals — per-kind, exclusive-create, precedence-safe.
+ *
+ * Each signal kind occupies its own immutable slot:
+ *   <runDir>/signals/human_interrupt.json
+ *   <runDir>/signals/external_event.json
+ *
+ * Atomic publication (crash-safe):
+ *   1. Write complete JSON to a unique tmp file (wx, 0o600) in the signals dir
+ *   2. Sync and close the tmp file
+ *   3. Hard-link tmp to the final per-kind slot (EEXIST → already_exists)
+ *   4. Unlink tmp in finally; best-effort dir sync on POSIX
+ *
+ * The final slot is only visible after a fully written tmp — a crash cannot
+ * leave a permanently malformed final slot.
+ *
+ * Per-kind files let different kinds coexist — an external event filed first
+ * does NOT prevent a later human interrupt.  EXIT_PRECEDENCE is always honoured.
+ *
+ * Real-path containment guards against symlink/junction traversal out of the
+ * run store.  Diagnostics from malformed signals are propagated — never silently
+ * discarded as "no signal".
+ */
+import type { ExitSignalV1 } from "../contracts/index.js";
+export interface ExitSignalSource {
+    poll(runId: string): Promise<SignalReadResult>;
+}
+export interface SignalReadResult {
+    signals: readonly ExitSignalV1[];
+    diagnostics: readonly SignalDiagnostic[];
+}
+export interface SignalDiagnostic {
+    kind: "human_interrupt" | "external_event";
+    error: string;
+}
+/**
+ * Typed error surfaced by the monitor when diagnostics are detected and no
+ * onDiagnostic handler is registered.  Contains safe diagnostic codes and
+ * signal kinds — no absolute paths or payload secrets.
+ */
+export declare class SignalDiagnosticError extends Error {
+    readonly diagnostics: readonly SignalDiagnostic[];
+    constructor(diagnostics: readonly SignalDiagnostic[]);
+}
+/** Path to a per-kind signal file — safe against lexical traversal. */
+export declare function exitSignalPath(runsRoot: string, runId: string, kind: "human_interrupt" | "external_event"): string;
+/**
+ * Write one signal of its kind atomically.  Returns "created" on success or
+ * "already_exists" when that kind was already filed (first writer wins).
+ * Throws on IO errors other than EEXIST on the final slot.
+ *
+ * Publication sequence (crash-safe):
+ *   1. Validate signal and size-check the payload
+ *   2. mkdir the signals directory
+ *   3. realpath-check: the real signals dir must stay inside the real root
+ *   4. Write complete JSON to a unique tmp file (wx, 0o600)
+ *   5. Sync and close the tmp file
+ *   6. Hard-link tmp to the final per-kind slot (EEXIST → already_exists)
+ *   7. Unlink tmp in finally; best-effort dir sync on POSIX
+ */
+export declare function writeExitSignal(runsRoot: string, signal: ExitSignalV1): Promise<"created" | "already_exists">;
+/**
+ * Read all present signals for a run (both kinds).  Returns a structured
+ * result with any parse diagnostics rather than throwing on malformed files.
+ */
+export declare function readAllExitSignals(runsRoot: string, runId: string): Promise<SignalReadResult>;
+/** Read a single signal kind; returns undefined when absent. */
+export declare function readExitSignal(runsRoot: string, runId: string, kind: "human_interrupt" | "external_event"): Promise<ExitSignalV1 | undefined>;
+export declare function createFileExitSignalSource(runsRoot: string): ExitSignalSource;
+/**
+ * Polls for any exit signal and calls onSignal with the full set when any
+ * new signal appears.  Returns a dispose function — MUST be called on every
+ * return/throw path in the run harness (invariant: one interval per run).
+ *
+ * Diagnostics (malformed signals, containment failures) are routed to
+ * onDiagnostic when provided; otherwise surfaced as a SignalDiagnosticError
+ * through onError so callers always learn about corruption rather than
+ * silently treating it as "no signal".
+ */
+export declare function startExitSignalMonitor(input: {
+    source?: ExitSignalSource;
+    runId: string;
+    controller: AbortController;
+    pollIntervalMs?: number;
+    onSignal: (signals: readonly ExitSignalV1[]) => void;
+    onDiagnostic?: (diagnostics: readonly SignalDiagnostic[]) => void;
+    onError: (error: Error) => void;
+}): () => void;

package/dist/vendor/core/exit-signal.js

@@ -0,0 +1,339 @@
+/**
+ * Durable exit signals — per-kind, exclusive-create, precedence-safe.
+ *
+ * Each signal kind occupies its own immutable slot:
+ *   <runDir>/signals/human_interrupt.json
+ *   <runDir>/signals/external_event.json
+ *
+ * Atomic publication (crash-safe):
+ *   1. Write complete JSON to a unique tmp file (wx, 0o600) in the signals dir
+ *   2. Sync and close the tmp file
+ *   3. Hard-link tmp to the final per-kind slot (EEXIST → already_exists)
+ *   4. Unlink tmp in finally; best-effort dir sync on POSIX
+ *
+ * The final slot is only visible after a fully written tmp — a crash cannot
+ * leave a permanently malformed final slot.
+ *
+ * Per-kind files let different kinds coexist — an external event filed first
+ * does NOT prevent a later human interrupt.  EXIT_PRECEDENCE is always honoured.
+ *
+ * Real-path containment guards against symlink/junction traversal out of the
+ * run store.  Diagnostics from malformed signals are propagated — never silently
+ * discarded as "no signal".
+ */
+import { link, lstat, mkdir, open, readFile, realpath, unlink } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+const MAX_SIGNAL_BYTES = 64 * 1024;
+const RUN_ID_RE = /^[A-Za-z0-9._-]{1,128}$/u;
+/**
+ * Typed error surfaced by the monitor when diagnostics are detected and no
+ * onDiagnostic handler is registered.  Contains safe diagnostic codes and
+ * signal kinds — no absolute paths or payload secrets.
+ */
+export class SignalDiagnosticError extends Error {
+    diagnostics;
+    constructor(diagnostics) {
+        const summary = diagnostics
+            .map((d) => `${d.kind}: ${d.error}`)
+            .join("; ");
+        super(`Signal diagnostics: ${summary}`);
+        this.name = "SignalDiagnosticError";
+        this.diagnostics = diagnostics;
+    }
+}
+/** Path to a per-kind signal file — safe against lexical traversal. */
+export function exitSignalPath(runsRoot, runId, kind) {
+    assertRunId(runId);
+    const root = resolve(runsRoot);
+    const runDir = resolve(root, runId);
+    const sep = process.platform === "win32" ? "\\" : "/";
+    if (runDir !== root && !runDir.startsWith(`${root}${sep}`)) {
+        throw new Error("Resolved run path escapes runs root");
+    }
+    const filename = kind === "human_interrupt"
+        ? "human_interrupt.json"
+        : "external_event.json";
+    return join(runDir, "signals", filename);
+}
+/**
+ * Write one signal of its kind atomically.  Returns "created" on success or
+ * "already_exists" when that kind was already filed (first writer wins).
+ * Throws on IO errors other than EEXIST on the final slot.
+ *
+ * Publication sequence (crash-safe):
+ *   1. Validate signal and size-check the payload
+ *   2. mkdir the signals directory
+ *   3. realpath-check: the real signals dir must stay inside the real root
+ *   4. Write complete JSON to a unique tmp file (wx, 0o600)
+ *   5. Sync and close the tmp file
+ *   6. Hard-link tmp to the final per-kind slot (EEXIST → already_exists)
+ *   7. Unlink tmp in finally; best-effort dir sync on POSIX
+ */
+export async function writeExitSignal(runsRoot, signal) {
+    validateExitSignal(signal);
+    const payload = `${JSON.stringify(signal)}\n`;
+    if (Buffer.byteLength(payload, "utf8") > MAX_SIGNAL_BYTES) {
+        throw new Error("Exit signal payload exceeds 64 KiB");
+    }
+    const finalPath = exitSignalPath(runsRoot, signal.runId, signal.kind);
+    const sigDir = dirname(finalPath);
+    await mkdir(sigDir, { recursive: true });
+    // Real-path containment: the real signals directory must stay inside the
+    // real run store root.  This catches symlink/junction escapes that lexical
+    // resolve() cannot detect.
+    const realRoot = await realpath(resolve(runsRoot));
+    const realSigDir = await realpath(sigDir);
+    if (!isContained(realRoot, realSigDir)) {
+        throw new Error("Signal directory escapes the run store");
+    }
+    // Atomic publication via unique tmp file + hard-link.
+    // Both tmp and final are in the same directory, so they are on the same
+    // filesystem — hard-link is always available.
+    const tmpPath = join(sigDir, `.tmp-${randomUUID()}`);
+    let handle;
+    try {
+        handle = await open(tmpPath, "wx", 0o600);
+        await handle.writeFile(payload, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+    }
+    catch (err) {
+        if (handle !== undefined) {
+            await handle.close().catch(() => undefined);
+            handle = undefined;
+        }
+        await unlink(tmpPath).catch(() => undefined);
+        throw err;
+    }
+    // Claim the final slot atomically — link() fails with EEXIST if slot is
+    // already occupied, preserving first-signal-wins without replacing the file.
+    let outcome;
+    try {
+        await link(tmpPath, finalPath);
+        outcome = "created";
+    }
+    catch (err) {
+        if (err.code === "EEXIST") {
+            outcome = "already_exists";
+        }
+        else {
+            throw err;
+        }
+    }
+    finally {
+        await unlink(tmpPath).catch(() => undefined);
+        // Best-effort directory sync so the new entry is durable on POSIX.
+        // Windows directories cannot be opened with O_RDONLY — skip.
+        if (process.platform !== "win32") {
+            const dh = await open(sigDir, "r").catch(() => undefined);
+            if (dh !== undefined) {
+                await dh.sync().catch(() => undefined);
+                await dh.close().catch(() => undefined);
+            }
+        }
+    }
+    return outcome;
+}
+/**
+ * Read all present signals for a run (both kinds).  Returns a structured
+ * result with any parse diagnostics rather than throwing on malformed files.
+ */
+export async function readAllExitSignals(runsRoot, runId) {
+    const kinds = [
+        "human_interrupt",
+        "external_event"
+    ];
+    const signals = [];
+    const diagnostics = [];
+    for (const kind of kinds) {
+        const result = await readOneSignal(runsRoot, runId, kind);
+        if (result.signal !== undefined)
+            signals.push(result.signal);
+        if (result.diagnostic !== undefined)
+            diagnostics.push(result.diagnostic);
+    }
+    return { signals, diagnostics };
+}
+/** Read a single signal kind; returns undefined when absent. */
+export async function readExitSignal(runsRoot, runId, kind) {
+    const { signal } = await readOneSignal(runsRoot, runId, kind);
+    return signal;
+}
+export function createFileExitSignalSource(runsRoot) {
+    return {
+        poll: async (runId) => readAllExitSignals(runsRoot, runId)
+    };
+}
+/**
+ * Polls for any exit signal and calls onSignal with the full set when any
+ * new signal appears.  Returns a dispose function — MUST be called on every
+ * return/throw path in the run harness (invariant: one interval per run).
+ *
+ * Diagnostics (malformed signals, containment failures) are routed to
+ * onDiagnostic when provided; otherwise surfaced as a SignalDiagnosticError
+ * through onError so callers always learn about corruption rather than
+ * silently treating it as "no signal".
+ */
+export function startExitSignalMonitor(input) {
+    if (input.source === undefined)
+        return () => undefined;
+    const intervalMs = input.pollIntervalMs ?? 250;
+    let polling = false;
+    let lastCount = 0;
+    const timer = setInterval(() => {
+        if (polling || input.controller.signal.aborted)
+            return;
+        polling = true;
+        void input.source
+            .poll(input.runId)
+            .then(({ signals, diagnostics }) => {
+            if (input.controller.signal.aborted)
+                return;
+            // Surface diagnostics without aborting the run
+            if (diagnostics.length > 0) {
+                if (input.onDiagnostic !== undefined) {
+                    input.onDiagnostic(diagnostics);
+                }
+                else {
+                    input.onError(new SignalDiagnosticError(diagnostics));
+                }
+            }
+            // Only fire onSignal when new signals appear
+            if (signals.length > lastCount) {
+                lastCount = signals.length;
+                input.onSignal(signals);
+                input.controller.abort(signals);
+            }
+        })
+            .catch((err) => {
+            const e = err instanceof Error ? err : new Error(String(err));
+            input.onError(e);
+            input.controller.abort(e);
+        })
+            .finally(() => { polling = false; });
+    }, intervalMs);
+    timer.unref?.();
+    return () => clearInterval(timer);
+}
+// ─── Internal helpers ────────────────────────────────────────────────────────
+async function readOneSignal(runsRoot, runId, kind) {
+    assertRunId(runId);
+    const finalPath = exitSignalPath(runsRoot, runId, kind);
+    const sigDir = dirname(finalPath);
+    // Real-path containment for reads: signals dir must stay inside the run store.
+    // ENOENT on the signals dir means no signals have been written — return absent.
+    let realSigDir;
+    try {
+        realSigDir = await realpath(sigDir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return {};
+        return {
+            diagnostic: {
+                kind,
+                error: `containment check failed [${err.code ?? "ERR"}]`
+            }
+        };
+    }
+    const realRoot = await realpath(resolve(runsRoot));
+    if (!isContained(realRoot, realSigDir)) {
+        return { diagnostic: { kind, error: "signal directory escapes the run store" } };
+    }
+    // lstat: reject symlinks and surface size violations before reading.
+    // With atomic publication, the final file is always a complete hardlinked
+    // inode — a size=0 or a symlink indicates tampering.
+    let size;
+    try {
+        const lstats = await lstat(finalPath);
+        if (lstats.isSymbolicLink()) {
+            return { diagnostic: { kind, error: "signal file is a symbolic link" } };
+        }
+        size = lstats.size;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return {};
+        return {
+            diagnostic: {
+                kind,
+                error: `stat error [${err.code ?? "ERR"}]`
+            }
+        };
+    }
+    if (size > MAX_SIGNAL_BYTES) {
+        return { diagnostic: { kind, error: "signal file exceeds 64 KiB" } };
+    }
+    let text;
+    try {
+        text = await readFile(finalPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return {};
+        return {
+            diagnostic: {
+                kind,
+                error: `read error [${err.code ?? "ERR"}]`
+            }
+        };
+    }
+    // With atomic publication the final file should always contain valid JSON.
+    // A parse failure indicates file corruption — surface as diagnostic.
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { diagnostic: { kind, error: "signal file contains invalid JSON" } };
+    }
+    try {
+        validateExitSignal(parsed);
+        return { signal: parsed };
+    }
+    catch (err) {
+        return { diagnostic: { kind, error: String(err) } };
+    }
+}
+function validateExitSignal(signal) {
+    if (signal.schemaVersion !== "exit-signal/1") {
+        throw new Error(`Unsupported exit signal schema: ${String(signal.schemaVersion)}`);
+    }
+    assertRunId(signal.runId);
+    if (signal.kind !== "human_interrupt" && signal.kind !== "external_event") {
+        throw new Error(`Invalid exit signal kind: ${String(signal.kind)}`);
+    }
+    if (!signal.requestedBy?.trim() || !Number.isFinite(Date.parse(signal.requestedAt))) {
+        throw new Error("Exit signal requester and timestamp are required");
+    }
+    if (signal.kind === "external_event" && signal.externalEvent === undefined) {
+        throw new Error("external_event signal requires externalEvent evidence");
+    }
+    if (signal.externalEvent !== undefined) {
+        const ev = signal.externalEvent;
+        if (!ev.source?.trim() || !ev.event?.trim()) {
+            throw new Error("External event source and event are required");
+        }
+        if (!["satisfied", "superseded", "cancelled"].includes(ev.disposition)) {
+            throw new Error(`Invalid external event disposition: ${String(ev.disposition)}`);
+        }
+        if (!Number.isFinite(Date.parse(ev.observedAt))) {
+            throw new Error("External event observedAt must be an ISO timestamp");
+        }
+    }
+}
+function assertRunId(runId) {
+    if (runId === "." ||
+        runId === ".." ||
+        !RUN_ID_RE.test(runId) ||
+        basename(runId) !== runId) {
+        throw new Error(`Invalid run id: ${JSON.stringify(runId)}`);
+    }
+}
+/** True when candidate equals root or is a strict descendant under root. */
+function isContained(root, candidate) {
+    const sep = process.platform === "win32" ? "\\" : "/";
+    return candidate === root || candidate.startsWith(`${root}${sep}`);
+}

package/dist/vendor/core/exits.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Eight-Exit Runtime — pure deterministic evaluator.
+ *
+ * EXIT_PRECEDENCE rationale (product decision — see contracts/exits.ts for rationale;
+ * any change to this array requires updating that paragraph in the same commit):
+ *   human_interrupt > external_event > wall_clock > budget_cap > turn_cap >
+ *   goal_met > error_threshold > no_progress
+ */
+import type { ExitEvaluationV1, ExitPolicyV1, ExitSnapshotV1, LoopBudget, LoopLifecycleState, LoopStatus } from "../contracts/index.js";
+export interface LegacyExitDecision {
+    shouldExit: boolean;
+    lifecycleState: LoopLifecycleState;
+    status: LoopStatus;
+    reason: string;
+    reasonCode?: string;
+    failureClass?: string;
+    safetySurface?: string;
+    exitEvaluation: ExitEvaluationV1;
+}
+export interface ExitPolicyOverrides {
+    goal?: Partial<ExitPolicyV1["goal"]>;
+    turns?: Partial<ExitPolicyV1["turns"]>;
+    budget?: Partial<ExitPolicyV1["budget"]>;
+    wallClock?: Partial<ExitPolicyV1["wallClock"]>;
+    progress?: Partial<ExitPolicyV1["progress"]>;
+    errors?: Partial<ExitPolicyV1["errors"]>;
+    humanInterrupt?: Partial<ExitPolicyV1["humanInterrupt"]>;
+    externalEvent?: Partial<ExitPolicyV1["externalEvent"]>;
+}
+export declare function createDefaultExitPolicy(budget: LoopBudget, overrides?: ExitPolicyOverrides): ExitPolicyV1;
+export declare function validateExitPolicy(policy: ExitPolicyV1): void;
+export declare function evaluateExitPolicy(policy: ExitPolicyV1, snapshot: ExitSnapshotV1): ExitEvaluationV1;
+export declare function toLegacyExitDecision(evaluation: ExitEvaluationV1, externalDisposition?: "satisfied" | "superseded" | "cancelled"): LegacyExitDecision;
+/**
+ * Hash the meaningful workspace/verification state for no-progress detection.
+ * Excludes timestamps, cost counters, prose summaries — only structural changes count.
+ */
+export declare function hashProgressState(value: unknown): string;
+/** @deprecated Use evaluateExitPolicy instead. Retained for downstream compatibility. */
+export { inferExitCompat as inferExitCompat };
+declare function inferExitCompat(_unused: unknown): never;