@kylecheng3146/agent-ops 0.11.1 → 0.11.2

package/dist/runtime/src/followup/process.js

@@ -0,0 +1,273 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { calculateConfigHash, canonicalJson } from "../config/hash.js";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { assessFollowup, followupFindingDigest, isFollowupAssessmentCurrent, readFollowupAssessment } from "../review/followup.js";
+import { FileRunRepository } from "../run/service.js";
+import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
+import { evidenceMatchesContract } from "../task/contract.js";
+import { validateEvidence } from "../schema/validate.js";
+import { acceptanceCoverage } from "../verify/acceptance-coverage.js";
+import { collectChangeSurface, resolveGitCommit } from "../verify/change-surface.js";
+import { isPassingVerificationEvidence } from "../verify/evidence.js";
+import { readDeliveredReceipt } from "./receipt.js";
+import { FileFollowupStore } from "./store.js";
+function invalid(code = "FOLLOWUP_PROGRESS_INVALID") {
+    throw new AgentOpsError(code, "Followup progress cannot authorize this operation; preserve it for recovery.");
+}
+function progressPath(commonDir, itemId) {
+    if (!/^followup-[a-f0-9]{64}$/u.test(itemId))
+        invalid();
+    return join(commonDir, "agent-ops", "followup", "progress", `${itemId}.json`);
+}
+function reference(value, commonDir) {
+    return value !== undefined && typeof value.digest === "string" && /^[a-f0-9]{64}$/u.test(value.digest) &&
+        value.path === join(commonDir, "agent-ops", "followup", "assessments", `${value.digest}.json`);
+}
+export async function readFollowupProgress(commonDir, itemId, currentItem) {
+    const source = await readPrivateFile(progressPath(commonDir, itemId), commonDir);
+    if (source === null)
+        return { schemaVersion: 1, itemId, status: "unresolved", code: "FOLLOWUP_PENDING", attempts: [], resolutions: [] };
+    try {
+        const state = JSON.parse(source);
+        if (Buffer.byteLength(source) > 4 * 1024 * 1024 || state.schemaVersion !== 1 || state.itemId !== itemId ||
+            !["assessing", "unresolved", "starting", "linked", "resolved"].includes(state.status) ||
+            typeof state.code !== "string" || !/^[A-Z0-9_-]{1,128}$/u.test(state.code) ||
+            (state.assessment !== undefined && !reference(state.assessment, commonDir)) ||
+            !Array.isArray(state.attempts) || !Array.isArray(state.resolutions) ||
+            state.attempts.some(a => !a || !/^run-[a-z0-9-]{4,60}$/u.test(a.runId) || !["codex", "claude"].includes(a.host) ||
+                !["starting", "linked", "refused"].includes(a.status) || !/^[a-f0-9]{64}$/u.test(a.findingDigest) ||
+                typeof a.goal !== "string" || a.goal.trim() === "" || a.goal.length > 1024 * 1024 || !reference(a.assessment, commonDir)) ||
+            state.resolutions.some(r => !r || !Number.isFinite(Date.parse(r.at)) || !/^[a-f0-9]{40,64}$/u.test(r.commit) ||
+                !/^[a-f0-9]{64}$/u.test(r.findingDigest) || !["behavioral", "review-only"].includes(r.proofKind) ||
+                !reference(r.assessment, commonDir) || !/^[a-f0-9]{64}$/u.test(r.configHash) || typeof r.targetBranch !== "string" || r.targetBranch.trim() === "" ||
+                (r.receipt !== undefined && (typeof r.receipt.path !== "string" || !/^[a-f0-9]{64}$/u.test(r.receipt.digest) ||
+                    typeof r.receipt.taskId !== "string" || !/^run-[a-z0-9-]{4,60}$/u.test(r.receipt.runId))) ||
+                !Array.isArray(r.proofDigests) || r.proofDigests.length === 0 || r.proofDigests.some((d) => !/^[a-f0-9]{64}$/u.test(d))))
+            invalid();
+        const item = currentItem ?? await new FileFollowupStore(commonDir).get(itemId), resolution = state.resolutions.at(-1);
+        if (state.status === "resolved" && (resolution === undefined || resolution.findingDigest !== followupFindingDigest(item) ||
+            item.history.some(event => ["reopened", "clarified"].includes(event.action) && Date.parse(event.at) >= Date.parse(resolution.at))))
+            return { ...state, status: "unresolved", code: "FOLLOWUP_REOPENED" };
+        return state;
+    }
+    catch {
+        return invalid();
+    }
+}
+async function save(commonDir, state) {
+    const content = `${JSON.stringify(state, null, 2)}\n`;
+    if (Buffer.byteLength(content) > 4 * 1024 * 1024)
+        invalid();
+    await writePrivateFile(progressPath(commonDir, state.itemId), content, commonDir);
+    return state;
+}
+export function followupResolutionDescription(itemId, findingDigest) {
+    return `Resolve the exact original finding ${itemId} (finding-sha256: ${findingDigest}) with corresponding evidence; generic test PASS or changed paths are insufficient.`;
+}
+/** The ordinary run goal is the immutable link; no historical run is resumed or rewritten. */
+function repairGoal(item, proof, reference) {
+    return ["Repair this selected, conclusively PRESENT followup and nothing unrelated.",
+        canonicalJson({ itemId: item.id, findingDigest: proof.findingDigest, original: item.original, provenance: item.provenance,
+            finding: proof.finding, assessment: reference, binding: proof.binding }),
+        "Keep the original goal fixed. Preserve normal task advisory, mandatory verification, trust, permissions, two fresh reviews and finish.",
+        "Include a root acceptance criterion with id followup-resolution and this exact description:",
+        followupResolutionDescription(item.id, proof.findingDigest),
+        proof.reviewOnlyReason === undefined
+            ? `Use behavioral acceptance for followup-resolution, baselineCommit ${proof.binding.commit}, with designated failing baseline checks for the original finding and corresponding passing candidate checks. Invariant or generic suite PASS cannot resolve it.`
+            : `Use an explicit review-only acceptance contract for followup-resolution, baselineCommit ${proof.binding.commit}, reviewOnlyReason ${JSON.stringify(proof.reviewOnlyReason)}. Both fresh reviewers must assess this exact finding and the fallback reason. A reproducible bug still requires behavioral red-to-green; reject this fallback if executable checks can establish the claim.`,
+        "Do not declare the followup resolved yourself. Its delivered sealed receipt is reconciled against the original finding, exact candidate and evidence."].join("\n\n");
+}
+/** An exclusive private claim spans assessment and durable start intent, including competing CLI processes. */
+export async function processFollowup(options) {
+    const { commonDir, itemId } = options;
+    if (!["codex", "claude"].includes(options.host))
+        invalid("RUN_HOST_INVALID");
+    return await withPrivateFileLock(progressPath(commonDir, itemId), commonDir, async () => {
+        const store = new FileFollowupStore(commonDir), item = await store.get(itemId);
+        if (item.kind !== "candidate")
+            invalid("FOLLOWUP_CLARIFICATION_REQUIRED");
+        let state = await readFollowupProgress(commonDir, itemId, item);
+        const runs = new FileRunRepository(join(commonDir, "agent-ops", "runs"), commonDir);
+        const prior = state.attempts.at(-1);
+        if (prior !== undefined && prior.status !== "refused") {
+            const existing = await runs.read(prior.runId);
+            if (existing !== null) {
+                if (existing.goal !== prior.goal || existing.host !== prior.host)
+                    invalid("FOLLOWUP_RUN_CHANGED");
+                const unsettledWriters = existing.workers.some(worker => ["assigned", "starting", "running", "idle", "handing-off"].includes(worker.status) ||
+                    ((worker.processId !== null || worker.nativeSessionId !== null || worker.nativeJobId !== null) && worker.stopIntent?.confirmedDeadAt == null));
+                if (!["failed", "complete"].includes(existing.status) || existing.proofProcess != null || unsettledWriters)
+                    return await save(commonDir, { ...state, status: "linked", code: "FOLLOWUP_RUN_LINKED",
+                        attempts: [...state.attempts.slice(0, -1), { ...prior, status: "linked" }] });
+            }
+            else if (prior.status === "starting") {
+                // An interrupted start has one reserved identity. Never issue a second identity while its outcome is ambiguous.
+                return await save(commonDir, { ...state, status: "starting", code: "FOLLOWUP_START_PENDING" });
+            }
+            else
+                invalid("FOLLOWUP_RUN_MISSING");
+        }
+        state = await save(commonDir, { ...state, status: "assessing", code: "FOLLOWUP_ASSESSING" });
+        const { assessment, reference } = await assessFollowup(options);
+        state = await save(commonDir, { ...state, assessment: reference, status: "unresolved", code: "FOLLOWUP_" + assessment.conclusion });
+        if (assessment.conclusion === "UNKNOWN")
+            return state;
+        if (!await isFollowupAssessmentCurrent(options, assessment))
+            return await save(commonDir, { ...state, code: "FOLLOWUP_SOURCE_CHANGED" });
+        if (assessment.conclusion === "ABSENT") {
+            if (assessment.reviewOnlyReason === undefined)
+                return state;
+            const resolution = { at: new Date().toISOString(), findingDigest: assessment.findingDigest,
+                commit: assessment.binding.commit, targetBranch: assessment.binding.targetBranch, configHash: assessment.binding.configHash,
+                proofKind: "review-only", assessment: reference, proofDigests: [reference.digest,
+                    sha256(canonicalJson(assessment.review.report)), sha256(canonicalJson(assessment.review.adversarial.report))] };
+            return await save(commonDir, { ...state, status: "resolved", code: "FOLLOWUP_ABSENCE_PROVEN", resolutions: [...state.resolutions, resolution] });
+        }
+        const attempt = { runId: `run-${randomUUID().replaceAll("-", "").slice(0, 16)}`,
+            host: options.host, findingDigest: assessment.findingDigest, assessment: reference,
+            goal: repairGoal(item, assessment, reference), status: "starting" };
+        state = await save(commonDir, { ...state, status: "starting", code: "FOLLOWUP_START_PENDING", attempts: [...state.attempts, attempt] });
+        try {
+            if (!await isFollowupAssessmentCurrent(options, assessment))
+                invalid("FOLLOWUP_SOURCE_CHANGED");
+            const run = await options.start({ runId: attempt.runId, goal: attempt.goal, host: attempt.host }, assessment);
+            if (run.runId !== attempt.runId || run.goal !== attempt.goal)
+                invalid("FOLLOWUP_RUN_CHANGED");
+            state = { ...state, status: "linked", code: "FOLLOWUP_RUN_STARTED", attempts: [...state.attempts.slice(0, -1), { ...attempt, status: "linked" }] };
+        }
+        catch (error) {
+            const code = error instanceof AgentOpsError && /^[A-Z0-9_]{1,128}$/u.test(error.code) ? error.code : "FOLLOWUP_START_FAILED";
+            const created = await runs.read(attempt.runId);
+            if (created !== null && (created.goal !== attempt.goal || created.host !== attempt.host))
+                invalid("FOLLOWUP_RUN_CHANGED");
+            state = { ...state, status: created === null ? "unresolved" : "linked", code,
+                attempts: [...state.attempts.slice(0, -1), { ...attempt, status: created === null ? "refused" : "linked", code }] };
+        }
+        return await save(commonDir, state);
+    });
+}
+/** Recheck sealed specific acceptance after cleanup, using existing paired-evidence rules. */
+export async function reconcileFollowupRepairs(options) {
+    const warnings = [];
+    try {
+        const store = new FileFollowupStore(options.commonDir);
+        const runs = new FileRunRepository(join(options.commonDir, "agent-ops", "runs"), options.commonDir);
+        const gitRunner = { run: async (args) => {
+                const result = await options.git(options.mainRoot, args);
+                return { ...result, stdout: Buffer.from(result.stdout) };
+            } };
+        for (const item of (await store.read()).items) {
+            await withPrivateFileLock(progressPath(options.commonDir, item.id), options.commonDir, async () => {
+                const state = await readFollowupProgress(options.commonDir, item.id, item), attempt = state.attempts.at(-1);
+                if (attempt === undefined || attempt.status === "refused")
+                    return;
+                const run = await runs.read(attempt.runId);
+                if (run === null)
+                    return;
+                if (run.goal !== attempt.goal || run.host !== attempt.host || run.root !== options.mainRoot ||
+                    run.commonDir !== options.commonDir || attempt.findingDigest !== followupFindingDigest(item))
+                    invalid("FOLLOWUP_RUN_CHANGED");
+                if (run.integration?.receiptPath == null || run.integration.receiptDigest === null ||
+                    (options.path !== undefined && options.path !== run.integration.receiptPath))
+                    return;
+                const proof = await readFollowupAssessment(options.commonDir, attempt.assessment);
+                if (proof.conclusion !== "PRESENT" || proof.findingDigest !== attempt.findingDigest || proof.binding === null ||
+                    proof.itemId !== item.id || repairGoal(item, proof, attempt.assessment) !== attempt.goal)
+                    invalid();
+                const original = await readDeliveredReceipt({ ...options, path: item.provenance.receiptPath });
+                if (original.digest !== item.provenance.receiptDigest)
+                    invalid("FOLLOWUP_ORIGINAL_CHANGED");
+                const delivered = await readDeliveredReceipt({ ...options, path: run.integration.receiptPath });
+                const receipt = delivered.receipt;
+                if (delivered.digest !== run.integration.receiptDigest || receipt.sessionId !== run.ownerSessionId ||
+                    receipt.integrationJournal?.transactionId !== run.integration.transactionId || receipt.candidateHead !== run.integration.candidate ||
+                    receipt.targetCommit !== run.integration.expectedTarget ||
+                    run.targetBranch !== proof.binding.targetBranch || run.rootTaskId === null ||
+                    (await collectChangeSurface(gitRunner)).paths.length !== 0 ||
+                    await resolveGitCommit(gitRunner, "HEAD") !== receipt.candidateHead ||
+                    (await gitRunner.run(["merge-base", "--is-ancestor", proof.binding.commit, receipt.candidateHead])).exitCode !== 0)
+                    return;
+                const branch = await gitRunner.run(["symbolic-ref", "--short", "HEAD"]);
+                if (branch.exitCode !== 0 || Buffer.from(branch.stdout).toString("utf8").trim() !== run.targetBranch)
+                    return;
+                const root = receipt.tasks.find(r => r.task.id === run.rootTaskId);
+                const criterion = root?.task.criteria.find(c => c.id === "followup-resolution");
+                if (root === undefined || root.task.goal !== attempt.goal || criterion?.description !== followupResolutionDescription(item.id, attempt.findingDigest) ||
+                    criterion.acceptance === undefined || criterion.acceptance.baselineCommit !== proof.binding.commit ||
+                    (proof.reviewOnlyReason === undefined ? criterion.acceptance.mode !== "behavioral" :
+                        criterion.acceptance.mode !== "review-only" || criterion.acceptance.reviewOnlyReason !== proof.reviewOnlyReason))
+                    return;
+                const configHash = calculateConfigHash(options.config);
+                const load = async (reference) => receipt.verification[reference]?.value ?? null;
+                const readExecution = async (path) => {
+                    const seal = receipt.executionArtifacts?.[path];
+                    if (seal === undefined || typeof seal.value !== "string" || sha256(JSON.stringify(seal.value)) !== seal.digest)
+                        return null;
+                    return seal.value;
+                };
+                const proofDigests = [delivered.digest, attempt.assessment.digest];
+                for (const record of receipt.tasks) {
+                    if (record.policyConfigHash !== configHash)
+                        return;
+                    for (const c of record.task.criteria)
+                        for (const command of options.config.verification.commands.filter(c => c.required)) {
+                            const evidence = (record.evidence[c.id] ?? []).filter(ref => !ref.startsWith("review:")).map(ref => {
+                                const seal = receipt.verification[ref];
+                                const result = validateEvidence(seal?.value);
+                                if (seal === undefined || sha256(JSON.stringify(seal.value)) !== seal.digest || !result.ok)
+                                    return null;
+                                return { value: result.value, digest: seal.digest };
+                            }).filter(e => e !== null && e.value.acceptance === undefined && e.value.taskId === record.task.id &&
+                                e.value.criterionId === c.id && e.value.commandId === command.id && e.value.configHash === configHash &&
+                                e.value.sourceFingerprint === receipt.sourceFingerprint && evidenceMatchesContract(e.value.taskContractHash, record.task))
+                                .sort((a, b) => Date.parse(b.value.finishedAt) - Date.parse(a.value.finishedAt) || (a.value.status === "PASS" ? 1 : -1))[0];
+                            if (evidence == null || !isPassingVerificationEvidence(command, evidence.value))
+                                return;
+                            proofDigests.push(evidence.digest);
+                        }
+                    const coverage = await acceptanceCoverage(record, options.config, receipt.sourceFingerprint, { root: options.mainRoot, load }, readExecution);
+                    if (coverage.some(c => ["behavioral", "invariant"].includes(c.mode) && c.status !== "proven"))
+                        return;
+                    for (const c of record.task.criteria)
+                        for (const ref of record.evidence[c.id] ?? []) {
+                            const seal = receipt.verification[ref];
+                            const checked = validateEvidence(seal?.value);
+                            if (!checked.ok || checked.value.acceptance === undefined || checked.value.sourceFingerprint !== receipt.sourceFingerprint ||
+                                checked.value.configHash !== configHash || !evidenceMatchesContract(checked.value.taskContractHash, record.task))
+                                continue;
+                            if (checked.value.acceptance.phase === "candidate" && checked.value.acceptance.commit !== receipt.candidateHead)
+                                return;
+                            proofDigests.push(seal.digest);
+                            const execution = await readExecution(checked.value.acceptance.executionArtifact);
+                            if (execution === null)
+                                return;
+                            proofDigests.push(sha256(execution));
+                        }
+                }
+                for (const seals of Object.values(receipt.reviews)) {
+                    if (seals.attestation.value.schemaVersion !== 3)
+                        return;
+                    proofDigests.push(seals.attestation.digest, seals.report.digest);
+                }
+                if (state.resolutions.some(r => r.receipt?.digest === delivered.digest && r.findingDigest === attempt.findingDigest))
+                    return;
+                const resolution = { at: new Date().toISOString(), findingDigest: attempt.findingDigest,
+                    commit: receipt.candidateHead, targetBranch: run.targetBranch, configHash, proofKind: criterion.acceptance.mode,
+                    assessment: attempt.assessment, receipt: { path: run.integration.receiptPath, digest: delivered.digest, taskId: root.task.id, runId: run.runId },
+                    proofDigests: [...new Set(proofDigests)] };
+                if (followupFindingDigest(await store.get(item.id)) !== attempt.findingDigest ||
+                    await resolveGitCommit(gitRunner, "HEAD") !== receipt.candidateHead || (await collectChangeSurface(gitRunner)).paths.length !== 0 ||
+                    (options.loadConfig !== undefined && calculateConfigHash(await options.loadConfig()) !== configHash))
+                    return;
+                await save(options.commonDir, { ...state, status: "resolved", code: "FOLLOWUP_REPAIR_PROVEN", resolutions: [...state.resolutions, resolution] });
+            });
+        }
+    }
+    catch (error) {
+        const code = error instanceof AgentOpsError ? error.code : "FOLLOWUP_RECONCILIATION_FAILED";
+        warnings.push(`followup: ${code}; completion is unchanged and the item remains retryable.`);
+    }
+    return warnings;
+}

