@martinloop/mcp 0.3.9 → 0.5.0

package/dist/vendor/core/delivery/message-schema.js

@@ -0,0 +1,111 @@
+import { ALLOWED_ACTION_TYPES, DELIVERY_MESSAGE_SCHEMA_VERSION, MESSAGE_SELECTION_RESPONSE_SCHEMA_VERSION, } from "../../contracts/index.js";
+const MAX_RESPONSE_BYTES = 8_192;
+const MAX_TITLE_LENGTH = 120;
+const MAX_BODY_LENGTH = 500;
+const MAX_ID_LENGTH = 128;
+const ALLOWED_ACTION_SET = new Set(ALLOWED_ACTION_TYPES);
+/**
+ * Parse and validate a raw response body from the message selection endpoint.
+ * Returns ok:false on any violation — caller must render nothing and log the error.
+ */
+export function parseMessageSelectionResponse(raw) {
+    if (Buffer.byteLength(raw, "utf8") > MAX_RESPONSE_BYTES) {
+        return { ok: false, error: "schema_response_too_large" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, error: "schema_malformed" };
+    }
+    if (!isObject(parsed)) {
+        return { ok: false, error: "schema_malformed" };
+    }
+    if (parsed["schemaVersion"] !== MESSAGE_SELECTION_RESPONSE_SCHEMA_VERSION) {
+        return { ok: false, error: "schema_version_unknown", detail: String(parsed["schemaVersion"]) };
+    }
+    if (!("message" in parsed) || parsed["message"] === undefined || parsed["message"] === null) {
+        return { ok: true, message: undefined };
+    }
+    const result = validateMessage(parsed["message"]);
+    if (!result.ok)
+        return result;
+    return { ok: true, message: result.message };
+}
+function validateMessage(raw) {
+    if (!isObject(raw)) {
+        return { ok: false, error: "schema_malformed" };
+    }
+    if (raw["schemaVersion"] !== DELIVERY_MESSAGE_SCHEMA_VERSION) {
+        return { ok: false, error: "schema_version_unknown", detail: String(raw["schemaVersion"]) };
+    }
+    const id = raw["id"];
+    if (typeof id !== "string" || id.length === 0 || id.length > MAX_ID_LENGTH || !/^[\w\-.:]+$/.test(id)) {
+        return { ok: false, error: "schema_invalid_id" };
+    }
+    const kind = raw["kind"];
+    if (kind !== "update" && kind !== "feedback_request" && kind !== "milestone") {
+        return { ok: false, error: "schema_unknown_kind", detail: String(kind) };
+    }
+    const revision = raw["revision"];
+    if (typeof revision !== "number" || !Number.isInteger(revision) || revision < 0) {
+        return { ok: false, error: "schema_malformed", detail: "revision" };
+    }
+    const title = raw["title"];
+    if (typeof title !== "string" || title.length === 0 || title.length > MAX_TITLE_LENGTH) {
+        return { ok: false, error: "schema_text_too_long", detail: "title" };
+    }
+    const body = raw["body"];
+    if (typeof body !== "string" || body.length === 0 || body.length > MAX_BODY_LENGTH) {
+        return { ok: false, error: "schema_text_too_long", detail: "body" };
+    }
+    const action = raw["action"];
+    if (!isObject(action)) {
+        return { ok: false, error: "schema_malformed", detail: "action" };
+    }
+    const actionType = action["type"];
+    if (typeof actionType !== "string" || !ALLOWED_ACTION_SET.has(actionType)) {
+        return { ok: false, error: "schema_unknown_action_type", detail: String(actionType) };
+    }
+    if ("url" in action && action["url"] !== undefined) {
+        if (typeof action["url"] !== "string" || !action["url"].startsWith("https://")) {
+            return { ok: false, error: "schema_url_not_https" };
+        }
+    }
+    if ("targetVersion" in action && action["targetVersion"] !== undefined) {
+        if (typeof action["targetVersion"] !== "string") {
+            return { ok: false, error: "schema_malformed", detail: "targetVersion" };
+        }
+    }
+    const expiresAt = raw["expiresAt"];
+    if (typeof expiresAt !== "string" || isNaN(Date.parse(expiresAt))) {
+        return { ok: false, error: "schema_invalid_date", detail: "expiresAt" };
+    }
+    const cooldownHours = raw["cooldownHours"];
+    if (typeof cooldownHours !== "number" ||
+        !Number.isFinite(cooldownHours) ||
+        cooldownHours < 0 ||
+        cooldownHours > 8760) {
+        return { ok: false, error: "schema_invalid_cooldown" };
+    }
+    const message = {
+        schemaVersion: DELIVERY_MESSAGE_SCHEMA_VERSION,
+        id,
+        revision,
+        kind,
+        title,
+        body,
+        action: {
+            type: actionType,
+            ...(action["url"] !== undefined ? { url: action["url"] } : {}),
+            ...(action["targetVersion"] !== undefined ? { targetVersion: action["targetVersion"] } : {}),
+        },
+        expiresAt,
+        cooldownHours,
+    };
+    return { ok: true, message };
+}
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}

