@kylecheng3146/agent-ops 0.11.1 → 0.11.2

package/dist/packages/cli/src/run-entry.js

@@ -1,6 +1,7 @@
 import { criteriaReviewStatus } from "./criteria-review.js";
+import { collectFollowupReceipt } from "../../../runtime/src/followup/intake.js";
 import { renderCriteriaReview } from "../../../runtime/src/review/criteria.js";
-import { stat } from "node:fs/promises";
+import { rm, stat } from "node:fs/promises";
 import { recoverRunIntegrationAfterCleanup, validateRunIntegrationReceipt } from "../../../runtime/src/run/integration.js";
 import { pendingFindingPins } from "../../../runtime/src/run/ratchet.js";
 import { resolveReviewScope } from "../../../runtime/src/review/scope.js";
@@ -14,6 +15,7 @@ import { RunControlService, nativeResumeTime } from "../../../runtime/src/run/co
 import { beginPolicyTransition, markPolicyTransitionStage, completePolicyTransition, discoverPendingPolicyTransition } from "../../../runtime/src/run/policy-transition.js";
 import { readReviewReportArtifact } from "../../../runtime/src/review/attestation.js";
 import { execFile, spawn } from "node:child_process";
+import { redactSecrets } from "../../../runtime/src/security/redact.js";
 import { promisify } from "node:util";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -108,6 +110,84 @@ export function coordinatorWakeNote(state, coordinator) {
     return (coordinator.nativeSessionId === null ? "Fresh native session after wait; the earlier conversation is unavailable. " : "") +
         `Children: ${children.join("; ")}. Review deliveries, then plan follow-up workers and wait again, or request finalization.`;
 }