package/dist/runtime/src/followup/receipt.js

@@ -0,0 +1,116 @@
+import { basename, dirname, join } from "node:path";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { NOTES_REF } from "../parallel/service.js";
+import { validateReviewPair } from "../review/attestation.js";
+import { validateReviewReport, reviewReportStatus } from "../review/report.js";
+import { validateTask, validateEvidence } from "../schema/validate.js";
+import { readPrivateFile } from "../security/permissions.js";
+import { goalHash, taskContractHash, treeContractHash } from "../task/contract.js";
+import { validateRunIntegrationReceipt } from "../run/integration.js";
+function invalid() {
+    throw new AgentOpsError("FOLLOWUP_RECEIPT_INVALID", "Followup source is missing, changed, incomplete or not bound to delivered completion.");
+}
+function unseal(sealed) {
+    if (sealed === undefined || typeof sealed.digest !== "string" || sealed.digest !== sha256(JSON.stringify(sealed.value)))
+        invalid();
+    return sealed.value;
+}
+/** The final note binds exact receipt bytes; preliminary and active-task receipts are never intake sources. */
+export async function readDeliveredReceipt(options) {
+    const { git, mainRoot, commonDir, path } = options;
+    if (dirname(path) !== join(commonDir, "agent-ops", "receipts") ||
+        !/^[a-f0-9]{64}-[a-f0-9]{40,64}\.json$/u.test(basename(path)))
+        invalid();
+    const source = await readPrivateFile(path, commonDir);
+    if (source === null || Buffer.byteLength(source) > 16 * 1024 * 1024)
+        invalid();
+    let receipt;
+    try {
+        receipt = JSON.parse(source);
+    }
+    catch {
+        return invalid();
+    }
+    if (receipt === null || ![1, 2].includes(receipt.schemaVersion) ||
+        typeof receipt.sessionId !== "string" || !/^[a-f0-9]{40,64}$/u.test(receipt.candidateHead) ||
+        !/^[a-f0-9]{40,64}$/u.test(receipt.targetCommit) || !/^[a-f0-9]{64}$/u.test(receipt.sourceFingerprint) ||
+        basename(path) !== `${sha256(receipt.sessionId)}-${receipt.candidateHead}.json` ||
+        !["tree", "per-task-fallback"].includes(receipt.reviewMode) ||
+        !Array.isArray(receipt.tasks) || receipt.tasks.length === 0 ||
+        new Set(receipt.tasks.map(record => record?.task?.id)).size !== receipt.tasks.length ||
+        typeof receipt.reviews !== "object" || receipt.reviews === null ||
+        typeof receipt.verification !== "object" || receipt.verification === null)
+        invalid();
+    const digest = sha256(source);
+    const note = await git(mainRoot, ["notes", `--ref=${NOTES_REF}`, "show", receipt.candidateHead]);
+    if (note.exitCode !== 0 || !note.stdout.trimEnd().endsWith(`\nreceipt: ${path}\nreceipt-sha256: ${digest}`) ||
+        (await git(mainRoot, ["merge-base", "--is-ancestor", receipt.targetCommit, receipt.candidateHead])).exitCode !== 0)
+        invalid();
+    if (receipt.integrationJournal !== undefined)
+        validateRunIntegrationReceipt(receipt.integrationJournal, receipt);
+    const reviews = [];
+    const tasks = receipt.tasks;
+    for (const record of tasks) {
+        if (record?.status !== "complete" || record.failureFingerprint !== null || typeof record.completedAt !== "string" ||
+            !Number.isFinite(Date.parse(record.completedAt)) || !validateTask(record.task).ok)
+            invalid();
+        const task = record.task;
+        const sealed = receipt.reviews[task.id];
+        if (sealed === undefined)
+            invalid();
+        const raw = unseal(sealed.report);
+        const attestation = validateReviewPair(unseal(sealed.attestation), raw);
+        if (attestation === null || attestation.taskId !== task.id ||
+            attestation.sourceFingerprint !== receipt.sourceFingerprint || new Set(attestation.reviewSessionIds).size !== 2)
+            invalid();
+        const artifact = raw;
+        const tree = attestation.tree;
+        if ((receipt.reviewMode === "tree") !== (tree !== undefined))
+            invalid();
+        const ids = tree?.criterionIds ?? artifact.report?.results?.map(result => result.criterionId);
+        if (ids === undefined || (tree !== undefined && (tree.taskIds.length !== tasks.length ||
+            tasks.some(item => !tree.taskIds.includes(item.task.id)))))
+            invalid();
+        const requiredIds = tree === undefined ? task.criteria.map(c => c.id) : tasks.flatMap(item => item.task.criteria.map(c => `${item.task.id}:${c.id}`));
+        if (attestation.schemaVersion === 3 && requiredIds.some(id => !ids.includes(id)))
+            invalid();
+        for (const report of [artifact.report, artifact.adversarial?.report]) {
+            if (!validateReviewReport(report, ids).ok || reviewReportStatus(report) !== "PASS")
+                invalid();
+        }
+        if (attestation.schemaVersion === 3 && (attestation.candidateCommit !== receipt.candidateHead ||
+            attestation.taskContractHash !== taskContractHash(task) ||
+            attestation.goalHash !== goalHash(tree === undefined ? task : tasks.find(item => item.task.id === tree.rootTaskId).task) ||
+            Object.keys(attestation.taskContracts ?? {}).length !== (tree === undefined ? 1 : receipt.tasks.length) ||
+            (tree === undefined ? [record] : receipt.tasks).some(item => attestation.taskContracts?.[item.task.id] !== taskContractHash(item.task)) ||
+            (tree !== undefined && attestation.treeContractHash !== treeContractHash(receipt.tasks.map(item => item.task)))))
+            invalid();
+        // Historical failures and behavioral red phases are legitimate sealed history, never the final PASS.
+        for (const criterion of task.criteria) {
+            const references = record.evidence?.[criterion.id] ?? [];
+            const evidence = references.filter(reference => !reference.startsWith("review:")).map(reference => {
+                const checked = validateEvidence(unseal(receipt.verification[reference]));
+                if (!checked.ok || checked.value.taskId !== task.id || checked.value.criterionId !== criterion.id)
+                    return invalid();
+                return checked.value;
+            });
+            for (const commandId of criterion.verifierIds) {
+                const latest = evidence.filter(item => item.commandId === commandId && item.acceptance === undefined &&
+                    item.sourceFingerprint === receipt.sourceFingerprint && item.configHash === record.policyConfigHash)
+                    .sort((a, b) => Date.parse(b.finishedAt) - Date.parse(a.finishedAt) || (a.status === "PASS" ? 1 : -1))[0];
+                if (latest === undefined || latest.status !== "PASS" || latest.exitCode !== 0 || latest.failureClass !== "none")
+                    invalid();
+            }
+        }
+        reviews.push({ taskId: task.id, artifact, reportDigest: sealed.report.digest,
+            provenanceLimit: attestation.schemaVersion === 3 ? "contract-bound" : "legacy-unbound-contract" });
+    }
+    if (receipt.reviewMode === "tree") {
+        const root = reviews.find(review => review.taskId === review.artifact.tree?.rootTaskId);
+        if (root === undefined || reviews.some(review => JSON.stringify(review.artifact.tree) !== JSON.stringify(root.artifact.tree)))
+            invalid();
+        return { receipt, digest, reviews: [root] };
+    }
+    return { receipt, digest, reviews };
+}