package/dist/vendor/core/delivery/update-check.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns the installed version of the CLI package (`martin-loop`).
+ * Call site: CLI only. Never call from MCP.
+ */
+export declare function getCliInstalledVersion(): string | null;
+/**
+ * Returns the installed version of the MCP package (`@martinloop/mcp`).
+ * Call site: MCP only. Never call from CLI.
+ */
+export declare function getMcpInstalledVersion(): string | null;
+/**
+ * Compare two semver strings. Returns true when `available` is strictly
+ * newer than `current`.
+ *
+ * Prereleases are never surfaced as updates unless the user's current
+ * version is itself a prerelease (semver prerelease protection).
+ * Build metadata (+build) does not affect precedence.
+ */
+export declare function isNewerVersion(current: string, available: string): boolean;

package/dist/vendor/core/delivery/update-check.js

@@ -0,0 +1,107 @@
+import { createRequire } from "node:module";
+// CLI and MCP version checks are intentionally independent — they use different
+// package names and must never share a constant or resolve function.
+/**
+ * Returns the installed version of the CLI package (`martin-loop`).
+ * Call site: CLI only. Never call from MCP.
+ */
+export function getCliInstalledVersion() {
+    return resolvePackageVersion("martin-loop");
+}
+/**
+ * Returns the installed version of the MCP package (`@martinloop/mcp`).
+ * Call site: MCP only. Never call from CLI.
+ */
+export function getMcpInstalledVersion() {
+    return resolvePackageVersion("@martinloop/mcp");
+}
+/**
+ * Compare two semver strings. Returns true when `available` is strictly
+ * newer than `current`.
+ *
+ * Prereleases are never surfaced as updates unless the user's current
+ * version is itself a prerelease (semver prerelease protection).
+ * Build metadata (+build) does not affect precedence.
+ */
+export function isNewerVersion(current, available) {
+    const currentVersion = parseSemver(current);
+    const availableVersion = parseSemver(available);
+    if (!currentVersion || !availableVersion)
+        return false;
+    // Stable users must never be offered a prerelease.
+    if (currentVersion.prerelease.length === 0 &&
+        availableVersion.prerelease.length > 0) {
+        return false;
+    }
+    return compareSemver(availableVersion, currentVersion) > 0;
+}
+function resolvePackageVersion(name) {
+    try {
+        const require = createRequire(import.meta.url);
+        const pkg = require(`${name}/package.json`);
+        return typeof pkg.version === "string" ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+function parseSemver(version) {
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(version);
+    if (!match)
+        return null;
+    const prerelease = [];
+    for (const identifier of match[4]?.split(".") ?? []) {
+        if (/^\d+$/.test(identifier)) {
+            // Leading zeros on numeric identifiers are invalid per SemVer spec.
+            if (identifier.length > 1 && identifier.startsWith("0"))
+                return null;
+            prerelease.push(Number(identifier));
+        }
+        else {
+            prerelease.push(identifier);
+        }
+    }
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease,
+    };
+}
+/**
+ * Returns a positive number if left > right, negative if left < right, 0 if equal.
+ * Implements SemVer 2.0.0 precedence rules exactly.
+ */
+function compareSemver(left, right) {
+    for (const key of ["major", "minor", "patch"]) {
+        if (left[key] !== right[key])
+            return left[key] > right[key] ? 1 : -1;
+    }
+    // When base versions are equal: stable (no prerelease) > prerelease.
+    if (left.prerelease.length === 0 && right.prerelease.length === 0)
+        return 0;
+    if (left.prerelease.length === 0)
+        return 1;
+    if (right.prerelease.length === 0)
+        return -1;
+    // Both have prereleases — compare identifier by identifier.
+    const length = Math.max(left.prerelease.length, right.prerelease.length);
+    for (let index = 0; index < length; index++) {
+        const a = left.prerelease[index];
+        const b = right.prerelease[index];
+        if (a === undefined)
+            return -1; // fewer identifiers = lower precedence
+        if (b === undefined)
+            return 1;
+        if (a === b)
+            continue;
+        if (typeof a === "number" && typeof b === "number")
+            return a > b ? 1 : -1;
+        if (typeof a === "number")
+            return -1; // numeric < alphanumeric
+        if (typeof b === "number")
+            return 1;
+        return a > b ? 1 : -1; // both alphanumeric: lexicographic
+    }
+    return 0;
+}

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}`);
+}