@kylecheng3146/agent-ops 0.5.3 → 0.6.0

package/dist/runtime/src/run/hosts/protocol.js

@@ -0,0 +1,254 @@
+import { createInterface } from "node:readline";
+import { AgentOpsError } from "../../fs/paths.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseLine(line, source) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch (error) {
+        throw new AgentOpsError("NATIVE_PROTOCOL_INVALID", `Invalid JSON from ${source}.`, { cause: error });
+    }
+    if (!isRecord(parsed)) {
+        throw new AgentOpsError("NATIVE_PROTOCOL_INVALID", `Native ${source} message is not an object.`);
+    }
+    return parsed;
+}
+/** JSONL request/notification channel used by the Codex app server. */
+export class JsonRpcSession {
+    child;
+    requestTimeoutMs;
+    lines;
+    pending = new Map();
+    events = [];
+    waiters = [];
+    nextId = 1;
+    closed = null;
+    constructor(child, requestTimeoutMs = 30_000) {
+        this.child = child;
+        this.requestTimeoutMs = requestTimeoutMs;
+        this.lines = createInterface({ input: child.stdout });
+        this.lines.on("line", (line) => this.receive(line, "stdout"));
+        child.once("error", (error) => this.close(error));
+        child.once("exit", (code, signal) => {
+            this.close(new AgentOpsError("NATIVE_PROCESS_CLOSED", `Native process closed (code=${String(code)}, signal=${String(signal)}).`));
+        });
+    }
+    async request(method, params) {
+        if (this.closed !== null) {
+            throw this.closed;
+        }
+        const id = this.nextId++;
+        const request = { jsonrpc: "2.0", id, method, params };
+        const response = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new AgentOpsError("NATIVE_REQUEST_TIMEOUT", `Native request timed out: ${method}`));
+            }, this.requestTimeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+        });
+        this.write(request);
+        return response;
+    }
+    notify(method, params = {}) {
+        if (this.closed !== null) {
+            throw this.closed;
+        }
+        this.write({ jsonrpc: "2.0", method, params });
+    }
+    async nextEvent(signal) {
+        if (this.events.length > 0) {
+            return this.events.shift() ?? null;
+        }
+        if (this.closed !== null) {
+            return null;
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = { resolve, reject, signal };
+            if (signal !== undefined) {
+                if (signal.aborted) {
+                    resolve(null);
+                    return;
+                }
+                const onAbort = () => {
+                    const index = this.waiters.indexOf(waiter);
+                    if (index >= 0) {
+                        this.waiters.splice(index, 1);
+                    }
+                    resolve(null);
+                };
+                waiter.onAbort = onAbort;
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+            this.waiters.push(waiter);
+        });
+    }
+    close(error = null) {
+        if (this.closed !== null) {
+            return;
+        }
+        this.closed = error ?? new AgentOpsError("NATIVE_PROCESS_CLOSED", "Native process closed.");
+        this.lines.close();
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(this.closed);
+        }
+        this.pending.clear();
+        for (const waiter of this.waiters.splice(0)) {
+            if (waiter.signal !== undefined && waiter.onAbort !== undefined) {
+                waiter.signal.removeEventListener("abort", waiter.onAbort);
+            }
+            waiter.resolve(null);
+        }
+    }
+    receive(line, source) {
+        if (line.trim().length === 0) {
+            return;
+        }
+        let message;
+        try {
+            message = parseLine(line, source);
+        }
+        catch (error) {
+            this.close(error);
+            return;
+        }
+        const id = message.id;
+        if (typeof id === "number" && Number.isSafeInteger(id)) {
+            const pending = this.pending.get(id);
+            if (pending === undefined) {
+                this.enqueue(message);
+                return;
+            }
+            this.pending.delete(id);
+            clearTimeout(pending.timer);
+            if (isRecord(message.error)) {
+                pending.reject(new AgentOpsError("NATIVE_REQUEST_FAILED", String(message.error.message ?? "Native request failed"), { cause: message.error }));
+            }
+            else if (isRecord(message.result)) {
+                pending.resolve(message.result);
+            }
+            else {
+                pending.resolve(message);
+            }
+            return;
+        }
+        this.enqueue(message);
+    }
+    write(message) {
+        this.child.stdin.write(`${JSON.stringify(message)}\n`);
+    }
+    enqueue(message) {
+        const waiter = this.waiters.shift();
+        if (waiter !== undefined) {
+            if (waiter.signal !== undefined && waiter.onAbort !== undefined) {
+                waiter.signal.removeEventListener("abort", waiter.onAbort);
+            }
+            waiter.resolve(message);
+        }
+        else {
+            this.events.push(message);
+        }
+    }
+}
+/** Newline-delimited stream used by Claude Code's stream-json mode. */
+export class JsonLineStream {
+    child;
+    lines;
+    events = [];
+    waiters = [];
+    closed = false;
+    constructor(child) {
+        this.child = child;
+        this.lines = createInterface({ input: child.stdout });
+        this.lines.on("line", (line) => {
+            if (line.trim().length === 0) {
+                return;
+            }
+            try {
+                this.enqueue(parseLine(line, "stdout"));
+            }
+            catch (error) {
+                this.close(error);
+            }
+        });
+        child.once("error", (error) => this.close(error));
+        child.once("exit", () => this.close());
+    }
+    async next(signal) {
+        if (this.events.length > 0) {
+            return this.events.shift() ?? null;
+        }
+        if (this.closed) {
+            return null;
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = { resolve, reject, signal };
+            if (signal !== undefined) {
+                if (signal.aborted) {
+                    resolve(null);
+                    return;
+                }
+                const onAbort = () => {
+                    const index = this.waiters.indexOf(waiter);
+                    if (index >= 0) {
+                        this.waiters.splice(index, 1);
+                    }
+                    resolve(null);
+                };
+                waiter.onAbort = onAbort;
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+            this.waiters.push(waiter);
+        });
+    }
+    requeue(message) {
+        this.events.unshift(message);
+    }
+    close(_error) {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.lines.close();
+        for (const waiter of this.waiters.splice(0)) {
+            if (waiter.signal !== undefined && waiter.onAbort !== undefined) {
+                waiter.signal.removeEventListener("abort", waiter.onAbort);
+            }
+            waiter.resolve(null);
+        }
+    }
+    enqueue(message) {
+        const waiter = this.waiters.shift();
+        if (waiter !== undefined) {
+            if (waiter.signal !== undefined && waiter.onAbort !== undefined) {
+                waiter.signal.removeEventListener("abort", waiter.onAbort);
+            }
+            waiter.resolve(message);
+        }
+        else {
+            this.events.push(message);
+        }
+    }
+}
+export function asNativePayload(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : null;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => asNativePayload(item));
+    }
+    if (typeof value === "object") {
+        const object = {};
+        for (const [key, item] of Object.entries(value)) {
+            object[key] = asNativePayload(item);
+        }
+        return object;
+    }
+    return null;
+}