package/dist/runtime/src/followup/store.js

@@ -0,0 +1,133 @@
+import { join } from "node:path";
+import { AgentOpsError } from "../fs/paths.js";
+import { sha256 } from "../fs/hash.js";
+import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
+import { validateReviewReport } from "../review/report.js";
+export function followupIdentity(provenance) {
+    return `followup-${sha256(JSON.stringify([provenance.receiptDigest, provenance.taskId,
+        provenance.reportDigest, provenance.round, provenance.sourceKind, provenance.index]))}`;
+}
+function invalid() {
+    throw new AgentOpsError("FOLLOWUP_STATE_INVALID", "Followup state is malformed; preserve it for recovery.");
+}
+function text(value) {
+    return typeof value === "string" && value.trim() !== "" && !value.includes("\0") && Buffer.byteLength(value) <= 16 * 1024;
+}
+/** Reuse ordinary finding validation, including safe locations and nonempty evidence. */
+export function validateFollowupFinding(finding) {
+    return finding !== null && typeof finding === "object" && finding.blocking === false &&
+        Array.isArray(finding.criterionIds) && Array.isArray(finding.locations) && validateReviewReport({
+        summary: "Explicit followup clarification", results: finding.criterionIds.map(criterionId => ({ criterionId, status: "PASS", summary: "Clarified", evidence: ["Explicit user clarification"] })),
+        findings: [finding], residualRisks: [], changedFilesInspected: [],
+        supportingFilesInspected: [...new Set(finding.locations.map(location => location?.path))]
+    }, finding.criterionIds).ok;
+}
+function checked(value) {
+    if (typeof value !== "object" || value === null)
+        invalid();
+    const state = value;
+    if (state.schemaVersion !== 1 || !Array.isArray(state.items) ||
+        new Set(state.items.map(item => item?.id)).size !== state.items.length)
+        invalid();
+    const items = state.items;
+    for (const item of items) {
+        const p = item?.provenance;
+        if (p === undefined || !["candidate", "observation"].includes(item.kind) ||
+            !["pending", "accepted", "deferred"].includes(item.disposition) ||
+            ![p.receiptDigest, p.reportDigest, p.sourceFingerprint].every(hash => typeof hash === "string" && /^[a-f0-9]{64}$/u.test(hash)) ||
+            ![p.candidateHead, p.targetCommit].every(hash => typeof hash === "string" && /^[a-f0-9]{40,64}$/u.test(hash)) ||
+            ![1, 2].includes(p.receiptSchemaVersion) || !text(p.taskId) || !text(p.receiptPath) ||
+            !["primary", "adversarial"].includes(p.round) || !["finding", "residual-risk"].includes(p.sourceKind) ||
+            !["contract-bound", "legacy-unbound-contract"].includes(p.provenanceLimit) ||
+            !Number.isSafeInteger(p.index) || p.index < 0 || item.id !== followupIdentity(p) ||
+            (p.sourceKind === "finding" ? typeof item.original === "string" || !validateFollowupFinding(item.original) : !text(item.original)) ||
+            (item.clarification !== undefined && !validateFollowupFinding(item.clarification)) ||
+            (item.kind === "observation" && (p.sourceKind !== "residual-risk" || item.clarification !== undefined)) ||
+            (item.kind === "candidate" && p.sourceKind === "residual-risk" && item.clarification === undefined) ||
+            !Array.isArray(item.history) || item.history.length === 0 || item.history[0].action !== "collected" ||
+            item.history.some((event) => event === null || typeof event.at !== "string" || !Number.isFinite(Date.parse(event.at)) ||
+                !["collected", "clarified", "accepted", "deferred", "reopened"].includes(event.action) ||
+                (["accepted", "deferred", "clarified"].includes(event.action) && !text(event.reason)) ||
+                (event.finding !== undefined && !validateFollowupFinding(event.finding))))
+            invalid();
+    }
+    return state;
+}
+/** One repository-local, private ledger shared by every linked checkout. */
+export class FileFollowupStore {
+    commonDir;
+    path;
+    constructor(commonDir) {
+        this.commonDir = commonDir;
+        this.path = join(commonDir, "agent-ops", "followup", "ledger.json");
+    }
+    async read() {
+        const source = await readPrivateFile(this.path, this.commonDir);
+        if (source === null)
+            return { schemaVersion: 1, items: [] };
+        if (Buffer.byteLength(source) > 16 * 1024 * 1024)
+            invalid();
+        try {
+            return checked(JSON.parse(source));
+        }
+        catch (error) {
+            if (error instanceof AgentOpsError)
+                throw error;
+            return invalid();
+        }
+    }
+    async mutate(action) {
+        return await withPrivateFileLock(this.path, this.commonDir, async () => {
+            const state = await this.read();
+            const items = structuredClone([...state.items]);
+            const before = JSON.stringify(items);
+            const result = await action(items);
+            checked({ schemaVersion: 1, items });
+            if (JSON.stringify(items) !== before) {
+                const content = `${JSON.stringify({ schemaVersion: 1, items }, null, 2)}\n`;
+                if (Buffer.byteLength(content) > 16 * 1024 * 1024)
+                    invalid();
+                await writePrivateFile(this.path, content, this.commonDir);
+            }
+            return structuredClone(result);
+        });
+    }
+    async get(id) {
+        const item = (await this.read()).items.find(item => item.id === id);
+        if (item === undefined)
+            throw new AgentOpsError("FOLLOWUP_NOT_FOUND", "No followup item has that identity.");
+        return item;
+    }
+}
+export async function setFollowupDisposition(store, id, action, reason) {
+    if (!["accept", "defer", "reopen"].includes(action) ||
+        (action !== "reopen" && !text(reason)) || (reason !== undefined && !text(reason)))
+        throw new AgentOpsError("FOLLOWUP_REASON_REQUIRED", "Accepting or deferring a followup requires a nonempty bounded reason.");
+    return await store.mutate(items => {
+        const index = items.findIndex(item => item.id === id);
+        if (index < 0)
+            throw new AgentOpsError("FOLLOWUP_NOT_FOUND", "No followup item has that identity.");
+        const item = items[index];
+        const next = { ...item, disposition: action === "accept" ? "accepted" : action === "defer" ? "deferred" : "pending",
+            history: [...item.history, { at: new Date().toISOString(), action: action === "accept" ? "accepted" : action === "defer" ? "deferred" : "reopened",
+                    ...(reason === undefined ? {} : { reason: reason.trim() }) }] };
+        items[index] = next;
+        return next;
+    });
+}
+export async function clarifyFollowup(store, id, finding, reason) {
+    if (!text(reason) || !validateFollowupFinding(finding))
+        throw new AgentOpsError("FOLLOWUP_CLARIFICATION_INVALID", "Clarification requires a concrete nonblocking finding and a nonempty reason.");
+    return await store.mutate(items => {
+        const index = items.findIndex(item => item.id === id);
+        if (index < 0)
+            throw new AgentOpsError("FOLLOWUP_NOT_FOUND", "No followup item has that identity.");
+        const item = items[index];
+        if (item.provenance.sourceKind !== "residual-risk")
+            throw new AgentOpsError("FOLLOWUP_NOT_OBSERVATION", "Only an original residual-risk observation can be clarified.");
+        const next = { ...item, kind: "candidate", clarification: structuredClone(finding), disposition: "pending",
+            history: [...item.history, { at: new Date().toISOString(), action: "clarified", reason: reason.trim(), finding: structuredClone(finding) }] };
+        items[index] = next;
+        return next;
+    });
+}

