@kylecheng3146/agent-ops 0.11.0 → 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/harness.js

@@ -367,7 +367,7 @@ export function managedRules(descriptor, context) {
     if (context.capabilities.includes("task"))
         lines.push("To fix a bug, run `agent-ops task create --debug --goal <verbatim issue>` with a", "behavioral criterion whose `redCheckIds` fail at the baseline and pass on the", "candidate, then verify, review and finish as for any task. If you know where the", "bug came from, record it with `task revise --escape-of <commit> --escape-label", "<label>`; the origin is advisory and never blocks finish.", "");
     if (context.capabilities.includes("rules")) {
-        lines.push("For every change:", "", "1. Audit the change's surfaces first (EVIDENCE-SURFACE-001): dependents,", "   duplicates, other paths to the same concept, and shared state/data", "   contracts, each with recorded fixed-string queries or n/a: reason; pass", "   them with `task create --surface-file <json>`. An exclusion says why", "   the surface is unaffected; \"out of scope\" is not a reason. A derived", "   discovery query whose hits are all incidental may be dismissed once with", "   a reason in `dismissed` instead of excluding each file. Then define", "   two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope within the audited surfaces and", "   preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Start this command through the trusted outer host runner as its first", "   and only invocation. On Codex, the outer tool request must use", "   `sandbox_permissions: \"require_escalated\"` so network and loopback", "   are available; in that same request, unset", "   `CODEX_SANDBOX_NETWORK_DISABLED` and set `AGENT_OPS_HOST` when three", "   targets are configured. The Codex shell form is", "   `env -u CODEX_SANDBOX_NETWORK_DISABLED AGENT_OPS_HOST=<current-host> agent-ops review --task <task-id> --yes`.", "   Keep it a plain command line: to keep the output add `--output <file>`", "   (the JSON envelope is written there and one line is printed) instead of", "   a shell redirect, which the host can only allow by matching the whole", "   command string, task id included.", "   Do not run it once in the restricted sandbox and retry; changing the", "   variable inside that sandbox is not elevation.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
+        lines.push("   Every production task creation waits for one independent criteria advisory", "   before implementation (also DEBUG and native run parents/children). It has", "   no time/token budget; real launch/auth/output errors report NOT_RUN and", "   allow work, while explicit cancellation means stop. Read the private report,", "   decide which advice to adopt, and use task revise with reasons (including", "   rejections). Revise does not rerun it. Explicit rerun only:", "   `agent-ops review --criteria --task <id> --rerun --yes`.", "   Start task creation/criteria review through the trusted outer host when", "   the host sandbox blocks reviewer auth/network, using the same outer-host", "   invocation described below for review. Never bypass a native denial.", "   This advisory never replaces verify, final two-round review or finish.", "", "For every change:", "", "1. Audit the change's surfaces first (EVIDENCE-SURFACE-001): dependents,", "   duplicates, other paths to the same concept, and shared state/data", "   contracts, each with recorded fixed-string queries or n/a: reason; pass", "   them with `task create --surface-file <json>`. An exclusion says why", "   the surface is unaffected; \"out of scope\" is not a reason. A derived", "   discovery query whose hits are all incidental may be dismissed once with", "   a reason in `dismissed` instead of excluding each file. Then define", "   two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope within the audited surfaces and", "   preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Start this command through the trusted outer host runner as its first", "   and only invocation. On Codex, the outer tool request must use", "   `sandbox_permissions: \"require_escalated\"` so network and loopback", "   are available; in that same request, unset", "   `CODEX_SANDBOX_NETWORK_DISABLED` and set `AGENT_OPS_HOST` when three", "   targets are configured. The Codex shell form is", "   `env -u CODEX_SANDBOX_NETWORK_DISABLED AGENT_OPS_HOST=<current-host> agent-ops review --task <task-id> --yes`.", "   Keep it a plain command line: to keep the output add `--output <file>`", "   (the JSON envelope is written there and one line is printed) instead of", "   a shell redirect, which the host can only allow by matching the whole", "   command string, task id included.", "   Do not run it once in the restricted sandbox and retry; changing the", "   variable inside that sandbox is not elevation.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
     }
     if (context.capabilities.includes("task")) {
         lines.push("Split a change that exceeds five acceptance criteria into subtasks:", "`agent-ops task create --parent <task-id>` records one, and", "`agent-ops task status --parent <task-id>` lists them. Each subtask", "carries its own criteria and verification; final review covers all", "tasks together when their worktrees are integrated;", "completing one never completes its parent.", "", ...autoRunInstruction(descriptor, context), "To review every active subtask of a parent together, run", "`agent-ops batch --parent <task-id> --yes` instead of one review per", "subtask. It needs what review needs: start it through the trusted outer", "host runner as its first and only invocation, with the same Codex", "elevation, and keep `--output <file>` instead of a shell redirect. It", "verifies, one task at a time, each task that lacks fresh evidence, and", "reviews a few tasks at once. Do not commit or edit the worktree while it", "runs: a moved HEAD voids every verify and review in the batch.", "For subagents in separate worktrees, use `task advance` instead.", "", "Delegate a subtask whose scope spans unknown files, broad scans, or an", "independent workstream instead of doing it inline. Name the bounded", "scope, the artifact to return, and the acceptance criteria it serves.", subagentInstruction(descriptor), "Read every returned artifact back yourself: integration, verification,", "and review stay with the coordinator.", "", "One writer at a time. `agent-ops verify` and `agent-ops review`", "fingerprint the working tree and report UNKNOWN when anything else", "writes it during the run, so delegate edits to one subagent at a time,", "or give each writer its own Git worktree and merge before verifying.", "Read-only delegation has no such limit and may run in parallel.", "", "Parallel conversations in one repository each need their own worktree.", "When `.agent-ops/config.json` sets `worktree.mode` to `auto`, run", "`agent-ops task create` from the main checkout before your first edit:", "it creates this session's worktree and puts the task there (`agent-ops", "worktree add <name> --session <session-id>` does the same without a", "task). Work only inside the printed path", "(Claude Code: EnterWorktree with that path; otherwise use it as every", "command's working directory). Commit, then run verify and review for", "each task with the printed `--base`; do not run `task complete` in the", "worktree. Leave it (Claude Code: ExitWorktree with action keep) and run", "`agent-ops worktree finish <name>` from the main checkout: it completes", "every task in the worktree, subtasks first, then merges. A finish that", "reports an incomplete task names it; verify or review that task again", "in the worktree and finish again. A finish that reports a conflict is", "resolved once, as a new task whose criteria cover both intents; if its", "verification or review fails, reset as instructed and report.", "", "For a session with writing subagents, record each child task's complete", "modification intent with `task create --intent <text>` before editing.", "Each child commits and runs local `verify --task` in its own worktree.", "From the main checkout run `agent-ops task advance --task <parent-id>", "--session <session-id> --yes` through the trusted outer host runner,", "unsetting `CODEX_SANDBOX_NETWORK_DISABLED` on Codex. Advance integrates", "child commits and intent into the coordinator worktree, verifies every", "task on the final candidate, then runs one two-round tree review.", "Only `NOT_RUN / scope-too-large` falls back to per-task two-round review;", "a substantive FAIL must be fixed. After PASS, advance writes a local", "receipt under the main checkout's Git common directory and calls finish.", "If the target moves, it retries the final gate once. An unresolved", "failure preserves worktrees and cannot be reported as finished.", "");

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/logging/local-log.js

@@ -29,6 +29,18 @@ function sanitizeEvent(value) {
     if (!isRecord(value) || typeof value.type !== "string") {
         return invalidEvent();
     }
+    if (value.type === "criteria-review") {
+        if (!hasExactKeys(value, ["type", "taskId", "attemptId", "status", "code", "durationMs", "invocations", "recommendations", "report", "usage"]) ||
+            typeof value.taskId !== "string" || !ID_PATTERN.test(value.taskId) ||
+            typeof value.attemptId !== "string" || !/^[a-f0-9-]{36}$/u.test(value.attemptId) ||
+            !["RUNNING", "COMPLETED", "NOT_RUN", "CANCELLED"].includes(String(value.status)) ||
+            typeof value.code !== "string" || !ID_PATTERN.test(value.code) || !isBoundedString(value.report) ||
+            ![value.durationMs, value.invocations, value.recommendations].every(n => Number.isSafeInteger(n) && n >= 0) ||
+            !isRecord(value.usage) || Object.entries(value.usage).some(([key, n]) => !["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "costUsd"].includes(key) ||
+            typeof n !== "number" || !Number.isFinite(n) || n < 0))
+            return invalidEvent();
+        return { ...value, report: redactSecrets(value.report) };
+    }
     if (value.type === "diagnostic") {
         if (!hasExactKeys(value, ["code", "type"]) ||
             typeof value.code !== "string" ||