+export function workerInstructionLines() {
+    return ["Keep the original goal fixed. Read this repository's AGENTS.md and use its existing verifier authority.",
+        "Plan 2–5 substantive acceptance criteria. Submit a plan request before changing product files; the supervisor creates the task with the fixed goal.",
+        "Read the criteria advisory before implementation. Decide which suggestions to adopt and use task revise with reasons (including rejected advice). A revision does not automatically rerun criteria review; formal final proof remains required.",
+        "For every mechanically testable requirement use a configured acceptance runner; explicit review-only fallback requires a recorded reason and fresh goal review.",
+        "Implement, run targeted fast checks on changed code, commit and submit action=handoff so the supervisor runs full verification outside your context window. Do not poll full-suite verification in a loop. Repair failed checks and pin mechanically testable review findings into regression criteria. Never disable a mandatory policy verifier.",
+        "Only registered run workers may write. Use isolated worktrees and supervisor-issued leases; do not launch an unregistered writing subagent.",
+        "Commit product changes before revising the contract. A contract revision stops existing generations; dirty recovery preserves the checkout and blocks takeover.",
+        "Write one request atomically to .agent-ops/tasks/run-request.json; wait for matching run-response.json before another request.",
+        "Requests require requestId (unique alphanumeric or hyphen, max 64), workerId, generation and current contractHash.",
+        "Plan fields: action=plan,title,intent,criteria,surface (the EVIDENCE-SURFACE-001 audit object, same shape as task create --surface-file). Worker fields: action=worker,title,intent,criteria,dependencies (known worker task IDs; omit all acceptance baselines until dependencies are delivered),covers (parent included surface IDs this worker delivers; every included surface needs one worker).",
+        "Only the coordinator may change execution policy: submit action=policy, configFile (relative proposed JSON), expectedPolicyHash, approvals (each changed capabilityId command:<id>/runner:<id>/setup:<index>, classification=non-dangerous, reason assessing the entire fixed definition including setup/build). Commit source changes and wait until every writer is clean before requesting policy synchronization. Never use init/update/trust grant to create permanent execution authorization. Explicit native or organization denial must not be bypassed.",
+        "Worker task baselines are frozen after dependency commits enter its checkout. Handoff fields: action=handoff,sourceFiles (explicit existing source paths when unchanged). Question fields: action=question,prompt. Coordinator wait fields: action=wait, sent once every worker is planned instead of polling run status; the supervisor stops the coordinator and starts it again, in a fresh session with a child-status diagnostic, after every child is delivered, complete or blocked. Coordinator finalize fields: action=finalize.",
+        "The supervisor, after stopping writers, runs final verification, two fresh reviews and finish. A native completed goal is never final proof."];
+}
+export function workerGoalPrompt() {
+    return "Read .agent-ops/tasks/run-instructions.json and carry its immutable original goal through the evidence loop. Submit a plan if rootTaskId is null; otherwise implement and repair the assigned task. A child runs targeted fast checks, commits, and requests handoff so the supervisor executes full verification; the coordinator submits action=wait after planning its children, then requests finalization once all have delivered. Never substitute native goal completion for agent-ops evidence.";
+}
+/** Drop the old native thread for a stopped or fenced writer on a clean checkout so repair starts without context bloat. */
+export async function resetStoppedRepairThread(repository, runId, workerId, generation, cleanCheckout = true) {
+    const state = await repository.mutate(runId, current => ({
+        ...current,
+        workers: current.workers.map(w => w.workerId === workerId && w.generation === generation && ["stopped", "fenced"].includes(w.status) && cleanCheckout
+            ? { ...w, nativeSessionId: null, nativeJobId: null }
+            : w)
+    }));
+    const worker = state.workers.find(w => w.workerId === workerId);
+    if (worker === undefined)
+        throw new AgentOpsError("RUN_WORKER_NOT_FOUND", `Unknown worker ${workerId}.`);
+    return worker;
+}
+/** Check persisted requests/<sha256(requestId)>.json completion artifacts before rejecting across generations. */
+export async function reconcileWorkerRequest(options) {
+    const { repository, directory, commonDir, runId, worker, source, requestPath } = options;
+    async function rejectRequest(code) {
+        const digest = sha256(source);
+        const diagnostic = join(directory, runId, "invalid-requests", worker.workerId + "-" + worker.generation + "-" + digest + ".json");
+        if (await readPrivateFile(diagnostic, commonDir) === null) {
+            await writePrivateFile(diagnostic, canonicalJson({ code, workerId: worker.workerId, generation: worker.generation, requestDigest: digest }), commonDir);
+            await repository.appendEvent(runId, { type: "diagnostic", code, workerId: worker.workerId, taskId: worker.taskId,
+                detail: "Supervisor request is malformed or stale; a diagnostic response is available in the current checkout." });
+        }
+        await writePrivateFile(join(worker.worktree, ".agent-ops/tasks/run-response.json"), JSON.stringify({ code,
+            workerId: worker.workerId, generation: worker.generation, error: "Read current run-instructions.json and replace the malformed or stale request atomically." }), worker.worktree);
+        return { kind: "rejected", code };
+    }
+    let request;
+    try {
+        request = JSON.parse(source);
+    }
+    catch {
+        return await rejectRequest("RUN_REQUEST_INVALID");
+    }
+    if (!plain(request) || typeof request.requestId !== "string" || !/^[A-Za-z0-9-]{1,64}$/u.test(request.requestId))
+        return await rejectRequest("RUN_REQUEST_INVALID");
+    const donePath = join(directory, runId, "requests", sha256(request.requestId) + ".json");
+    const requestDigest = sha256(canonicalJson(request));
+    const completed = await readPrivateFile(donePath, commonDir);
+    if (completed !== null && request.workerId === worker.workerId) {
+        const cached = JSON.parse(completed);
+        const sameGeneration = request.generation === worker.generation;
+        if (plain(cached) && cached.requestDigest === requestDigest) {
+            if (sameGeneration)
+                await writePrivateFile(join(worker.worktree, ".agent-ops", "tasks", "run-response.json"), JSON.stringify(cached.response), worker.worktree);
+            await rm(requestPath, { force: true }).catch(() => { });
+            return { kind: "completed", sameGeneration };
+        }
+        if (sameGeneration) {
+            const conflict = { requestId: request.requestId, code: "RUN_REQUEST_ID_CONFLICT", error: "A request ID cannot be reused for different content." };
+            await writePrivateFile(join(worker.worktree, ".agent-ops", "tasks", "run-response.json"), JSON.stringify(conflict), worker.worktree);
+            await rm(requestPath, { force: true }).catch(() => { });
+            return { kind: "completed", sameGeneration: true };
+        }
+    }
+    if (request.workerId !== worker.workerId || request.generation !== worker.generation)
+        return await rejectRequest("RUN_REQUEST_STALE");
+    return { kind: "active", request, donePath, requestDigest };
+}
 /** Retain the structured child failure instead of hiding it behind recovery text. */
 export function runStepError(result, fallback) {
     const details = Array.isArray(result.errors) ? result.errors.filter(plain)
@@ -238,22 +318,10 @@ export async function superviseNativeRun(root, runId) {
             const content = { criteriaAdvisory: criteriaAdvice === null ? null : renderCriteriaReview(criteriaAdvice), runId, workerId: worker.workerId, generation: worker.generation, contractHash: current.currentContractHash,
                 originalGoal: current.goal, answers, rootTaskId: current.rootTaskId, taskId: worker.taskId, cli, ownerSessionId: worker.ownerSessionId,
                 policyConfigHash: current.policyBinding?.configHash,
-                instructions: ["Keep the original goal fixed. Read this repository's AGENTS.md and use its existing verifier authority.",
-                    "Plan 2–5 substantive acceptance criteria. Submit a plan request before changing product files; the supervisor creates the task with the fixed goal.",
-                    "Read the criteria advisory before implementation. Decide which suggestions to adopt and use task revise with reasons (including rejected advice). A revision does not automatically rerun criteria review; formal final proof remains required.",
-                    "For every mechanically testable requirement use a configured acceptance runner; explicit review-only fallback requires a recorded reason and fresh goal review.",
-                    "Implement, commit and verify. Repair failed checks and pin mechanically testable review findings into regression criteria. Never disable a mandatory policy verifier.",
-                    "Only registered run workers may write. Use isolated worktrees and supervisor-issued leases; do not launch an unregistered writing subagent.",
-                    "Commit product changes before revising the contract. A contract revision stops existing generations; dirty recovery preserves the checkout and blocks takeover.",
-                    "Write one request atomically to .agent-ops/tasks/run-request.json; wait for matching run-response.json before another request.",
-                    "Requests require requestId (unique alphanumeric or hyphen, max 64), workerId, generation and current contractHash.",
-                    "Plan fields: action=plan,title,intent,criteria,surface (the EVIDENCE-SURFACE-001 audit object, same shape as task create --surface-file). Worker fields: action=worker,title,intent,criteria,dependencies (known worker task IDs; omit all acceptance baselines until dependencies are delivered),covers (parent included surface IDs this worker delivers; every included surface needs one worker).",
-                    "Only the coordinator may change execution policy: submit action=policy, configFile (relative proposed JSON), expectedPolicyHash, approvals (each changed capabilityId command:<id>/runner:<id>/setup:<index>, classification=non-dangerous, reason assessing the entire fixed definition including setup/build). Commit source changes and wait until every writer is clean before requesting policy synchronization. Never use init/update/trust grant to create permanent execution authorization. Explicit native or organization denial must not be bypassed.",
-                    "Worker task baselines are frozen after dependency commits enter its checkout. Handoff fields: action=handoff,sourceFiles (explicit existing source paths when unchanged). Question fields: action=question,prompt. Coordinator wait fields: action=wait, sent once every worker is planned instead of polling run status; the supervisor stops the coordinator and starts it again, in a fresh session with a child-status diagnostic, after every child is delivered, complete or blocked. Coordinator finalize fields: action=finalize.",
-                    "The supervisor, after stopping writers, runs final verification, two fresh reviews and finish. A native completed goal is never final proof."], diagnostic };
+                instructions: workerInstructionLines(), diagnostic };
             const path = join(worker.worktree, ".agent-ops", "tasks", "run-instructions.json");
             await writePrivateFile(path, JSON.stringify(content, null, 2), worker.worktree);
-            return "Read .agent-ops/tasks/run-instructions.json and carry its immutable original goal through the evidence loop. Submit a plan if rootTaskId is null; otherwise implement and repair the assigned task. A child requests handoff after local green; the coordinator submits action=wait after planning its children, then requests finalization once all have delivered. Never substitute native goal completion for agent-ops evidence.";
+            return workerGoalPrompt();
         }
         async function start(worker, diagnostic, resumeAt) {
             if (await discoverPendingPolicyTransition(repository, runId) !== null)
@@ -559,8 +627,11 @@ export async function superviseNativeRun(root, runId) {
                 return;
             }
             const latest = result.state.workers.find(w => w.workerId === worker.workerId);
-            if (["fenced", "stopped"].includes(latest.status))
-                await start(latest, message);
+            if (["fenced", "stopped"].includes(latest.status)) {
+                const clean = latest.worktree !== null && (await collectChangeSurface(gitRunner(latest.worktree))).paths.length === 0;
+                const reset = await resetStoppedRepairThread(repository, runId, latest.workerId, latest.generation, clean);
+                await start(reset, message);
+            }
             else
                 await supervisor.sendRepair(runId, worker.workerId, worker.generation, message);
         }