package/dist/runtime/src/install/preauth.js

@@ -41,8 +41,8 @@ export const CLAUDE_PREAUTH_UNSANDBOXED = [
     "npx lint-staged *"
 ];
 /** Added with the `run` profile: `agent-ops run` starts a launchd supervisor. */
-export const CLAUDE_PREAUTH_RUN_ALLOW = ["Bash(agent-ops run *)"];
-export const CLAUDE_PREAUTH_RUN_UNSANDBOXED = ["agent-ops run", "agent-ops run *"];
+export const CLAUDE_PREAUTH_RUN_ALLOW = ["Bash(agent-ops run *)", "Bash(agent-ops followup process *)"];
+export const CLAUDE_PREAUTH_RUN_UNSANDBOXED = ["agent-ops run", "agent-ops run *", "agent-ops followup process", "agent-ops followup process *"];
 export const CODEX_RULES_PATH = "rules/agent-ops.rules";
 export const CODEX_RULES_MARKER = "# agent-ops managed: regenerated by agent-ops init and update; do not edit.";
 const HOSTS = ["AGENT_OPS_HOST=codex", "AGENT_OPS_HOST=claude", "AGENT_OPS_HOST=agy"];
@@ -143,11 +143,18 @@ export const CODEX_RUN_RULE = rule({
     match: "env -u CODEX_SANDBOX_NETWORK_DISABLED agent-ops run --goal-file .agent-ops/state/run-goal.md --host codex --wait",
     notMatch: "env -u CODEX_SANDBOX_NETWORK_DISABLED agent-ops trust grant --scope project --yes"
 });
