@martinloop/mcp 0.8.9 → 0.9.0

package/dist/tools/run-controls.js

@@ -1,85 +1,955 @@
-import { appendFile, readFile } from "node:fs/promises";
+import { createHash, randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { link, lstat, open, realpath, unlink } from "node:fs/promises";
+import { hostname } from "node:os";
 import path from "node:path";
-import { invalidArgumentsError, unsupportedOperationError } from "./tool-errors.js";
+import { readExitSignal, readActiveRunExecutionLease, writeExitSignal } from "../vendor/core/index.js";
+import { invalidArgumentsError, storeUnreadableError, unsupportedOperationError } from "./tool-errors.js";
 import { loadDetailedLoopRecord } from "./run-store.js";
-export async function createRunControlReceipt(action, input) {
-    const detail = await loadDetailedLoopRecord(input);
+export async function createRunControlReceipt(action, input, testHooks) {
+    if (input.authority?.transport !== "local_stdio") {
+        throw unsupportedOperationError("Run controls are available only over the local stdio transport.", "Use a local MartinLoop MCP stdio session; remote HTTP control requires authenticated principal support.");
+    }
+    const initialDetail = await loadDetailedLoopRecord(input);
+    if (!initialDetail.canonicalRunDirectory) {
+        throw unsupportedOperationError("Run control receipts require a canonical run directory.", "Use a canonical loopId-backed Martin run before writing control receipts.");
+    }
+    return withRunControlLock(initialDetail.canonicalRunDirectory, async () => {
+        await testHooks?.beforeLockedReload?.();
+        const detail = await loadDetailedLoopRecord(input);
+        if (detail.canonicalRunDirectory !== initialDetail.canonicalRunDirectory) {
+            throw controlReceiptIntegrityError();
+        }
+        return createRunControlReceiptLocked(action, input, detail, testHooks);
+    }, testHooks?.lockMaxRetries);
+}
+async function createRunControlReceiptLocked(action, input, detail, _testHooks) {
     if (!detail.canonicalRunDirectory) {
         throw unsupportedOperationError("Run control receipts require a canonical run directory.", "Use a canonical loopId-backed Martin run before writing control receipts.");
     }
-    const receipt = {
+    if (isTerminalRun(detail.loop)) {
+        throw unsupportedOperationError(`Run ${detail.loop.loopId} is already terminal and cannot accept ${action}.`, "Inspect the terminal run evidence instead of recording a new control request.");
+    }
+    if (await readRunTerminalIntent(detail.canonicalRunDirectory, detail.loop.loopId)) {
+        throw unsupportedOperationError(`Run ${detail.loop.loopId} is entering terminal persistence and cannot accept ${action}.`, "Inspect the terminal run evidence instead of recording a new control request.");
+    }
+    const executionLease = await readActiveRunExecutionLease({
+        runsRoot: detail.runsRoot,
+        runId: detail.loop.loopId
+    }).catch(() => undefined);
+    if (!executionLease) {
+        throw unsupportedOperationError(`Run ${detail.loop.loopId} has no live control-capable executor lease.`, "Start or resume the run through a supported MartinLoop executor before requesting controls.");
+    }
+    const priorState = await readRunControlStateUnlocked(detail);
+    const priorCancellation = priorState.receipts.find((candidate) => candidate.action === "cancel");
+    if (action === "cancel" && priorCancellation) {
+        return publishCancellation(detail, priorCancellation, priorState, _testHooks);
+    }
+    if (action === "pause" && priorState.requestedState === "paused") {
+        throw unsupportedOperationError("The run already has a pending pause request.", "Continue the existing pause before requesting another pause.");
+    }
+    if (action === "pause" && priorState.appliedState === "paused") {
+        throw unsupportedOperationError("The previous pause is still applied by the executor.", "Wait until the matching continue application is visible before requesting another pause.");
+    }
+    if (action !== "cancel" && priorState.requestedState === "cancellation_requested") {
+        throw unsupportedOperationError("The run already has a cancellation request.", "Wait for the active executor to record terminal cancellation evidence.");
+    }
+    const expectedPreviousControlId = action === "continue"
+        ? requirePendingPauseControlId(priorState)
+        : undefined;
+    const unsignedReceipt = {
+        schemaVersion: "martin.run-control.v2",
         controlId: `ctl_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
         loopId: detail.loop.loopId,
         action,
-        requestedAt: new Date().toISOString(),
+        requestedAt: nextControlRequestedAt(priorState),
+        authorityBoundary: "local_os_user",
+        principal: "local_mcp_client",
+        executorLeaseToken: executionLease.lease.token,
+        ...(typeof detail.loop.workspaceId === "string" ? { workspaceId: detail.loop.workspaceId } : {}),
+        ...(expectedPreviousControlId ? { expectedPreviousControlId } : {}),
         ...(input.reason ? { reason: input.reason } : {}),
-        ...(input.requestedBy ? { requestedBy: input.requestedBy } : {})
+        ...(priorState.receipts.at(-1)?.receiptHash
+            ? { previousReceiptHash: priorState.receipts.at(-1).receiptHash }
+            : {})
+    };
+    const receipt = {
+        ...unsignedReceipt,
+        receiptHash: hashCanonical(unsignedReceipt)
     };
+    const currentDetail = await loadDetailedLoopRecord(input);
+    if (currentDetail.canonicalRunDirectory !== detail.canonicalRunDirectory ||
+        isTerminalRun(currentDetail.loop) ||
+        await readRunTerminalIntent(detail.canonicalRunDirectory, detail.loop.loopId)) {
+        throw unsupportedOperationError(`Run ${detail.loop.loopId} is already terminal and cannot accept ${action}.`, "Inspect the terminal run evidence instead of recording a new control request.");
+    }
+    const currentLease = await readActiveRunExecutionLease({
+        runsRoot: currentDetail.runsRoot,
+        runId: currentDetail.loop.loopId
+    });
+    if (currentLease?.lease.token !== executionLease.lease.token) {
+        throw controlReceiptIntegrityError();
+    }
     const receiptPath = path.join(detail.canonicalRunDirectory, "controls.jsonl");
-    await appendFile(receiptPath, `${JSON.stringify(receipt)}\n`, "utf8");
-    const state = await readRunControlState(detail);
+    await safeAppendJournal(detail.canonicalRunDirectory, receiptPath, `${JSON.stringify(receipt)}\n`, _testHooks?.afterJournalOpen);
+    const receiptState = await readRunControlStateUnlocked(detail);
+    if (action === "cancel") {
+        return publishCancellation(detail, receipt, receiptState, _testHooks);
+    }
+    const latestDetail = await loadDetailedLoopRecord(input);
+    const state = await readRunControlStateUnlocked(latestDetail);
+    const terminal = isTerminalRun(latestDetail.loop);
     return {
         ok: true,
-        summary: action === "cancel"
-            ? `Cancellation request recorded for ${detail.loop.loopId}.`
+        summary: terminal
+            ? `Run ${detail.loop.loopId} became terminal while the control was recorded; terminal evidence wins.`
             : action === "pause"
-                ? `Pause request recorded for ${detail.loop.loopId}.`
-                : `Continue request recorded for ${detail.loop.loopId}.`,
+                ? `Pause requested for ${detail.loop.loopId}; application waits for the next safe attempt boundary.`
+                : `Continue request bound to pause ${expectedPreviousControlId} for ${detail.loop.loopId}.`,
         loopId: detail.loop.loopId,
         requestedAction: action,
         state,
         action: receipt.action,
         controlId: receipt.controlId,
         requestedAt: receipt.requestedAt,
+        publicationState: "receipt_recorded",
+        applicationState: terminal ? "terminal_reconciled" : "requested_only",
         ...(receipt.reason ? { reason: receipt.reason } : {}),
-        ...(receipt.requestedBy ? { requestedBy: receipt.requestedBy } : {})
+        authorityBoundary: receipt.authorityBoundary,
+        principal: receipt.principal,
+        receiptHash: receipt.receiptHash
+    };
+}
+async function publishCancellation(detail, receipt, state, testHooks) {
+    const existingPublication = state.publications.find((candidate) => candidate.controlId === receipt.controlId);
+    const expectedSignal = {
+        schemaVersion: "exit-signal/1",
+        kind: "human_interrupt",
+        runId: detail.loop.loopId,
+        requestedAt: receipt.requestedAt,
+        requestedBy: "local_mcp_client",
+        reason: receipt.reason ?? "Cancellation requested through martin_cancel."
+    };
+    // A publication receipt never substitutes for the canonical signal. This
+    // repairs a missing signal and fails closed if first-writer-wins preserved a
+    // different signal payload in the canonical slot.
+    const signalState = await writeExitSignal(detail.runsRoot, expectedSignal);
+    const durableSignal = await readExitSignal(detail.runsRoot, detail.loop.loopId, "human_interrupt");
+    if (!durableSignal ||
+        durableSignal.schemaVersion !== expectedSignal.schemaVersion ||
+        durableSignal.kind !== expectedSignal.kind ||
+        durableSignal.runId !== expectedSignal.runId ||
+        durableSignal.requestedAt !== expectedSignal.requestedAt ||
+        durableSignal.requestedBy !== expectedSignal.requestedBy ||
+        durableSignal.reason !== expectedSignal.reason) {
+        throw controlReceiptIntegrityError();
+    }
+    let publicationState = "already_requested";
+    if (!existingPublication) {
+        const previous = state.publications.at(-1);
+        const unsigned = {
+            schemaVersion: "martin.run-control-publication.v1",
+            loopId: receipt.loopId,
+            controlId: receipt.controlId,
+            receiptHash: receipt.receiptHash,
+            signalState,
+            recordedAt: new Date().toISOString(),
+            ...(previous ? { previousPublicationHash: previous.publicationHash } : {})
+        };
+        const publication = {
+            ...unsigned,
+            publicationHash: hashCanonical(unsigned)
+        };
+        try {
+            await safeAppendJournal(detail.canonicalRunDirectory, path.join(detail.canonicalRunDirectory, "control-publications.jsonl"), `${JSON.stringify(publication)}\n`, testHooks?.afterJournalOpen);
+            publicationState = signalState === "created" ? "published" : "already_requested";
+        }
+        catch {
+            publicationState = "published_audit_pending";
+        }
+    }
+    const currentDetail = await loadDetailedLoopRecord({
+        loopId: detail.loop.loopId,
+        runsDir: detail.runsRoot
+    });
+    const currentState = await readRunControlStateUnlocked(currentDetail);
+    const terminal = isTerminalRun(currentDetail.loop) || currentState.requestedState === "terminal";
+    return {
+        ok: true,
+        summary: terminal
+            ? `Run ${detail.loop.loopId} is terminal; terminal evidence wins over pending cancellation state.`
+            : publicationState === "published_audit_pending"
+                ? `Cancellation signal is live for ${detail.loop.loopId}; publication audit is pending a safe retry.`
+                : `Cancellation signal is authoritative for ${detail.loop.loopId}; executor observation is pending.`,
+        loopId: detail.loop.loopId,
+        requestedAction: "cancel",
+        state: currentState,
+        action: "cancel",
+        controlId: receipt.controlId,
+        requestedAt: receipt.requestedAt,
+        publicationState,
+        applicationState: terminal ? "terminal_reconciled" : "pending_observation",
+        ...(receipt.reason ? { reason: receipt.reason } : {}),
+        authorityBoundary: receipt.authorityBoundary,
+        principal: receipt.principal,
+        receiptHash: receipt.receiptHash
     };
 }
 export async function readRunControlState(detailOrInput) {
     const detail = isDetailedLoopSource(detailOrInput)
         ? detailOrInput
         : await loadDetailedLoopRecord(detailOrInput);
+    return detail.canonicalRunDirectory
+        ? withRunControlLock(detail.canonicalRunDirectory, () => readRunControlStateUnlocked(detail))
+        : readRunControlStateUnlocked(detail);
+}
+async function readRunControlStateUnlocked(detail) {
     const receiptPath = detail.canonicalRunDirectory
         ? path.join(detail.canonicalRunDirectory, "controls.jsonl")
         : undefined;
-    const receipts = receiptPath ? await readControlReceipts(receiptPath) : [];
+    const receipts = receiptPath
+        ? await readControlReceipts(receiptPath, detail.loop.loopId)
+        : [];
+    const applicationPath = detail.canonicalRunDirectory
+        ? path.join(detail.canonicalRunDirectory, "control-applications.jsonl")
+        : undefined;
+    const applications = applicationPath
+        ? await readRunControlApplications(applicationPath, detail.loop.loopId)
+        : [];
+    const publicationPath = detail.canonicalRunDirectory
+        ? path.join(detail.canonicalRunDirectory, "control-publications.jsonl")
+        : undefined;
+    const publications = publicationPath
+        ? await readRunControlPublications(publicationPath, detail.loop.loopId)
+        : [];
+    const terminalIntent = detail.canonicalRunDirectory
+        ? await readRunTerminalIntent(detail.canonicalRunDirectory, detail.loop.loopId)
+        : undefined;
     const latestReceipt = receipts.at(-1);
+    const snapshot = resolveRunControlSnapshot(receipts);
+    const reconciledAppliedState = reconcileRunControlApplications(receipts, applications);
+    reconcileRunControlPublications(receipts, publications);
     return {
-        requestedState: latestReceipt?.action === "pause"
-            ? "paused"
+        requestedState: isTerminalRun(detail.loop) || terminalIntent !== undefined
+            ? "terminal"
             : latestReceipt?.action === "cancel"
                 ? "cancellation_requested"
-                : "active",
+                : snapshot.pause
+                    ? "paused"
+                    : "active",
         ...(latestReceipt ? { latestReceipt } : {}),
-        approvalState: latestReceipt?.action === "pause" ? "resume_requested" : "not_required",
+        approvalState: "not_required",
+        appliedState: isTerminalRun(detail.loop) || terminalIntent !== undefined
+            ? "terminal"
+            : latestReceipt?.action === "cancel"
+                ? "cancellation_pending"
+                : reconciledAppliedState,
         receipts,
-        ...(receiptPath ? { receiptPath } : {})
+        applications,
+        publications,
+        ...(receiptPath ? { receiptPath } : {}),
+        ...(applicationPath ? { applicationPath } : {})
+    };
+}
+function reconcileRunControlPublications(receipts, publications) {
+    const receiptsById = new Map(receipts.map((receipt) => [receipt.controlId, receipt]));
+    const seen = new Set();
+    for (const publication of publications) {
+        if (seen.has(publication.controlId))
+            throw controlReceiptIntegrityError();
+        seen.add(publication.controlId);
+        const receipt = receiptsById.get(publication.controlId);
+        if (receipt?.action !== "cancel" ||
+            publication.loopId !== receipt.loopId ||
+            publication.receiptHash !== receipt.receiptHash) {
+            throw controlReceiptIntegrityError();
+        }
+    }
+}
+export function createFileRunControlSource(runsRoot) {
+    return {
+        async poll(runId) {
+            const runDirectory = path.join(runsRoot, runId);
+            const runDirectoryEntry = await lstat(runDirectory).catch((error) => {
+                if (isNodeError(error, "ENOENT"))
+                    return undefined;
+                throw storeUnreadableError();
+            });
+            if (!runDirectoryEntry)
+                return {};
+            if (!runDirectoryEntry.isDirectory() || runDirectoryEntry.isSymbolicLink()) {
+                throw controlReceiptIntegrityError();
+            }
+            return withRunControlLock(runDirectory, async () => {
+                if (await readRunTerminalIntent(runDirectory, runId))
+                    return {};
+                const receipts = await readControlReceipts(path.join(runDirectory, "controls.jsonl"), runId);
+                return resolveRunControlSnapshot(receipts);
+            });
+        },
+        async recordApplication(application) {
+            const runDirectory = path.join(runsRoot, application.loopId);
+            await withRunControlLock(runDirectory, async () => {
+                const receiptPath = path.join(runDirectory, "controls.jsonl");
+                const applicationPath = path.join(runDirectory, "control-applications.jsonl");
+                const receipts = await readControlReceipts(receiptPath, application.loopId);
+                resolveRunControlSnapshot(receipts);
+                const existing = await readRunControlApplications(applicationPath, application.loopId);
+                reconcileRunControlApplications(receipts, existing);
+                if (existing.some((candidate) => candidate.controlId === application.controlId &&
+                    candidate.action === application.action)) {
+                    return;
+                }
+                const previousApplicationHash = existing.at(-1)?.applicationHash;
+                const unsigned = {
+                    schemaVersion: "martin.run-control-application.v2",
+                    ...application,
+                    ...(previousApplicationHash ? { previousApplicationHash } : {})
+                };
+                const stored = {
+                    ...unsigned,
+                    applicationHash: hashCanonical(unsigned)
+                };
+                reconcileRunControlApplications(receipts, [...existing, stored]);
+                await safeAppendJournal(runDirectory, applicationPath, `${JSON.stringify(stored)}\n`);
+            });
+        },
+        async recordTerminalIntent(runId) {
+            const runDirectory = path.join(runsRoot, runId);
+            await withRunControlLock(runDirectory, async () => {
+                if (await readRunTerminalIntent(runDirectory, runId))
+                    return;
+                const unsigned = {
+                    schemaVersion: "martin.run-terminal-intent.v1",
+                    loopId: runId,
+                    recordedAt: new Date().toISOString()
+                };
+                const intent = {
+                    ...unsigned,
+                    intentHash: hashCanonical(unsigned)
+                };
+                await safeAppendJournal(runDirectory, path.join(runDirectory, "terminal-intent.jsonl"), `${JSON.stringify(intent)}\n`);
+            });
+        }
+    };
+}
+export function reconcileRunControlApplications(receipts, applications) {
+    const receiptPositions = new Map(receipts.map((receipt, index) => [receipt.controlId, { receipt, index }]));
+    const seenApplications = new Set();
+    let appliedPauseId;
+    let lastReceiptPosition = -1;
+    let lastAppliedAt = -Infinity;
+    for (const application of applications) {
+        const identity = `${application.action}:${application.controlId}`;
+        if (seenApplications.has(identity))
+            throw controlReceiptIntegrityError();
+        seenApplications.add(identity);
+        const matched = receiptPositions.get(application.controlId);
+        if (!matched || matched.index < lastReceiptPosition)
+            throw controlReceiptIntegrityError();
+        if (application.receiptHash !== matched.receipt.receiptHash) {
+            throw controlReceiptIntegrityError();
+        }
+        const appliedAt = Date.parse(application.appliedAt);
+        if (appliedAt < Date.parse(matched.receipt.requestedAt) || appliedAt < lastAppliedAt) {
+            throw controlReceiptIntegrityError();
+        }
+        if (receipts
+            .slice(matched.index + 1)
+            .some((receipt) => Date.parse(receipt.requestedAt) <= appliedAt)) {
+            throw controlReceiptIntegrityError();
+        }
+        if (application.action === "pause_applied") {
+            if (matched.receipt.action !== "pause" ||
+                application.relatedControlId !== undefined ||
+                appliedPauseId !== undefined) {
+                throw controlReceiptIntegrityError();
+            }
+            appliedPauseId = matched.receipt.controlId;
+        }
+        else {
+            if (matched.receipt.action !== "continue" ||
+                matched.receipt.expectedPreviousControlId !== application.relatedControlId ||
+                appliedPauseId !== application.relatedControlId) {
+                throw controlReceiptIntegrityError();
+            }
+            appliedPauseId = undefined;
+        }
+        lastReceiptPosition = matched.index;
+        lastAppliedAt = appliedAt;
+    }
+    return appliedPauseId ? "paused" : "active";
+}
+export function resolveRunControlSnapshot(receipts) {
+    let pause;
+    let continuedBy;
+    let cancellationRequested = false;
+    const controlIds = new Set();
+    let lastRequestedAt = -Infinity;
+    for (const receipt of receipts) {
+        if (controlIds.has(receipt.controlId))
+            throw controlReceiptIntegrityError();
+        controlIds.add(receipt.controlId);
+        const requestedAt = Date.parse(receipt.requestedAt);
+        if (requestedAt < lastRequestedAt)
+            throw controlReceiptIntegrityError();
+        lastRequestedAt = requestedAt;
+        if (receipt.action === "cancel") {
+            cancellationRequested = true;
+            pause = undefined;
+            continuedBy = undefined;
+            continue;
+        }
+        if (cancellationRequested) {
+            throw controlReceiptIntegrityError();
+        }
+        if (receipt.action === "pause") {
+            if (pause)
+                throw controlReceiptIntegrityError();
+            pause = receipt;
+            continuedBy = undefined;
+            continue;
+        }
+        if (!pause || receipt.expectedPreviousControlId !== pause.controlId) {
+            throw controlReceiptIntegrityError();
+        }
+        continuedBy = receipt;
+        pause = undefined;
+    }
+    return {
+        ...(pause ? { pause } : {}),
+        ...(!pause && continuedBy ? { continuedBy } : {})
     };
 }
-export async function readControlReceipts(receiptPath) {
+export async function readRunControlApplications(applicationPath, expectedLoopId) {
+    let contents;
+    try {
+        contents = await safeReadJournal(path.dirname(applicationPath), applicationPath);
+    }
+    catch (error) {
+        if (isFileNotFoundError(error))
+            return [];
+        throw controlReceiptIntegrityError();
+    }
+    const applications = [];
+    for (const line of contents.split(/\r?\n/u).map((value) => value.trim()).filter(Boolean)) {
+        let candidate;
+        try {
+            candidate = JSON.parse(line);
+        }
+        catch {
+            throw controlReceiptIntegrityError();
+        }
+        if (!isRunControlApplication(candidate, expectedLoopId)) {
+            throw controlReceiptIntegrityError();
+        }
+        const previous = applications.at(-1);
+        if (candidate.previousApplicationHash !== previous?.applicationHash) {
+            throw controlReceiptIntegrityError();
+        }
+        applications.push(candidate);
+    }
+    return applications;
+}
+export async function readControlReceipts(receiptPath, expectedLoopId) {
+    let contents;
+    try {
+        contents = await safeReadJournal(path.dirname(receiptPath), receiptPath);
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
+            return [];
+        }
+        throw storeUnreadableError();
+    }
+    const receipts = [];
+    for (const line of contents.split(/\r?\n/u).map((value) => value.trim()).filter(Boolean)) {
+        let candidate;
+        try {
+            candidate = JSON.parse(line);
+        }
+        catch {
+            throw controlReceiptIntegrityError();
+        }
+        if (!isRunControlReceipt(candidate)) {
+            throw controlReceiptIntegrityError();
+        }
+        if (expectedLoopId !== undefined && candidate.loopId !== expectedLoopId) {
+            throw controlReceiptIntegrityError();
+        }
+        const previous = receipts.at(-1);
+        if (candidate.previousReceiptHash !== previous?.receiptHash) {
+            throw controlReceiptIntegrityError();
+        }
+        receipts.push(candidate);
+    }
+    return receipts;
+}
+async function readRunControlPublications(publicationPath, expectedLoopId) {
+    let contents;
     try {
-        const contents = await readFile(receiptPath, "utf8");
-        return contents
-            .split(/\r?\n/u)
-            .map((line) => line.trim())
-            .filter(Boolean)
-            .map((line) => JSON.parse(line))
-            .filter(isRunControlReceipt);
+        contents = await safeReadJournal(path.dirname(publicationPath), publicationPath);
+    }
+    catch (error) {
+        if (isFileNotFoundError(error))
+            return [];
+        throw controlReceiptIntegrityError();
+    }
+    const publications = [];
+    for (const line of contents.split(/\r?\n/u).map((value) => value.trim()).filter(Boolean)) {
+        let candidate;
+        try {
+            candidate = JSON.parse(line);
+        }
+        catch {
+            throw controlReceiptIntegrityError();
+        }
+        if (!isRunControlPublication(candidate, expectedLoopId)) {
+            throw controlReceiptIntegrityError();
+        }
+        const previous = publications.at(-1);
+        if (candidate.previousPublicationHash !== previous?.publicationHash) {
+            throw controlReceiptIntegrityError();
+        }
+        publications.push(candidate);
+    }
+    return publications;
+}
+async function readRunTerminalIntent(runDirectory, expectedLoopId) {
+    const intentPath = path.join(runDirectory, "terminal-intent.jsonl");
+    let contents;
+    try {
+        contents = await safeReadJournal(runDirectory, intentPath);
+    }
+    catch (error) {
+        if (isFileNotFoundError(error))
+            return undefined;
+        throw controlReceiptIntegrityError();
+    }
+    const lines = contents.split(/\r?\n/u).map((value) => value.trim()).filter(Boolean);
+    if (lines.length !== 1)
+        throw controlReceiptIntegrityError();
+    let candidate;
+    try {
+        candidate = JSON.parse(lines[0]);
     }
     catch {
-        return [];
+        throw controlReceiptIntegrityError();
     }
+    if (typeof candidate !== "object" || candidate === null)
+        throw controlReceiptIntegrityError();
+    const intent = candidate;
+    if (!hasOnlyOwnKeys(intent, ["schemaVersion", "loopId", "recordedAt", "intentHash"]) ||
+        intent.schemaVersion !== "martin.run-terminal-intent.v1" ||
+        intent.loopId !== expectedLoopId ||
+        !isIsoTimestamp(intent.recordedAt) ||
+        !isSha256(intent.intentHash)) {
+        throw controlReceiptIntegrityError();
+    }
+    const { intentHash, ...unsigned } = intent;
+    if (intentHash !== hashCanonical(unsigned))
+        throw controlReceiptIntegrityError();
+    return intent;
 }
 function isDetailedLoopSource(value) {
     return typeof value === "object" && value !== null && "loop" in value && "runsRoot" in value;
 }
+function isTerminalRun(loop) {
+    return (loop.terminationEnvelope !== undefined ||
+        !["queued", "running", "verifying"].includes(loop.status) ||
+        !["created", "running", "verifying"].includes(loop.lifecycleState));
+}
 function isRunControlReceipt(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        typeof value.controlId === "string" &&
-        typeof value.loopId === "string" &&
-        typeof value.action === "string" &&
-        typeof value.requestedAt === "string");
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const candidate = value;
+    const structurallyValid = (hasOnlyOwnKeys(candidate, [
+        "schemaVersion",
+        "controlId",
+        "loopId",
+        "action",
+        "requestedAt",
+        "authorityBoundary",
+        "principal",
+        "executorLeaseToken",
+        "workspaceId",
+        "projectId",
+        "expectedPreviousControlId",
+        "reason",
+        "previousReceiptHash",
+        "receiptHash"
+    ]) &&
+        candidate.schemaVersion === "martin.run-control.v2" &&
+        isNonEmptyString(candidate.controlId) &&
+        isNonEmptyString(candidate.loopId) &&
+        isControlAction(candidate.action) &&
+        isIsoTimestamp(candidate.requestedAt) &&
+        (candidate.expectedPreviousControlId === undefined ||
+            isNonEmptyString(candidate.expectedPreviousControlId)) &&
+        (candidate.action === "continue"
+            ? isNonEmptyString(candidate.expectedPreviousControlId)
+            : candidate.expectedPreviousControlId === undefined) &&
+        candidate.authorityBoundary === "local_os_user" &&
+        candidate.principal === "local_mcp_client" &&
+        isNonEmptyString(candidate.executorLeaseToken) &&
+        (candidate.workspaceId === undefined || isNonEmptyString(candidate.workspaceId)) &&
+        (candidate.projectId === undefined || isNonEmptyString(candidate.projectId)) &&
+        (candidate.reason === undefined || isNonEmptyString(candidate.reason)) &&
+        (candidate.previousReceiptHash === undefined || isSha256(candidate.previousReceiptHash)) &&
+        isSha256(candidate.receiptHash));
+    if (!structurallyValid)
+        return false;
+    const { receiptHash, ...unsigned } = value;
+    return receiptHash === hashCanonical(unsigned);
+}
+function isRunControlApplication(value, expectedLoopId) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    const structurallyValid = (hasOnlyOwnKeys(candidate, [
+        "schemaVersion",
+        "loopId",
+        "controlId",
+        "action",
+        "appliedAt",
+        "relatedControlId",
+        "receiptHash",
+        "previousApplicationHash",
+        "applicationHash"
+    ]) &&
+        candidate.schemaVersion === "martin.run-control-application.v2" &&
+        isNonEmptyString(candidate.loopId) &&
+        (expectedLoopId === undefined || candidate.loopId === expectedLoopId) &&
+        isNonEmptyString(candidate.controlId) &&
+        (candidate.action === "pause_applied" || candidate.action === "continue_applied") &&
+        isIsoTimestamp(candidate.appliedAt) &&
+        (candidate.relatedControlId === undefined || isNonEmptyString(candidate.relatedControlId)) &&
+        (candidate.action === "continue_applied"
+            ? isNonEmptyString(candidate.relatedControlId)
+            : candidate.relatedControlId === undefined) &&
+        isSha256(candidate.receiptHash) &&
+        (candidate.previousApplicationHash === undefined || isSha256(candidate.previousApplicationHash)) &&
+        isSha256(candidate.applicationHash));
+    if (!structurallyValid)
+        return false;
+    const { applicationHash, ...unsigned } = value;
+    return applicationHash === hashCanonical(unsigned);
+}
+function isRunControlPublication(value, expectedLoopId) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    const structurallyValid = hasOnlyOwnKeys(candidate, [
+        "schemaVersion",
+        "loopId",
+        "controlId",
+        "receiptHash",
+        "signalState",
+        "recordedAt",
+        "previousPublicationHash",
+        "publicationHash"
+    ]) &&
+        candidate.schemaVersion === "martin.run-control-publication.v1" &&
+        candidate.loopId === expectedLoopId &&
+        isNonEmptyString(candidate.controlId) &&
+        isSha256(candidate.receiptHash) &&
+        (candidate.signalState === "created" || candidate.signalState === "already_exists") &&
+        isIsoTimestamp(candidate.recordedAt) &&
+        (candidate.previousPublicationHash === undefined || isSha256(candidate.previousPublicationHash)) &&
+        isSha256(candidate.publicationHash);
+    if (!structurallyValid)
+        return false;
+    const { publicationHash, ...unsigned } = value;
+    return publicationHash === hashCanonical(unsigned);
+}
+function requirePendingPauseControlId(state) {
+    const latest = state.latestReceipt;
+    if (latest?.action !== "pause") {
+        throw unsupportedOperationError("Continue requires one pending pause request.", "Pause the active run first, then continue the exact pause returned by MartinLoop.");
+    }
+    return latest.controlId;
+}
+function nextControlRequestedAt(state) {
+    let latestEvidenceMs = -Infinity;
+    for (const receipt of state.receipts) {
+        latestEvidenceMs = Math.max(latestEvidenceMs, Date.parse(receipt.requestedAt));
+    }
+    for (const application of state.applications) {
+        latestEvidenceMs = Math.max(latestEvidenceMs, Date.parse(application.appliedAt));
+    }
+    return new Date(Math.max(Date.now(), latestEvidenceMs + 1)).toISOString();
+}
+function isControlAction(value) {
+    return value === "pause" || value === "cancel" || value === "continue";
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function hasOnlyOwnKeys(value, allowedKeys) {
+    const allowed = new Set(allowedKeys);
+    return Object.keys(value).every((key) => allowed.has(key));
+}
+function isSha256(value) {
+    return typeof value === "string" && /^[a-f0-9]{64}$/u.test(value);
+}
+export function hashCanonical(value) {
+    return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+function isIsoTimestamp(value) {
+    return (isNonEmptyString(value) &&
+        Number.isFinite(Date.parse(value)) &&
+        new Date(value).toISOString() === value);
+}
+function isFileNotFoundError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function controlReceiptIntegrityError() {
+    return storeUnreadableError("Run control receipt integrity check failed.");
+}
+function sameFileIdentity(left, right) {
+    return String(left.dev) === String(right.dev) && String(left.ino) === String(right.ino);
+}
+async function assertSafeRunDirectory(runDirectory) {
+    const parentDirectory = path.dirname(runDirectory);
+    const parentEntry = await lstat(parentDirectory);
+    if (!parentEntry.isDirectory() || parentEntry.isSymbolicLink())
+        throw controlReceiptIntegrityError();
+    const entry = await lstat(runDirectory);
+    if (!entry.isDirectory() || entry.isSymbolicLink())
+        throw controlReceiptIntegrityError();
+    const canonical = path.resolve(await realpath(runDirectory));
+    const canonicalParent = path.resolve(await realpath(parentDirectory));
+    // Compare the leaf against the canonical parent rather than the lexical
+    // absolute path. macOS exposes /var through the trusted /private/var system
+    // alias; canonicalizing the parent preserves that platform behavior while
+    // still rejecting a linked runs-root or run-directory leaf.
+    const expected = path.join(canonicalParent, path.basename(runDirectory));
+    const isSamePath = process.platform === "win32"
+        ? canonical.toLowerCase() === expected.toLowerCase()
+        : canonical === expected;
+    if (!isSamePath) {
+        throw controlReceiptIntegrityError();
+    }
+}
+async function safeReadJournal(runDirectory, journalPath) {
+    await assertSafeRunDirectory(runDirectory);
+    const before = await lstat(journalPath);
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1) {
+        throw controlReceiptIntegrityError();
+    }
+    const handle = await open(journalPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const opened = await handle.stat();
+        if (!opened.isFile() || opened.nlink !== 1 || !sameFileIdentity(before, opened)) {
+            throw controlReceiptIntegrityError();
+        }
+        const contents = await handle.readFile({ encoding: "utf8" });
+        const after = await lstat(journalPath);
+        await assertSafeRunDirectory(runDirectory);
+        if (!after.isFile() || after.isSymbolicLink() || after.nlink !== 1 || !sameFileIdentity(opened, after)) {
+            throw controlReceiptIntegrityError();
+        }
+        return contents;
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function safeAppendJournal(runDirectory, journalPath, contents, afterOpen) {
+    await assertSafeRunDirectory(runDirectory);
+    const before = await lstat(journalPath).catch((error) => {
+        if (isNodeError(error, "ENOENT"))
+            return undefined;
+        throw error;
+    });
+    if (before && (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1)) {
+        throw controlReceiptIntegrityError();
+    }
+    const flags = constants.O_WRONLY | constants.O_APPEND | (constants.O_NOFOLLOW ?? 0) |
+        (before ? 0 : constants.O_CREAT | constants.O_EXCL);
+    const handle = await open(journalPath, flags, 0o600);
+    try {
+        const opened = await handle.stat();
+        if (!opened.isFile() || opened.nlink !== 1 || (before && !sameFileIdentity(before, opened))) {
+            throw controlReceiptIntegrityError();
+        }
+        await afterOpen?.(journalPath);
+        await handle.writeFile(contents, "utf8");
+        await handle.sync();
+        const after = await lstat(journalPath);
+        await assertSafeRunDirectory(runDirectory);
+        if (!after.isFile() || after.isSymbolicLink() || after.nlink !== 1 || !sameFileIdentity(opened, after)) {
+            throw controlReceiptIntegrityError();
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+const RUN_CONTROL_LOCK_RETRY_MS = 25;
+const RUN_CONTROL_LOCK_MAX_RETRIES = 200;
+async function withRunControlLock(runDirectory, operation, maxRetries = RUN_CONTROL_LOCK_MAX_RETRIES) {
+    await assertSafeRunDirectory(runDirectory);
+    const lockPath = path.join(runDirectory, ".run-control.lock");
+    const token = randomBytes(16).toString("hex");
+    let lockHandle;
+    let lease;
+    for (let attempt = 0; attempt < maxRetries; attempt += 1) {
+        try {
+            lockHandle = await open(lockPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+            const now = new Date().toISOString();
+            lease = {
+                schemaVersion: "martin.run-control-lock.v1",
+                token,
+                pid: process.pid,
+                hostname: hostname(),
+                acquiredAt: now,
+                heartbeatAt: now
+            };
+            await lockHandle.writeFile(`${JSON.stringify(lease)}\n`, "utf8");
+            await lockHandle.sync();
+            break;
+        }
+        catch (error) {
+            if (!isNodeError(error, "EEXIST"))
+                throw storeUnreadableError();
+            try {
+                const before = await lstat(lockPath);
+                if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1) {
+                    throw storeUnreadableError();
+                }
+                const raw = await safeReadJournal(runDirectory, lockPath);
+                const existing = JSON.parse(raw);
+                if (existing.schemaVersion === "martin.run-control-lock.v1" &&
+                    typeof existing.token === "string" &&
+                    existing.hostname === hostname() &&
+                    typeof existing.pid === "number" &&
+                    !isProcessAlive(existing.pid)) {
+                    if (await reclaimDeadRunControlLock(runDirectory, lockPath, raw, before, existing.token)) {
+                        continue;
+                    }
+                }
+            }
+            catch (inspectionError) {
+                if (isNodeError(inspectionError, "ENOENT"))
+                    continue;
+            }
+            await new Promise((resolve) => setTimeout(resolve, RUN_CONTROL_LOCK_RETRY_MS));
+        }
+    }
+    if (!lockHandle || !lease) {
+        throw storeUnreadableError("Run control journal is busy; no control was recorded.");
+    }
+    let heartbeatRunning = false;
+    const heartbeat = setInterval(() => {
+        if (!lockHandle || !lease || heartbeatRunning)
+            return;
+        heartbeatRunning = true;
+        lease = { ...lease, heartbeatAt: new Date().toISOString() };
+        const serializedLease = `${JSON.stringify(lease)}\n`;
+        void lockHandle.truncate(0)
+            // FileHandle.writeFile() writes from the handle's current position. The
+            // explicit position prevents a heartbeat from leaving a sparse prefix
+            // after truncate(), which would make the ownership record unreadable.
+            .then(() => lockHandle.write(serializedLease, 0, "utf8"))
+            .then(() => lockHandle.sync())
+            .catch(() => undefined)
+            .finally(() => {
+            heartbeatRunning = false;
+        });
+    }, 1_000);
+    heartbeat.unref();
+    try {
+        return await operation();
+    }
+    finally {
+        clearInterval(heartbeat);
+        await lockHandle.close();
+        const raw = await safeReadJournal(runDirectory, lockPath).catch(() => undefined);
+        if (raw) {
+            try {
+                const current = JSON.parse(raw);
+                if (current.token === token)
+                    await unlink(lockPath);
+            }
+            catch {
+                // A replaced/corrupt lock is never deleted by a former owner.
+            }
+        }
+    }
+}
+async function reclaimDeadRunControlLock(runDirectory, lockPath, observedRaw, observed, staleToken) {
+    const claimPath = path.join(runDirectory, `.run-control.reclaim-${createHash("sha256").update(staleToken).digest("hex").slice(0, 24)}`);
+    try {
+        // A hard-link is an atomic compare token for the observed inode. Exactly
+        // one concurrent reclaimer can create this deterministic claim.
+        await link(lockPath, claimPath);
+    }
+    catch (error) {
+        if (isNodeError(error, "EEXIST") || isNodeError(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+    try {
+        const claimed = await lstat(claimPath);
+        const current = await lstat(lockPath).catch((error) => {
+            if (isNodeError(error, "ENOENT"))
+                return undefined;
+            throw error;
+        });
+        if (!current ||
+            !claimed.isFile() ||
+            claimed.isSymbolicLink() ||
+            !sameFileIdentity(observed, claimed) ||
+            !sameFileIdentity(claimed, current)) {
+            return false;
+        }
+        const handle = await open(claimPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        let claimRaw;
+        try {
+            const opened = await handle.stat();
+            if (!sameFileIdentity(claimed, opened))
+                return false;
+            claimRaw = await handle.readFile({ encoding: "utf8" });
+        }
+        finally {
+            await handle.close();
+        }
+        if (claimRaw !== observedRaw)
+            return false;
+        // Only the successful claim creator may unlink. Other reclaimers wait for
+        // the claim to disappear, preventing a second stale observer from deleting
+        // a newly acquired lock after the first reclaimer succeeds.
+        const beforeUnlink = await lstat(lockPath).catch(() => undefined);
+        if (!beforeUnlink || !sameFileIdentity(claimed, beforeUnlink))
+            return false;
+        await unlink(lockPath);
+        return true;
+    }
+    finally {
+        await unlink(claimPath).catch(() => undefined);
+    }
+}
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !isNodeError(error, "ESRCH");
+    }
+}
+function isNodeError(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
 }
 export function validateControlReason(value) {
     if (value === undefined) {