@@ -594,6 +665,17 @@ export async function superviseNativeRun(root, runId) {
                 contractRevision: current.contractRevision + (current.currentContractHash === finalContract ? 0 : 1) }));
             await supervisor.finalize(runId, { targetCommit: receipt.candidateHead, candidateCommit: receipt.candidateHead,
                 verificationPass: true, reviewPass: true, taskStateComplete: true, receiptWritten: true, receiptDigest: sha256(source) });
+            try {
+                const followup = await collectFollowupReceipt({ git: deps.git, mainRoot: root, commonDir,
+                    path, config: await deps.loadConfig(root), loadConfig: async () => await deps.loadConfig(root) });
+                for (const warning of followup.warnings)
+                    await repository.appendEvent(runId, { type: "diagnostic",
+                        code: "FOLLOWUP_RECONCILIATION_PENDING", workerId: null, taskId: null, detail: warning });
+            }
+            catch {
+                await repository.appendEvent(runId, { type: "diagnostic", code: "FOLLOWUP_RECONCILIATION_PENDING",
+                    workerId: null, taskId: null, detail: "Completion remains valid; followup reconciliation needs retry." }).catch(() => { });
+            }
             try {
                 await stopAll("stop");
                 await launchd.disableRestart(runDescriptor(current), "verified final integration completed");
@@ -728,47 +810,18 @@ export async function superviseNativeRun(root, runId) {
                             await repair(worker, "RUN_NATIVE_COMPLETION_UNPROVEN", "Native completion has no agent-ops delivery or final receipt. Read run-instructions.json, complete the evidence loop and submit handoff or finalize.");
                         continue;
                     }
-                    async function rejectRequest(code) {
-                        const digest = sha256(source);
-                        const diagnostic = join(directory, runId, "invalid-requests", worker.workerId + "-" + worker.generation + "-" + digest + ".json");
-                        if (await readPrivateFile(diagnostic, commonDir) === null) {
-                            await writePrivateFile(diagnostic, canonicalJson({ code, workerId: worker.workerId, generation: worker.generation, requestDigest: digest }), commonDir);
-                            await repository.appendEvent(runId, { type: "diagnostic", code, workerId: worker.workerId, taskId: worker.taskId,
-                                detail: "Supervisor request is malformed or stale; a diagnostic response is available in the current checkout." });
-                        }
-                        await writePrivateFile(join(worker.worktree, ".agent-ops/tasks/run-response.json"), JSON.stringify({ code,
-                            workerId: worker.workerId, generation: worker.generation, error: "Read current run-instructions.json and replace the malformed or stale request atomically." }), worker.worktree);
+                    const reconciled = await reconcileWorkerRequest({ repository, directory, commonDir, runId, worker, source, requestPath });
+                    if (reconciled.kind === "rejected") {
                         if (observation.nativeGoalState === "complete")
-                            await repair(worker, code, "A malformed or stale request cannot establish completion. Read current run-instructions.json and replace run-request.json atomically.");
-                    }
-                    let request;
-                    try {
-                        request = JSON.parse(source);
-                    }
-                    catch {
-                        await rejectRequest("RUN_REQUEST_INVALID");
+                            await repair(worker, reconciled.code, "A malformed or stale request cannot establish completion. Read current run-instructions.json and replace run-request.json atomically.");
                         continue;
                     }
-                    if (!plain(request) || typeof request.requestId !== "string" || !/^[A-Za-z0-9-]{1,64}$/u.test(request.requestId)) {
-                        await rejectRequest("RUN_REQUEST_INVALID");
-                        continue;
-                    }
-                    if (request.workerId !== worker.workerId || request.generation !== worker.generation) {
-                        await rejectRequest("RUN_REQUEST_STALE");
-                        continue;
-                    }
-                    const donePath = join(directory, runId, "requests", sha256(request.requestId) + ".json");
-                    const requestDigest = sha256(canonicalJson(request));
-                    const completed = await readPrivateFile(donePath, commonDir);
-                    if (completed !== null) {
-                        const cached = JSON.parse(completed);
-                        const response = plain(cached) && cached.requestDigest === requestDigest ? cached.response :
-                            { requestId: request.requestId, code: "RUN_REQUEST_ID_CONFLICT", error: "A request ID cannot be reused for different content." };
-                        await writePrivateFile(join(worker.worktree, ".agent-ops", "tasks", "run-response.json"), JSON.stringify(response), worker.worktree);
-                        if (observation.nativeGoalState === "complete")
+                    if (reconciled.kind === "completed") {
+                        if (reconciled.sameGeneration && observation.nativeGoalState === "complete")
                             await repair(worker, "RUN_NATIVE_COMPLETION_UNPROVEN", "The previous request response is available, but current delivery or final proof is still missing. Continue the assigned goal and submit a new request.");
                         continue;
                     }
+                    const { request, donePath, requestDigest } = reconciled;
                     const current = (await repository.read(runId));
                     let response;
                     try {
@@ -946,6 +999,7 @@ export async function superviseNativeRun(root, runId) {
                         }
                     }
                     await writePrivateFile(donePath, JSON.stringify({ requestDigest, response }), commonDir);
+                    await rm(requestPath, { force: true }).catch(() => { });
                     const after = (await repository.read(runId));
                     if (after.status === "complete") {
                         await writePrivateFile(join(directory, runId, "final-response.json"), JSON.stringify(response), commonDir);
@@ -992,7 +1046,9 @@ export async function runControlledStep(repository, cli, cwd, args, saved) {
         delete env.AGENT_OPS_AGENT_ID;
         delete env.CODEX_SANDBOX_NETWORK_DISABLED;
         const child = spawn(process.execPath, [fileURLToPath(new URL("./run-step-entry.js", import.meta.url)), cli, ...args, "--json"], { cwd, env, detached: process.platform !== "win32", stdio: ["pipe", "pipe", "pipe"] });
-        let output = "";
+        let output = Buffer.alloc(0), diagnostic = Buffer.alloc(0);
+        let outputOverflow = false;
+        let spawnError;
         let closed = false;
         let escalation;
         const terminate = () => {
@@ -1015,7 +1071,7 @@ export async function runControlledStep(repository, cli, cwd, args, saved) {
             const identity = child.pid === undefined ? null : await nativeProcessIdentity(child.pid);
             if (identity === null || closed) {
                 terminate();
-                return;
+                throw new Error("Controlled process identity unavailable.");
             }
             await repository.mutate(runId, current => {
                 if (current.status !== "active" || current.disableRestart) {
@@ -1042,22 +1098,54 @@ export async function runControlledStep(repository, cli, cwd, args, saved) {
                     terminate();
             }).catch(terminate).finally(() => { checking = false; });
         }, 250);
-        child.stdout.on("data", chunk => { output += chunk.toString(); if (Buffer.byteLength(output) > 4 * 1024 * 1024)
-            terminate(); });
-        child.stderr.resume();
-        child.once("error", cause => { closed = true; clearTimeout(timeout); clearInterval(control); reject(cause); });
-        child.once("close", async () => {
+        child.stdout.on("data", (chunk) => {
+            const room = 4 * 1024 * 1024 - output.length;
+            if (room > 0)
+                output = Buffer.concat([output, chunk.subarray(0, room)]);
+            if (chunk.length > room) {
+                outputOverflow = true;
+                terminate();
+            }
+        });
+        child.stderr.on("data", (chunk) => {
+            const room = 64 * 1024 - diagnostic.length;
+            if (room > 0)
+                diagnostic = Buffer.concat([diagnostic, chunk.subarray(0, room)]);
+        });
+        child.once("error", cause => { spawnError = cause; terminate(); });
+        child.once("close", async (exitCode, signal) => {
             closed = true;
             clearTimeout(timeout);
             clearTimeout(escalation);
             clearInterval(control);
+            let stage = "registration";
             try {
-                await registration;
+                // Cleanup ownership even when registration or the subprocess failed.
+                let registrationError;
+                try {
+                    await registration;
+                }
+                catch (cause) {
+                    registrationError = cause;
+                }
+                stage = "cleanup";
                 await repository.mutate(runId, current => ({ ...current,
                     ...(current.proofProcess?.processId === child.pid ? { proofProcess: null } : {}) }));
-                const result = JSON.parse(output);
+                stage = "registration";
+                if (registrationError !== undefined)
+                    throw registrationError;
+                stage = "process";
+                if (spawnError !== undefined)
+                    throw spawnError;
+                if (signal !== null || outputOverflow)
+                    throw new Error(outputOverflow ? "Result exceeded 4 MiB." : "Controlled process was signaled.");
+                stage = "result";
+                const result = JSON.parse(output.toString("utf8"));
                 if (!plain(result) || !["ok", "error"].includes(String(result.status)) || typeof result.code !== "string")
-                    throw new Error();
+                    throw new Error("Invalid result envelope.");
+                if (result.status === "ok" && exitCode !== 0)
+                    throw new Error("Successful envelope with unsuccessful process exit.");
+                stage = "usage";
                 const coordinatorRoot = saved.workers[0]?.worktree;
                 if (!criteria && result.status === "error" && coordinatorRoot != null)
                     await recordSavedReviewRunUsage(repository, runId, coordinatorRoot);
@@ -1069,8 +1157,15 @@ export async function runControlledStep(repository, cli, cwd, args, saved) {
                 }
                 resolve(result);
             }
-            catch {
-                reject(new AgentOpsError("RUN_FINAL_PROOF_INTERRUPTED", "Final gate did not return a complete result; inspect target and receipt before retrying."));
+            catch (cause) {
+                const excerpt = (value) => redactSecrets(value)
+                    .replace(/-----BEGIN (?:[A-Z0-9]+ )?PRIVATE KEY-----[\s\S]*$/u, "[REDACTED_PRIVATE_KEY]").slice(0, 3500);
+                const detail = JSON.stringify({ exitCode, signal, stage, outputOverflow,
+                    cause: excerpt(cause instanceof Error ? cause.message : String(cause)),
+                    stderr: excerpt(diagnostic.toString("utf8")), stdout: excerpt(output.toString("utf8").slice(0, 4096)) }).slice(0, 9500);
+                await repository.appendEvent(runId, { type: "diagnostic", code: "RUN_CONTROLLED_STEP_FAILED",
+                    workerId: env.AGENT_OPS_WORKER_ID ?? null, taskId: saved.workers.find(w => w.worktree === cwd)?.taskId ?? null, detail }).catch(() => undefined);
+                reject(new AgentOpsError("RUN_FINAL_PROOF_INTERRUPTED", "Final gate did not return a complete result; inspect target and receipt before retrying. " + detail));
             }
         });
     });

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

@@ -0,0 +1,75 @@
+import { lstat, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { AgentOpsError } from "../fs/paths.js";
+import { readDeliveredReceipt } from "./receipt.js";
+import { FileFollowupStore, followupIdentity } from "./store.js";
+import { reconcileFollowupRepairs } from "./process.js";
+function warning(error) {
+    const code = error instanceof AgentOpsError && /^[A-Z0-9_]{1,80}$/u.test(error.code) ? error.code : "FOLLOWUP_COLLECTION_FAILED";
+    return `followup: ${code}; original completion is unchanged. Retry with followup import.`;
+}
+/** Metadata-only and fail-open: collection cannot invalidate a successful finish. */
+export async function collectFollowupReceipt(options) {
+    try {
+        const { receipt, digest, reviews } = await readDeliveredReceipt(options);
+        const pending = [];
+        for (const review of reviews)
+            for (const round of ["primary", "adversarial"]) {
+                const report = round === "primary" ? review.artifact.report : review.artifact.adversarial.report;
+                const provenance = { receiptPath: options.path, receiptDigest: digest, receiptSchemaVersion: receipt.schemaVersion,
+                    candidateHead: receipt.candidateHead, targetCommit: receipt.targetCommit, sourceFingerprint: receipt.sourceFingerprint,
+                    taskId: review.taskId, reportDigest: review.reportDigest, round, provenanceLimit: review.provenanceLimit };
+                const add = (sourceKind, original, index) => {
+                    const source = { ...provenance, sourceKind, index };
+                    pending.push({ id: followupIdentity(source), kind: sourceKind === "finding" ? "candidate" : "observation",
+                        original, provenance: source, disposition: "pending", history: [{ at: new Date().toISOString(), action: "collected" }] });
+                };
+                report.findings.forEach((finding, index) => { if (!finding.blocking)
+                    add("finding", finding, index); });
+                report.residualRisks.forEach((risk, index) => add("residual-risk", risk, index));
+            }
+        const collected = await new FileFollowupStore(options.commonDir).mutate(items => {
+            const known = new Set(items.map(item => item.id));
+            const added = pending.filter(item => !known.has(item.id));
+            items.push(...added);
+            return { added: added.length, candidates: added.filter(item => item.kind === "candidate").length,
+                observations: added.filter(item => item.kind === "observation").length, warnings: [] };
+        });
+        const warnings = options.config === undefined ? [] : await reconcileFollowupRepairs({ ...options, config: options.config });
+        return { ...collected, warnings };
+    }
+    catch (error) {
+        return { added: 0, candidates: 0, observations: 0, warnings: [warning(error)] };
+    }
+}
+/** Historical import never launches assessment, repair, models or provider calls. */
+export async function reconcileFollowups(options) {
+    const result = { added: 0, candidates: 0, observations: 0, warnings: [] };
+    try {
+        const directory = join(options.commonDir, "agent-ops", "receipts");
+        // Checking through the private reader rejects symlinked ancestors before enumeration.
+        await new FileFollowupStore(options.commonDir).read();
+        const status = await lstat(directory);
+        if (!status.isDirectory() || status.isSymbolicLink())
+            throw new AgentOpsError("PRIVATE_STATE_PATH_INVALID", "Receipt directory is unsafe.");
+        const names = (await readdir(directory)).filter(name => /^[a-f0-9]{64}-[a-f0-9]{40,64}\.json$/u.test(name)).sort();
+        const { config: _config, loadConfig: _loadConfig, ...source } = options;
+        for (const name of names) {
+            const collected = await collectFollowupReceipt({ ...source, path: join(directory, name) });
+            result.added += collected.added;
+            result.candidates += collected.candidates;
+            result.observations += collected.observations;
+            // Repeated malformed sources cannot flood normal CLI diagnostics.
+            for (const item of collected.warnings)
+                if (!result.warnings.includes(item) && result.warnings.length < 8)
+                    result.warnings.push(item);
+        }
+        if (options.config !== undefined)
+            result.warnings.push(...await reconcileFollowupRepairs({ ...options, config: options.config }));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            result.warnings.push(warning(error));
+    }
+    return result;
+}