+export const CODEX_FOLLOWUP_RULE = rule({
+    withHost: false,
+    command: ["followup", "process"],
+    justification: "agent-ops followup process assesses one selected item and may start a native repair outside the sandbox.",
+    match: "env -u CODEX_SANDBOX_NETWORK_DISABLED agent-ops followup process followup-example --host codex",
+    notMatch: "env -u CODEX_SANDBOX_NETWORK_DISABLED agent-ops followup accept followup-example --reason accepted"
+});
 /** The rules file for worktree auto mode and the `run` profile, or null for neither. */
 export function codexRulesContent(worktree, run) {
     if (!run)
         return worktree ? CODEX_RULES_CONTENT : null;
-    return `${worktree ? CODEX_RULES_CONTENT : `${CODEX_RULES_MARKER}\n`}${CODEX_RUN_RULE}\n`;
+    return `${worktree ? CODEX_RULES_CONTENT : `${CODEX_RULES_MARKER}\n`}${CODEX_RUN_RULE}\n${CODEX_FOLLOWUP_RULE}\n`;
 }
 export function codexHomeDirectory(env = process.env) {
     return env.CODEX_HOME ?? join(env.HOME ?? homedir(), ".codex");
@@ -306,7 +313,7 @@ async function codexChange(codexHome, desired, run) {
                 content,
                 expectedHash: current?.hash ?? null
             },
-            summary: `Writes ${join(codexHome, CODEX_RULES_PATH)}: allow rules for ${desired ? `agent-ops review, batch, ${run ? "run, " : ""}doctor --check-auth, worktree commit and lint-staged` : "agent-ops run"}.`,
+            summary: `Writes ${join(codexHome, CODEX_RULES_PATH)}: allow rules for ${desired ? `agent-ops review, batch, ${run ? "run, followup process, " : ""}doctor --check-auth, worktree commit and lint-staged` : "agent-ops run and followup process"}.`,
             ownedContent: true
         };
 }