package/dist/runtime/src/run/hosts/types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/src/run/hosts/util.js

@@ -0,0 +1,136 @@
+import { randomUUID } from "node:crypto";
+import { spawn as nodeSpawn } from "node:child_process";
+import { AgentOpsError } from "../../fs/paths.js";
+import { asNativePayload } from "./protocol.js";
+export function spawnNative(command, args, cwd, env, options) {
+    const spawn = options.spawn ?? ((name, argv, spawnOptions) => nodeSpawn(name, [...argv], spawnOptions));
+    const child = spawn(command, args, {
+        cwd,
+        env: { ...process.env, ...options.env, ...env },
+        stdio: ["pipe", "pipe", "pipe"],
+        detached: process.platform !== "win32"
+    });
+    // Native clients can emit diagnostics independently of their structured
+    // stdout protocol. Drain stderr so a long-lived writer cannot deadlock on a
+    // full pipe; structured lifecycle events remain the source of truth.
+    child.stderr.resume();
+    return child;
+}
+export function assertContext(handle, context) {
+    if (handle.runId !== context.runId ||
+        handle.workerId !== context.workerId ||
+        handle.generation !== context.generation ||
+        handle.contractHash !== context.contractHash) {
+        throw new AgentOpsError("NATIVE_STALE_WRITER", "The native action belongs to a stale run worker generation.");
+    }
+}
+export function assertProcessRunning(child) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        throw new AgentOpsError("NATIVE_PROCESS_CLOSED", "The native worker process is already closed.");
+    }
+}
+export function actionResult(accepted, nativeStatus, payload) {
+    return {
+        actionId: randomUUID(),
+        accepted,
+        nativeStatus,
+        payload: asNativePayload(payload)
+    };
+}
+export function event(handle, type, nativeStatus, payload, now) {
+    return {
+        type,
+        host: handle.kind,
+        runId: handle.runId,
+        workerId: handle.workerId,
+        generation: handle.generation,
+        contractHash: handle.contractHash,
+        at: now().toISOString(),
+        nativeStatus,
+        payload: asNativePayload(payload),
+        proof: false
+    };
+}
+export async function waitForExit(child, timeoutMs = 10_000) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        return;
+    }
+    await new Promise((resolve) => {
+        let settled = false;
+        const settle = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(settle, timeoutMs);
+        child.once("exit", settle);
+        child.once("error", settle);
+    });
+}
+export function commandParts(options, fallbackCommand, fallbackArgs) {
+    return {
+        command: options.command ?? fallbackCommand,
+        args: options.args ?? fallbackArgs
+    };
+}
+/** Native writers own a process group, including their managed command children. */
+export function nativeProcessGroupAlive(pid) {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch (cause) {
+        if (cause.code === "ESRCH")
+            return false;
+        // Permission errors cannot establish death.
+        return true;
+    }
+}
+export async function signalNativeProcessGroup(pid, signal) {
+    try {
+        process.kill(process.platform === "win32" ? pid : -pid, signal);
+    }
+    catch (cause) {
+        const code = cause.code;
+        if (code === "ESRCH")
+            return;
+        if (code === "EPERM" && process.platform !== "win32") {
+            // macOS can report EPERM while an already-killed group is being reaped.
+            // Permission failure is safe to dismiss only after the kernel confirms absence.
+            for (let i = 0; i < 30 && nativeProcessGroupAlive(pid); i++)
+                await new Promise(resolve => setTimeout(resolve, 100));
+            if (!nativeProcessGroupAlive(pid))
+                return;
+        }
+        throw cause;
+    }
+}
+export async function stopNativeProcess(child, signal) {
+    const pid = child.pid;
+    if (pid === undefined)
+        throw new AgentOpsError("NATIVE_PROCESS_UNKNOWN", "Native process has no registered PID.");
+    const send = async (s) => {
+        if (process.platform !== "win32")
+            return await signalNativeProcessGroup(pid, s);
+        try {
+            child.kill(s);
+        }
+        catch (cause) {
+            if (cause.code !== "ESRCH")
+                throw cause;
+        }
+    };
+    await send(signal);
+    await waitForExit(child, 3000);
+    if (process.platform !== "win32" && nativeProcessGroupAlive(pid)) {
+        await send("SIGKILL");
+        for (let i = 0; i < 30 && nativeProcessGroupAlive(pid); i++)
+            await new Promise(resolve => setTimeout(resolve, 100));
+        if (nativeProcessGroupAlive(pid))
+            throw new AgentOpsError("NATIVE_PROCESS_STILL_ALIVE", "Managed native descendants have not stopped; takeover is refused.");
+    }
+    if (child.exitCode === null && child.signalCode === null)
+        throw new AgentOpsError("NATIVE_PROCESS_STILL_ALIVE", "Native stop did not confirm process death.");
+}

package/dist/runtime/src/run/integration.js

@@ -0,0 +1,204 @@
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { canonicalJson } from "../config/hash.js";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+import { FileRunRepository } from "./service.js";
+function ledger(commonDir) { return new FileRunRepository(join(commonDir, "agent-ops", "runs"), commonDir); }
+function proofPath(commonDir, runId) { return join(commonDir, "agent-ops", "runs", runId, "integration-proof.json"); }
+function integrationIdentity(integration) {
+    return {
+        transactionId: integration.transactionId,
+        expectedTarget: integration.expectedTarget,
+        candidate: integration.candidate
+    };
+}
+/** The binding intentionally excludes receiptDigest to avoid a receipt/state cycle. */
+export function integrationReceiptBindingDigest(integration) {
+    return sha256(canonicalJson(integrationIdentity(integration)));
+}
+export function integrationReceiptBinding(integration) {
+    return { ...integrationIdentity(integration), digest: integrationReceiptBindingDigest(integration) };
+}
+const plain = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Validate the immutable run transaction fields embedded in a final receipt. */
+export function validateRunIntegrationReceipt(integration, receipt) {
+    const binding = receipt.integrationJournal;
+    if (receipt.candidateHead !== integration.candidate || receipt.targetCommit !== integration.expectedTarget ||
+        !plain(binding) || binding.transactionId !== integration.transactionId ||
+        binding.expectedTarget !== integration.expectedTarget || binding.candidate !== integration.candidate ||
+        binding.digest !== integrationReceiptBindingDigest(integration)) {
+        throw new AgentOpsError("RUN_INTEGRATION_RECEIPT_INVALID", "The final receipt is not bound to the sealed integration transaction.");
+    }
+}
+async function readSealedProof(commonDir, runId, integration) {
+    const source = await readPrivateFile(proofPath(commonDir, runId), commonDir);
+    if (source === null || integration.proofDigest === undefined || sha256(source) !== integration.proofDigest) {
+        throw new AgentOpsError("RUN_INTEGRATION_PROOF_CHANGED", "The sealed integration proof is missing or changed.");
+    }
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch (cause) {
+        throw new AgentOpsError("RUN_INTEGRATION_PROOF_CHANGED", "The sealed integration proof is not valid JSON.", { cause });
+    }
+    if (!plain(value) || value.target !== integration.expectedTarget || value.head !== integration.candidate) {
+        throw new AgentOpsError("RUN_INTEGRATION_PROOF_CHANGED", "Integration proof no longer matches the frozen target and candidate.");
+    }
+    return value;
+}
+/** Seal the exact final gate before any target mutation. Recovery cannot invent a new proof. */
+export async function prepareRunIntegration(commonDir, record, proof) {
+    if (record.runId === undefined)
+        return;
+    const repository = ledger(commonDir);
+    const state = await repository.read(record.runId);
+    if (state === null || state.ownerSessionId !== record.sessionId || state.coordinatorId !== record.workerId ||
+        state.status !== "active" || state.disableRestart || state.workers.some(worker => ["assigned", "starting", "running", "idle", "handing-off"].includes(worker.status)))
+        throw new AgentOpsError("RUN_INTEGRATION_OWNERSHIP", "Final integration requires the stopped registered coordinator and current active run.");
+    if (state.integration !== null) {
+        if (state.integration.status !== "prepared")
+            throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "Reconcile the existing integration before preparing another candidate.");
+        const sealed = await readSealedProof(commonDir, record.runId, state.integration);
+        if (canonicalJson(sealed) !== canonicalJson(proof))
+            throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "The existing sealed integration cannot be replaced by a new proof.");
+        return;
+    }
+    const source = JSON.stringify(proof);
+    await repository.mutate(record.runId, async (current) => {
+        if (current.status !== "active" || current.disableRestart || current.revision !== state.revision)
+            throw new AgentOpsError("RUN_INTEGRATION_STALE", "Run changed while sealing final proof.");
+        await writePrivateFile(proofPath(commonDir, record.runId), source, commonDir);
+        return { ...current, integration: { transactionId: randomUUID(), status: "prepared", expectedTarget: proof.target,
+                candidate: proof.head, proofDigest: sha256(source), completedSteps: [], receiptPath: null, receiptDigest: null,
+                updatedAt: new Date().toISOString(), childDeliveries: proof.children.map(child => child.commit) } };
+    });
+}
+export async function readRunIntegrationProof(commonDir, record) {
+    if (record.runId === undefined)
+        return null;
+    const state = await ledger(commonDir).read(record.runId);
+    if (state?.integration == null)
+        return null;
+    if (state.ownerSessionId !== record.sessionId || state.coordinatorId !== record.workerId)
+        throw new AgentOpsError("RUN_INTEGRATION_OWNERSHIP", "Recovery coordinator does not match the sealed transaction.");
+    return await readSealedProof(commonDir, record.runId, state.integration);
+}
+/** A failed pre-merge CAS may be retried only after archiving the unused sealed transaction. */
+export async function abandonPreparedRunIntegration(commonDir, record, git) {
+    if (record.runId === undefined)
+        return;
+    const repository = ledger(commonDir);
+    const state = await repository.read(record.runId);
+    const transaction = state?.integration;
+    if (state === null || transaction == null)
+        return;
+    if (transaction.status !== "prepared" || state.ownerSessionId !== record.sessionId || state.coordinatorId !== record.workerId ||
+        state.workers.some(worker => ["assigned", "starting", "running", "idle", "handing-off"].includes(worker.status)))
+        throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "Only a stopped, unused prepared transaction may be superseded.");
+    const target = await git(state.root, ["rev-parse", state.targetBranch + "^{commit}"]);
+    const commit = target.stdout.trim();
+    const ancestry = await git(state.root, ["merge-base", "--is-ancestor", transaction.candidate, commit]);
+    if (target.exitCode !== 0 || commit === transaction.expectedTarget || commit === transaction.candidate || ancestry.exitCode !== 1)
+        throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "The old candidate may have reached the target; preserve and recover its sealed transaction.");
+    const proof = await readSealedProof(commonDir, record.runId, transaction);
+    await repository.mutate(record.runId, async (current) => {
+        const actual = await git(state.root, ["rev-parse", state.targetBranch + "^{commit}"]);
+        if (current.revision !== state.revision || actual.exitCode !== 0 || actual.stdout.trim() !== commit)
+            throw new AgentOpsError("RUN_INTEGRATION_STALE", "Run or target changed while superseding an unused transaction.");
+        const path = join(commonDir, "agent-ops", "runs", record.runId, "integration-history", transaction.transactionId + ".json");
+        await writePrivateFile(path, JSON.stringify({ transaction, proof, observedTarget: commit }), commonDir);
+        return { ...current, integration: null };
+    });
+}
+/** Read the binding used by a finish receipt without trusting caller-supplied transaction fields. */
+export async function readRunIntegrationReceiptBinding(commonDir, record, expected) {
+    if (record.runId === undefined)
+        return null;
+    const state = await ledger(commonDir).read(record.runId);
+    if (state === null || state.integration === null)
+        throw new AgentOpsError("RUN_INTEGRATION_REQUIRED", "A run-owned final receipt requires a sealed integration transaction.");
+    if (state.ownerSessionId !== record.sessionId || state.coordinatorId !== record.workerId)
+        throw new AgentOpsError("RUN_INTEGRATION_OWNERSHIP", "The integration transaction belongs to another coordinator.");
+    await readSealedProof(commonDir, record.runId, state.integration);
+    if (state.integration.expectedTarget !== expected.target || state.integration.candidate !== expected.candidate)
+        throw new AgentOpsError("RUN_INTEGRATION_PROOF_CHANGED", "The receipt candidate does not match the sealed integration transaction.");
+    return integrationReceiptBinding(state.integration);
+}
+export async function markRunIntegration(commonDir, record, status, step, receipt) {
+    if (record.runId === undefined)
+        return;
+    await ledger(commonDir).mutate(record.runId, current => {
+        if (current.integration === null || current.ownerSessionId !== record.sessionId || current.coordinatorId !== record.workerId)
+            throw new AgentOpsError("RUN_INTEGRATION_OWNERSHIP", "The integration transaction is missing or belongs to another coordinator.");
+        return { ...current, integration: { ...current.integration, status, updatedAt: new Date().toISOString(),
+                completedSteps: [...new Set([...current.integration.completedSteps, step])],
+                ...(receipt === undefined ? {} : { receiptPath: receipt.path, receiptDigest: receipt.digest }) } };
+    });
+}
+/**
+ * Finish bookkeeping after a coordinator checkout vanished. This only verifies
+ * sealed artifacts and advances the ledger; it never recreates a checkout or
+ * starts a native writer.
+ */
+export async function recoverRunIntegrationAfterCleanup(commonDir, runId, git) {
+    const repository = ledger(commonDir);
+    const state = await repository.read(runId);
+    if (state === null || state.integration === null)
+        throw new AgentOpsError("RUN_INTEGRATION_REQUIRED", "There is no sealed integration to recover.");
+    const integration = state.integration;
+    if (state.workers.some(worker => ["assigned", "starting", "running", "idle", "handing-off"].includes(worker.status)))
+        throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "Integration cleanup cannot be recovered while a writer is active.");
+    await readSealedProof(commonDir, runId, integration);
+    if (integration.status !== "cleaned" &&
+        (integration.status !== "receipt-written" || !integration.completedSteps.includes("receipt") ||
+            !integration.completedSteps.includes("note"))) {
+        throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "Recovery requires a recorded receipt and Git note before cleanup can be completed.");
+    }
+    if (integration.receiptPath === null || integration.receiptDigest === null)
+        throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "The integration has no sealed receipt.");
+    const source = await readPrivateFile(integration.receiptPath, commonDir);
+    if (source === null || sha256(source) !== integration.receiptDigest)
+        throw new AgentOpsError("RUN_INTEGRATION_RECEIPT_INVALID", "The recorded integration receipt is missing or changed.");
+    let receipt;
+    try {
+        const value = JSON.parse(source);
+        if (!plain(value))
+            throw new Error("receipt is not an object");
+        receipt = value;
+    }
+    catch (cause) {
+        throw new AgentOpsError("RUN_INTEGRATION_RECEIPT_INVALID", "The recorded integration receipt is not valid JSON.", { cause });
+    }
+    if (receipt.sessionId !== state.ownerSessionId)
+        throw new AgentOpsError("RUN_INTEGRATION_RECEIPT_INVALID", "The receipt belongs to another run owner.");
+    validateRunIntegrationReceipt(integration, receipt);
+    const note = await git(state.root, ["notes", "--ref=agent-ops", "show", integration.candidate]);
+    const noteText = note.stdout;
+    if (note.exitCode !== 0 || !noteText.includes(`session: ${state.ownerSessionId}`) ||
+        !noteText.includes(`receipt: ${integration.receiptPath}`) ||
+        !noteText.includes(`receipt-sha256: ${integration.receiptDigest}`)) {
+        throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "The sealed receipt is not bound by the Git note for the candidate.");
+    }
+    const target = await git(state.root, ["rev-parse", state.targetBranch + "^{commit}"]);
+    const exact = target.exitCode === 0 && target.stdout.trim() === integration.candidate;
+    const historic = !exact && target.exitCode === 0 && integration.completedSteps.includes("target") &&
+        integration.completedSteps.includes("receipt") && integration.completedSteps.includes("note") &&
+        (await git(state.root, ["merge-base", "--is-ancestor", integration.candidate, target.stdout.trim()])).exitCode === 0;
+    if (!exact && !historic)
+        throw new AgentOpsError("RUN_INTEGRATION_TARGET_CHANGED", "The target is inconsistent with the sealed, receipt-bound integration history.");
+    await repository.mutate(runId, current => {
+        if (current.integration === null || current.integration.transactionId !== integration.transactionId ||
+            current.integration.candidate !== integration.candidate || current.integration.expectedTarget !== integration.expectedTarget)
+            throw new AgentOpsError("RUN_INTEGRATION_STALE", "The integration changed during recovery.");
+        if (current.integration.status === "cleaned")
+            return current;
+        if (current.integration.status !== "receipt-written")
+            throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "The integration is not at the cleanup recovery boundary.");
+        return { ...current, integration: { ...current.integration, status: "cleaned",
+                completedSteps: [...new Set([...current.integration.completedSteps, "coordinator"])], updatedAt: new Date().toISOString() } };
+    });
+    return { transactionId: integration.transactionId, receiptPath: integration.receiptPath, receiptDigest: integration.receiptDigest };
+}