package/dist/runtime/src/parallel/finish.js

@@ -1,4 +1,5 @@
 import { withActivity } from "../office/activity.js";
+import { collectFollowupReceipt } from "../followup/intake.js";
 import { lstat, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
@@ -82,6 +83,7 @@ async function finishRunCleanup(deps, commonDir, record, proof, children) {
         await action();
         await markRunIntegration(commonDir, record, "receipt-written", name);
     };
+    let followup;
     try {
         await step("note", async () => {
             if (!noteBound)
@@ -90,6 +92,8 @@ async function finishRunCleanup(deps, commonDir, record, proof, children) {
                     proof.head], "WORKTREE_NOTE_FAILED", "Cannot bind the sealed receipt to its candidate.");
         });
         const config = await deps.loadConfig(record.mainRoot);
+        followup = await collectFollowupReceipt({ git: deps.git, mainRoot: record.mainRoot, commonDir, config,
+            loadConfig: async () => await deps.loadConfig(record.mainRoot), path: integration.receiptPath });
         await step("gate", async () => {
             if (!config.features.completionGate.enabled)
                 return;
@@ -118,7 +122,7 @@ async function finishRunCleanup(deps, commonDir, record, proof, children) {
         throw cause;
     }
     await recoverRunIntegrationAfterCleanup(commonDir, record.runId, deps.git);
-    return { record, mergedHead: proof.head, taskIds: (receipt.tasks ?? []).map(item => item.task.id), warnings: [],
+    return { record, mergedHead: proof.head, taskIds: (receipt.tasks ?? []).map(item => item.task.id), warnings: followup?.warnings ?? [], followup,
         receipt: integration.receiptPath, residualRisks: receipt.residualRisks ?? [] };
 }
 /**
@@ -562,6 +566,10 @@ export async function finishWorktree(deps, options) {
         await attempt("note", async () => await git(deps, mainRoot, ["notes", `--ref=${NOTES_REF}`, "add", "-f", "-m", finishNote, mergedHead], "WORKTREE_NOTE_FAILED", "Git could not write the agent-ops note."));
         if (receiptOptions !== undefined)
             await markRunIntegration(commonDir, record, "receipt-written", "note");
+        const followup = receipt === undefined ? undefined : await collectFollowupReceipt({ git: deps.git, mainRoot, commonDir, config: mainConfig,
+            loadConfig: async () => await deps.loadConfig(mainRoot), path: receipt.path });
+        if (followup !== undefined)
+            warnings.push(...followup.warnings);
         if (gateEnabled) {
             await attempt("gate", async () => {
                 const mainGate = await deps.gate(mainRoot, mainConfig);
@@ -598,7 +606,7 @@ export async function finishWorktree(deps, options) {
         await attempt("remove", async () => await removeCheckout(deps, record, options.finalProof === undefined, options.finalProof?.head));
         if (receiptOptions !== undefined)
             await markRunIntegration(commonDir, record, "cleaned", "coordinator");
-        return { record, mergedHead, taskIds: tree.map(({ task }) => task.task.id), warnings,
+        return { record, mergedHead, taskIds: tree.map(({ task }) => task.task.id), warnings, followup,
             ...(receipt === undefined ? {} : { receipt: receipt.path, residualRisks: receipt.receipt.residualRisks }) };
     }));
 }

package/dist/runtime/src/review/attestation.js

@@ -274,6 +274,16 @@ function parseAttestation(value) {
         createdAt: record.createdAt
     };
 }
+/** Validate a sealed pair without depending on a retired review checkout. */
+export function validateReviewPair(attestation, report) {
+    try {
+        const checked = parseAttestation(attestation);
+        return checked !== null && matchingReportArtifact(report, checked) ? checked : null;
+    }
+    catch {
+        return null;
+    }
+}
 export async function saveReviewAttestation(root, attestation) {
     const validated = parseAttestation(attestation);
     if (validated === null) {