@kylecheng3146/agent-ops 0.11.1 → 0.11.3

package/README.md

@@ -17,7 +17,9 @@ command behavior may change before 1.0.
 Every new task, including DEBUG and native run parent/child tasks, waits for one
 independent advisory review of its goal, criteria and assigned surface before
 implementation. Read the suggestions, decide which to adopt, and record reasons
-through `task revise`. Revisions do not automatically re-review.
+through `task revise`. The first revision that changes criteria, intent or
+goal reruns the advisory once; surface-only revisions do not, and later
+reruns are explicit (`review --criteria --rerun`).
 
 The advisory has no time/token budget; explicit cancellation stops work. Genuine
 execution errors report NOT_RUN and allow work. Detailed reports remain private;
@@ -521,6 +523,12 @@ as its first and only invocation, with `--output` instead of a shell redirect.
 
 See [Configuration](docs/en/guides/configuration.md) for the full contract.
 
+Retained nonblocking review findings and residual risks are collected privately
+across linked worktrees. Use `agent-ops followup list` / `show`, metadata-only
+`import`, reasoned `accept` / `defer`, and explicit `process <followup-id> --host
+codex` for current-source revalidation and bounded repair. Observations need
+`clarify`; resolution needs finding-specific proof. See [followup guidance](docs/en/guides/task-debug.md#retained-review-followups).
+
 ## Project principles
 
 - Define verifiable success before making changes.

package/dist/packages/cli/src/args.js

@@ -14,7 +14,8 @@ export const COMMAND_NAMES = [
     "worktree",
     "run",
     "office",
-    "escapes"
+    "escapes",
+    "followup"
 ];
 const COMMAND_SET = new Set(COMMAND_NAMES);
 const SCOPES = new Set(["project", "user"]);
@@ -64,6 +65,8 @@ function parseHookTarget(option, value) {
     return { harness: harness, surfaceId };
 }
 export function parseArgs(argv) {
+    if (argv[0] === "followup")
+        return parseFollowupArgs(argv.slice(1));
     if (argv[0] === "run")
         return parseRunArgs(argv.slice(1));
     if (argv[0] === "task" && argv[1] === "debug")
@@ -945,10 +948,15 @@ function parseRunArgs(argv) {
             args.wait = true;
             continue;
         }
-        if (!["--host", "--goal-file", "--time-budget", "--jobs", "--question-id", "--answer", "--answer-file", "--retry-approval"].includes(token))
+        if (!["--host", "--goal-file", "--time-budget", "--jobs", "--question-id", "--answer", "--answer-file", "--retry-approval", "--retry-delivery"].includes(token))
             throw new CliArgumentError("CLI_UNKNOWN_OPTION", `Unknown run option: ${token}`, token);
         const value = readOptionValue(argv, i++, token);
         switch (token) {
+            case "--retry-delivery":
+                if (!/^task-[a-z0-9-]{1,128}$/u.test(value))
+                    invalidValue(token, value);
+                args.retryDeliveryTaskId = value;
+                break;
             case "--retry-approval":
                 if (!/^auth-[a-f0-9]{64}$/u.test(value) || args.retryApprovalIds?.includes(value))
                     invalidValue(token, value);
@@ -983,6 +991,8 @@ function parseRunArgs(argv) {
     }
     if (args.retryApprovalIds !== undefined && action !== "resume")
         throw new CliArgumentError("CLI_INVALID_OPTION", "--retry-approval requires run resume.");
+    if (args.retryDeliveryTaskId !== undefined && (action !== "resume" || args.retryApprovalIds !== undefined))
+        throw new CliArgumentError("CLI_INVALID_OPTION", "--retry-delivery requires run resume without --retry-approval.");
     if (action === "start") {
         args.goal = positional;
         if ((args.goal === undefined) === (args.goalFile === undefined))
@@ -1007,3 +1017,59 @@ function parseRunArgs(argv) {
     }
     return args;
 }
+function parseFollowupArgs(argv) {
+    const args = { command: "followup", profiles: [], dryRun: false, json: false, yes: false, rerun: false };
+    if (argv.includes("--help") || argv.includes("-h"))
+        return { ...args, command: "help", helpTopic: "followup", json: argv.includes("--json") };
+    const actions = ["list", "show", "import", "sync", "clarify", "accept", "defer", "reopen", "process"];
+    const action = argv[0] === undefined || argv[0].startsWith("-") ? "list" : argv[0];
+    if (!actions.includes(action))
+        invalidValue("followup action", action);
+    args.action = action;
+    const seen = new Set();
+    for (let i = argv[0] === action ? 1 : 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (!token.startsWith("-")) {
+            if (args.followupId !== undefined)
+                throw new CliArgumentError("CLI_UNEXPECTED_ARGUMENT", "Select exactly one followup identity.");
+            if (!/^followup-[a-f0-9]{64}$/u.test(token))
+                invalidValue("followup identity", token);
+            args.followupId = token;
+            continue;
+        }
+        if (seen.has(token))
+            duplicate(token);
+        seen.add(token);
+        if (token === "--json") {
+            args.json = true;
+            continue;
+        }
+        if (!["--reason", "--finding-file", "--host", "--review-only-reason"].includes(token))
+            throw new CliArgumentError("CLI_UNKNOWN_OPTION", `Unknown followup option: ${token}`, token);
+        const value = readOptionValue(argv, i++, token);
+        if (value.trim() === "" || value.includes("\0"))
+            invalidValue(token, value);
+        if (token === "--reason")
+            args.reason = value;
+        if (token === "--finding-file")
+            args.findingFile = value;
+        if (token === "--review-only-reason")
+            args.reviewOnlyReason = value;
+        if (token === "--host") {
+            if (value !== "claude" && value !== "codex")
+                invalidValue(token, value);
+            args.host = value;
+        }
+    }
+    const selectsItem = !["list", "import", "sync"].includes(action);
+    if (selectsItem !== (args.followupId !== undefined))
+        throw new CliArgumentError("CLI_MISSING_VALUE", "This action requires exactly one followup identity; list/import/sync take none.");
+    if ((args.reason !== undefined && !["accept", "defer", "reopen", "clarify"].includes(action)) ||
+        (args.findingFile !== undefined && action !== "clarify") ||
+        ((args.host !== undefined || args.reviewOnlyReason !== undefined) && action !== "process"))
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Option does not apply to this followup action.");
+    if ((["accept", "defer", "clarify"].includes(action) && args.reason === undefined) ||
+        (action === "clarify" && args.findingFile === undefined) || (action === "process" && args.host === undefined))
+        throw new CliArgumentError("CLI_MISSING_VALUE", "Accept/defer/clarify need --reason; clarify needs --finding-file; process needs --host.");
+    return args;
+}

package/dist/packages/cli/src/bin.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
-import { reviewCreatedCriteria, criteriaReviewStatus } from "./criteria-review.js";
+import { reviewCreatedCriteria, reviewRevisedCriteria, criteriaReviewStatus } from "./criteria-review.js";
 import { renderCriteriaReview } from "../../../runtime/src/review/criteria.js";
 import { advancePhaseObserver, productionRunContext } from "./run-deps.js";
 import { AgentOpsError } from "../../../runtime/src/fs/paths.js";
 import { recordRunVerification } from "../../../runtime/src/run/verification.js";
 import { runOwnedLocalProof } from "./owned-run-step.js";
 import { runRunCommand } from "./commands/run.js";
+import { runFollowupCommand } from "./commands/followup.js";
+import { reconcileRepositoryFollowups } from "./followup-deps.js";
 import { runOfficeCommand } from "./commands/office.js";
 import { ensureBackgroundOffice, observeOfficeSession, officePhaseReporter, openOfficeBrowser, serveOffice } from "./office-entry.js";
 import { readFile, readdir, stat } from "node:fs/promises";
@@ -259,6 +261,11 @@ else {
                 const root = args.scope === "user"
                     ? process.env.AGENT_OPS_HOME ?? homedir()
                     : process.cwd();
+                if (args.scope !== "user" && !["init", "update", "uninstall", "followup", "escapes", "office"].includes(args.command)) {
+                    const collected = await reconcileRepositoryFollowups(root);
+                    for (const warning of collected.warnings)
+                        process.stderr.write(`Warning: ${warning}\n`);
+                }
                 // Committed work is judged as a range by default; see defaultBase.
                 if ((args.command === "verify" || (args.command === "review" && args.action !== "show" && !args.criteriaReview)) && args.base === undefined && args.scope !== "user") {
                     const taskId = args.taskId;
@@ -279,6 +286,8 @@ else {
                     const context = await productionRunContext(root);
                     return await runRunCommand({ args, ...context, root: context.mainRoot, office: async () => await ensureBackgroundOffice(root, undefined, openOfficeBrowser) });
                 }
+                if (args.command === "followup")
+                    return await runFollowupCommand({ args, cwd: root });
                 if (args.command === "escapes")
                     return await runEscapesCommand({ root });
                 if (args.command === "office") {
@@ -511,6 +520,7 @@ else {
                         service: taskService,
                         onTaskCreated: async (record, createdRoot) => await reviewCreatedCriteria(createdRoot ?? root, record.task),
                         criteriaStatus: async (record) => await criteriaReviewStatus(root, record.task),
+                        onTaskRevised: async (record) => await reviewRevisedCriteria(root, record.task),
                         ...(policyConfigHash === undefined ? {} : { policyConfigHash }),
                         ...(sessionId === undefined ? {} : { sessionId }),
                         ...(fromMain

package/dist/packages/cli/src/cli.js

@@ -31,6 +31,7 @@ Commands:
   review     Run an independent review or show recorded reports
   run        Start or control a supervised Claude/Codex native goal
   office     Open the local pixel office (Preview; opt-in)
+  followup   Collect and process retained review findings and risk observations
   escapes    Report escaped bugs, gate catches and learned rules (read-only)
   batch      Verify and review a parent task's subtasks together
   allow-stop Grant one fingerprint-bound completion-gate Stop permit (requires --session)
@@ -77,6 +78,30 @@ Options:
  * rejected.
  */
 export const COMMAND_HELP_TEXT = {
+    followup: `Usage: agent-ops followup [list] [--json]
+       agent-ops followup <show|reopen> <followup-id> [--json]
+       agent-ops followup <import|sync> [--json]
+       agent-ops followup <accept|defer> <followup-id> --reason <text> [--json]
+       agent-ops followup clarify <followup-id> --finding-file <json> --reason <text> [--json]
+       agent-ops followup process <followup-id> --host <claude|codex> [--review-only-reason <text>] [--json]
+
+Receipt collection and history import are metadata-only: no model calls or repairs.
+State is private under the Git common directory, shared by linked worktrees.
+Text observations require a concrete nonblocking ReviewFinding JSON clarification
+(severity, blocking=false, title, details, locations, evidence, recommendation,
+criterionIds). Accept/defer require a reason; neither resolves the finding.
+Reopen retains history. Process again to revalidate a selected candidate.
+Process authorizes independent current-source assessment and a new bounded native
+repair only when conclusively PRESENT. UNKNOWN stays unresolved. Native start
+refusals retain the item and exact reason; macOS, clean main, checked-out target,
+trust, run policy and native controls still apply. Run through the trusted outer
+host as: env -u CODEX_SANDBOX_NETWORK_DISABLED agent-ops followup process ...
+ABSENT closure requires an explicit justified review-only contract and two fresh
+reviews. Reproducible bugs require corresponding behavioral red-to-green proof.
+Closure records the exact commit and finding-specific evidence; generic PASS,
+changed paths, completed run status, acceptance and deferral cannot resolve.
+Collection warnings are advisory and retryable with followup import.
+`,
     escapes: `Usage: agent-ops escapes [--json]
 
 Read-only Escape Loop report: misses per gate from the tracked
@@ -103,6 +128,7 @@ The URL carries an access token; do not share it.
        agent-ops run [start] --goal-file <path> --host <claude|codex>
        agent-ops run <status|logs|resume|stop> <run-id> [--json]
        agent-ops run resume <run-id> [--retry-approval <auth-event-id>]... [--json]
+       agent-ops run resume <run-id> --retry-delivery <task-id> [--json]
        agent-ops run respond <run-id> --question-id <id> <--answer <text>|--answer-file <path>> [--json]
 
 New runs have no total time cap. Manual resume upgrades legacy finite runs and keeps accounting.
@@ -111,6 +137,9 @@ Native goal state is observational. Completion requires current verification,
 two fresh reviews, task completion and a target-bound integration receipt.
 --retry-approval explicitly retries an intact Codex approval-review usage-limit
 failure. Original denials remain recorded; every command needs fresh approval.
+--retry-delivery requeues one stopped child blocked by interrupted handoff proof.
+Inspect and repair the harness cause first. History is retained; fresh native
+generation, verification and delivery are required. It grants no command approval.
 Status includes phase, original cause, recorded sealed proof, cleanup state,
 resumability and remediation. Resume revalidates authority and sealed artifacts;
 receipt-bound recovery executes only missing cleanup steps. Resolve the saved

package/dist/packages/cli/src/commands/advance.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { resolve } from "node:path";
 import { AgentOpsError } from "../../../../runtime/src/fs/paths.js";
 import { finishWorktree } from "../../../../runtime/src/parallel/finish.js";
+import { followupFinishText } from "./parallel.js";
 import { integrateSessionChildren } from "../../../../runtime/src/parallel/integrate.js";
 import { readWorktreeRecord, resolveCheckouts, sessionWorktreeName, worktreePath } from "../../../../runtime/src/parallel/service.js";
 import { resolveReviewScope } from "../../../../runtime/src/review/scope.js";
@@ -93,7 +94,7 @@ export async function runAdvanceCommand(options) {
     if (savedProof !== null && (await git(deps, mainRoot, ["rev-parse", `${record.targetBranch}^{commit}`]) === savedProof.head ||
         (await deps.git(mainRoot, ["merge-base", "--is-ancestor", savedProof.head, record.targetBranch])).exitCode === 0)) {
         const finished = await finishWorktree(deps, { cwd: mainRoot, name, finalProof: { ...savedProof, recovery: true } });
-        return okEnvelope("TASK_ADVANCED", { ...finished, text: "Recovered the sealed integration without moving the target again." });
+        return okEnvelope("TASK_ADVANCED", { ...finished, text: `Recovered the sealed integration without moving the target again.\n${followupFinishText(finished)}${finished.warnings.join("\n")}` });
     }
     if (savedProof !== null && await git(deps, mainRoot, ["rev-parse", `${record.targetBranch}^{commit}`]) !== savedProof.target)
         await abandonPreparedRunIntegration(commonDir, record, deps.git);
@@ -176,7 +177,7 @@ export async function runAdvanceCommand(options) {
                 reviewMode,
                 sourceFingerprint,
                 ...finished,
-                text: `Final candidate ${head} passed all task verifiers and ${reviewMode} review, then finished into ${record.targetBranch}. Receipt: ${finished.receipt}.\n${highlights}Full reports: agent-ops review show --task ${parent.task.id}`
+                text: `Final candidate ${head} passed all task verifiers and ${reviewMode} review, then finished into ${record.targetBranch}. Receipt: ${finished.receipt}.\n${followupFinishText(finished)}${finished.warnings.map(w => `Warning: ${w}\n`).join("")}${highlights}Full reports: agent-ops review show --task ${parent.task.id}`
             });
         }
         catch (failure) {

package/dist/packages/cli/src/commands/followup.js

@@ -0,0 +1,74 @@
+import { readFile, lstat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { AgentOpsError } from "../../../../runtime/src/fs/paths.js";
+import { reconcileFollowups } from "../../../../runtime/src/followup/intake.js";
+import { readFollowupProgress } from "../../../../runtime/src/followup/process.js";
+import { FileFollowupStore, clarifyFollowup, setFollowupDisposition } from "../../../../runtime/src/followup/store.js";
+import { readFollowupAssessment } from "../../../../runtime/src/review/followup.js";
+import { redactSecrets } from "../../../../runtime/src/security/redact.js";
+import { safeTaskText } from "../../../../runtime/src/task/render.js";
+import { productionFollowupContext, followupRepositoryContext } from "../followup-deps.js";
+import { errorEnvelope, okEnvelope } from "../output.js";
+/** Redact strings individually so multiline credentials cannot hide behind JSON escapes. */
+function display(value) {
+    if (typeof value === "string")
+        return safeTaskText(redactSecrets(value));
+    if (Array.isArray(value))
+        return value.map(display);
+    if (value !== null && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).map(([key, field]) => [key, display(field)]));
+    return value;
+}
+export async function runFollowupCommand(options) {
+    const { args, cwd } = options;
+    const source = await followupRepositoryContext(cwd);
+    const collection = await reconcileFollowups(source);
+    const store = new FileFollowupStore(source.commonDir);
+    const action = args.action ?? "list";
+    const warnings = collection.warnings.map(w => `Warning: ${w}`);
+    if (action === "import" || action === "sync")
+        return okEnvelope("FOLLOWUP_IMPORTED", { collection,
+            text: [`Followup: collected ${collection.candidates} candidate(s), ${collection.observations} observation(s).`, ...warnings].join("\n") });
+    if (action === "list") {
+        const items = await Promise.all((await store.read()).items.map(async (item) => {
+            const progress = await readFollowupProgress(source.commonDir, item.id, item);
+            return { id: item.id, kind: item.kind, disposition: item.disposition, status: progress.status, code: progress.code,
+                title: typeof item.original === "string" ? item.original : item.original.title };
+        }));
+        const safe = display(items);
+        return okEnvelope("FOLLOWUP_LIST", { items: safe, collection,
+            text: [safe.length === 0 ? "No followup items." : safe.map(i => `${i.id} ${i.kind} ${i.disposition} ${i.status} (${i.code})\n  ${i.title}`).join("\n"), ...warnings].join("\n") });
+    }
+    const id = args.followupId;
+    if (action === "clarify") {
+        const path = resolve(cwd, args.findingFile);
+        if (!(await lstat(path)).isFile() || (await lstat(path)).size > 128 * 1024)
+            throw new AgentOpsError("FOLLOWUP_CLARIFICATION_INVALID", "Finding JSON must be a regular file no larger than 128 KiB.");
+        let finding;
+        try {
+            finding = JSON.parse(await readFile(path, "utf8"));
+        }
+        catch {
+            throw new AgentOpsError("FOLLOWUP_CLARIFICATION_INVALID", "Finding file must contain concrete ReviewFinding JSON.");
+        }
+        await clarifyFollowup(store, id, finding, args.reason);
+    }
+    else if (action === "accept" || action === "defer" || action === "reopen") {
+        await setFollowupDisposition(store, id, action, args.reason);
+    }
+    else if (action === "process") {
+        const progress = await (await productionFollowupContext(cwd)).process(id, args.host, args.reviewOnlyReason);
+        // A persisted refusal remains an error to scripts, with the durable state available to show.
+        if (progress.attempts.at(-1)?.code === progress.code)
+            return { ...errorEnvelope(progress.code, `Repair start refused: ${progress.code}. Item retained; inspect with followup show ${id}.`),
+                data: display({ progress, collection }) };
+    }
+    const item = await store.get(id), progress = await readFollowupProgress(source.commonDir, id, item);
+    const assessment = progress.assessment === undefined ? undefined : await readFollowupAssessment(source.commonDir, progress.assessment);
+    const safe = display({ item, progress, ...(assessment === undefined ? {} : {
+            assessment: { conclusion: assessment.conclusion, reason: assessment.reason, binding: assessment.binding }
+        }) });
+    return okEnvelope("FOLLOWUP_DETAIL", { ...safe, collection,
+        text: [`${id}: ${safe.item.kind}, ${safe.item.disposition}, ${progress.status} (${progress.code})`,
+            JSON.stringify(safe, null, 2), ...warnings].join("\n") });
+}

package/dist/packages/cli/src/commands/parallel.js

@@ -38,6 +38,9 @@ function addText(result) {
         "(Claude Code: ExitWorktree with action keep before finishing; do not run task complete in the worktree)."
     ].join("\n");
 }
+export function followupFinishText(result) {
+    return result.followup === undefined ? "" : `Followup: collected ${result.followup.candidates} candidate(s), ${result.followup.observations} observation(s). Inspect with agent-ops followup list.\n`;
+}
 function finishText(result) {
     const { record } = result;
     return [
@@ -45,6 +48,7 @@ function finishText(result) {
         `Completed and recorded in git notes (refs/notes/agent-ops): ${result.taskIds.join(", ")}.`,
         `Removed ${record.path}.`,
         ...(result.receipt === undefined ? [] : [`Receipt: ${result.receipt}`]),
+        ...followupFinishText(result).trimEnd().split("\n").filter(Boolean),
         ...(result.residualRisks === undefined || result.residualRisks.length === 0 ? [] :
             ["Residual risks from review:", ...result.residualRisks.map((risk) => `- ${safeTaskText(redactSecrets(risk))}`)]),
         ...result.warnings.map((warning) => `Warning: ${warning}`)

package/dist/packages/cli/src/commands/review.js

@@ -2,7 +2,7 @@ import { buildReviewPacket } from "../../../../runtime/src/review/packet.js";
 import { runIndependentReview } from "../../../../runtime/src/review/runner.js";
 import { renderReviewResult } from "../../../../runtime/src/review/render.js";
 import { reviewReportResults } from "../../../../runtime/src/review/report.js";
-import { findPriorFailingFindings, findReviewAttestation, invalidateReviewAttestation, readReviewReportArtifact, reviewReportDigest, saveReviewAttestation, saveReviewReportArtifact } from "../../../../runtime/src/review/attestation.js";
+import { countFailedReviewRounds, findPriorFailingFindings, REVIEW_ROUND_CAP, findReviewAttestation, invalidateReviewAttestation, readReviewReportArtifact, reviewReportDigest, saveReviewAttestation, saveReviewReportArtifact } from "../../../../runtime/src/review/attestation.js";
 import { detectHostTarget, planReviewTargets, resolveReviewRole } from "../../../../runtime/src/review/roles.js";
 import { evidenceMatchesContract, taskContractHash, treeContractHash, goalHash } from "../../../../runtime/src/task/contract.js";
 import { acceptanceCoverage, coverageDigest } from "../../../../runtime/src/verify/acceptance-coverage.js";
@@ -649,6 +649,20 @@ export async function runReviewCommand(options) {
         ? await treeContext(options)
         : await taskContext(options);
     options = { ...options, noChangePaths: options.noChangePaths ?? context?.records.find(r => r.task.id === context.taskId)?.noChangePaths };
+    // Before any scope, surface or reviewer cost: a contract that keeps failing
+    // needs a new approach, not another round of one-by-one fixes.
+    if (context !== undefined && options.root !== undefined) {
+        const own = context.records.find(r => r.task.id === context.taskId).task;
+        if (await countFailedReviewRounds(options.root, context.taskId, taskContractHash(own)) >= REVIEW_ROUND_CAP) {
+            const result = { ...resultBase, status: "NOT_RUN", reason: "round-cap", taskId: context.taskId };
+            const message = "Independent review was not run.";
+            return { code: "REVIEW_NOT_RUN", status: "error", errors: [{ code: "REVIEW_NOT_RUN", message }], data: { message, result,
+                    text: renderReviewResult(result) +
+                        `Review failed ${REVIEW_ROUND_CAP} times under this contract. Stop fixing findings one by one: reconsider ` +
+                        "the approach, then record the new plan (criteria or intent) with a reason, or ask the user how to proceed:\n" +
+                        `  agent-ops task revise --task ${context.taskId} --expected-contract ${taskContractHash(own)} --reason "<what changed in the approach>"\n` } };
+        }
+    }
     const evidenceRequirements = (options.args.evidence ?? []).map((value) => {
         const separator = value.indexOf("=");
         return {

package/dist/packages/cli/src/commands/run.js

@@ -108,7 +108,7 @@ export async function runRunCommand(options) {
             return okEnvelope("RUN_LOGS", { ...stateData(action, state, `Read ${events.length} event(s) for run ${runId}.`), events });
         }
         if (action === "resume")
-            return okEnvelope("RUN_RESUMED", data(action, await options.service.resume(runId, options.args.retryApprovalIds)));
+            return okEnvelope("RUN_RESUMED", data(action, await options.service.resume(runId, options.args.retryApprovalIds, true, options.args.retryDeliveryTaskId)));
         if (action === "stop")
             return okEnvelope("RUN_STOP_REQUESTED", data(action, await options.service.stop(runId, options.args.answer ?? "user requested stop")));
         const questionId = options.args.questionId;

package/dist/packages/cli/src/commands/task.js

@@ -6,7 +6,12 @@ import { renderTaskMarkdown, safeTaskText } from "../../../../runtime/src/task/r
 import { errorEnvelope, okEnvelope } from "../output.js";
 async function withCriteriaStatus(envelope, options) {
     const item = envelope.data?.record;
-    const advice = item === undefined ? null : await options.criteriaStatus?.(item).catch(() => null);
+    // A status read is best effort; a cancelled advisory round must still stop the caller.
+    const advice = item === undefined ? null : await options.criteriaStatus?.(item).catch((error) => {
+        if (error instanceof AgentOpsError && error.code === "CRITERIA_REVIEW_CANCELLED")
+            throw error;
+        return null;
+    });
     return advice == null || envelope.data === null ? envelope : { ...envelope, data: { ...envelope.data, criteriaReview: advice,
             text: envelope.data.text + "\n\n" + renderCriteriaReview(advice) } };
 }
@@ -202,7 +207,8 @@ export async function runTaskCommand(options) {
                 ...(origin === undefined ? {} : { origin }),
                 reason: options.args.reason, ...(options.args.baseline === undefined ? {} : { baseline: options.args.baseline })
             });
-            return await withCriteriaStatus(await withEscape(taskEnvelope(action, "TASK_REVISED", "Contract revised; obtain a fresh review, and new verification if the criteria or configuration changed.", record), origin === undefined ? undefined : await options.service.declareEscape(record.task.id), options.service), options);
+            // The revision is saved first: an advisory NOT_RUN keeps TASK_REVISED, and a cancelled round throws with it kept.
+            return await withCriteriaStatus(await withEscape(taskEnvelope(action, "TASK_REVISED", "Contract revised; obtain a fresh review, and new verification if the criteria or configuration changed.", record), origin === undefined ? undefined : await options.service.declareEscape(record.task.id), options.service), options.onTaskRevised === undefined ? options : { ...options, criteriaStatus: options.onTaskRevised });
         }
         if (action === "replan") {
             const payload = await jsonFile(options.args.planFile);

package/dist/packages/cli/src/context.js

@@ -236,22 +236,26 @@ export async function runPolicyContext(root, renew = false) {
         return null;
     const here = realpathSync(root);
     const worker = saved.workers.find(w => w.worktree === here);
-    const proofProcess = worker?.proofProcess ?? saved.proofProcess;
-    let proof = false;
-    if (proofProcess != null && String(proofProcess.processId) === process.env.AGENT_OPS_RUN_PROOF_PID) {
+    const matchesProof = (registered) => {
+        if (registered == null || String(registered.processId) !== process.env.AGENT_OPS_RUN_PROOF_PID)
+            return false;
         try {
-            proof = execFileSync("ps", ["-o", "pgid=", "-p", String(process.pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], windowsHide: true }).trim() === String(proofProcess.processId) &&
-                execFileSync("ps", ["-o", "lstart=", "-p", String(proofProcess.processId)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], windowsHide: true }).trim() === proofProcess.processIdentity;
+            return execFileSync("ps", ["-o", "pgid=", "-p", String(process.pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], windowsHide: true }).trim() === String(registered.processId) &&
+                execFileSync("ps", ["-o", "lstart=", "-p", String(registered.processId)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], windowsHide: true }).trim() === registered.processIdentity;
         }
         catch {
-            proof = false;
+            return false;
         }
-    }
+    };
+    const globalProof = matchesProof(saved.proofProcess);
+    const proof = globalProof || matchesProof(worker?.proofProcess);
+    // Reading another registered checkout does not change a run-level proof's coordinator actor.
+    const actor = globalProof || worker === undefined ? saved.workers.find(w => w.workerId === saved.coordinatorId) : worker;
     if ((!proof && (worker === undefined || record?.runId !== runId || record.workerId !== worker.workerId ||
         record.ownerSessionId !== worker.ownerSessionId || record.coordinatorId !== saved.coordinatorId || record.workerGeneration !== worker.generation)) ||
         (worker === undefined && !(proof && saved.root === here)) ||
-        (process.env.AGENT_OPS_WORKER_ID !== undefined && (process.env.AGENT_OPS_WORKER_ID !== (worker?.workerId ?? saved.coordinatorId) ||
-            process.env.AGENT_OPS_WORKER_GENERATION !== String((worker ?? saved.workers.find(w => w.workerId === saved.coordinatorId))?.generation))))
+        ((globalProof || process.env.AGENT_OPS_WORKER_ID !== undefined) && (actor === undefined ||
+            process.env.AGENT_OPS_WORKER_ID !== actor.workerId || process.env.AGENT_OPS_WORKER_GENERATION !== String(actor.generation))))
         throw new AgentOpsError("RUN_WORKER_STALE", "Run policy requires the current registered worker generation or proof process.");
     if (saved.status !== "active" || saved.disableRestart || saved.awaitingResume)
         throw new AgentOpsError("RUN_POLICY_DISABLED", "Run execution policy is inactive; explicit resume is required.");

package/dist/packages/cli/src/criteria-review.js

@@ -1,7 +1,7 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { AgentOpsError } from "../../../runtime/src/fs/paths.js";
-import { runCriteriaReview, readCriteriaReview, renderCriteriaReview } from "../../../runtime/src/review/criteria.js";
+import { runCriteriaReview, readCriteriaReview, renderCriteriaReview, revisionReviewDue } from "../../../runtime/src/review/criteria.js";
 import { registeredRunProofRunner } from "../../../runtime/src/verify/spawn.js";
 import { appendLocalLog } from "../../../runtime/src/logging/local-log.js";
 import { localStatePaths } from "../../../runtime/src/security/permissions.js";
@@ -24,7 +24,7 @@ export async function criteriaReviewStatus(root, task) {
     return await readCriteriaReview(root, task, await parentScope(root, task).catch(() => undefined));
 }
 /** Only production creation/explicit review installs this hook; TaskService stays model-free. */
-export async function reviewCreatedCriteria(root, task, rerun = false) {
+export async function reviewCreatedCriteria(root, task, rerun = false, trigger) {
     const controller = new AbortController();
     const interrupt = (signal) => { controller.abort(signal); };
     const int = () => interrupt("SIGINT"), term = () => interrupt("SIGTERM");
@@ -38,7 +38,7 @@ export async function reviewCreatedCriteria(root, task, rerun = false) {
         const parent = await parentScope(root, task).catch(() => undefined);
         process.stderr.write(`Criteria advisory for ${task.id}: waiting for one independent reviewer (no time budget; Ctrl-C cancels).\n`);
         let result = await runCriteriaReview({ root, task, parent, target, model: role?.model, effort: role?.effort,
-            rerun, signal: controller.signal, runner: registeredRunProofRunner(),
+            rerun, ...(trigger === undefined ? {} : { trigger }), signal: controller.signal, runner: registeredRunProofRunner(),
             unavailableCode: config === undefined ? "CRITERIA_REVIEW_CONFIG_UNAVAILABLE" : target === undefined && role !== undefined ? "CRITERIA_REVIEW_NO_INDEPENDENT_TARGET" : "CRITERIA_REVIEW_UNCONFIGURED",
             log: async (report, path) => {
                 const state = localStatePaths(process.env.AGENT_OPS_HOME ?? homedir());
@@ -61,3 +61,8 @@ export async function reviewCreatedCriteria(root, task, rerun = false) {
         process.removeListener("SIGTERM", term);
     }
 }
+/** A revise that changed what the advice judged reruns it once; otherwise it reports the current advisory. */
+export async function reviewRevisedCriteria(root, task) {
+    const view = await criteriaReviewStatus(root, task);
+    return revisionReviewDue(view) ? await reviewCreatedCriteria(root, task, true, "revise") : view;
+}

package/dist/packages/cli/src/followup-deps.js

@@ -0,0 +1,56 @@
+import { AgentOpsError } from "../../../runtime/src/fs/paths.js";
+import { processFollowup, reconcileFollowupRepairs } from "../../../runtime/src/followup/process.js";
+import { isFollowupAssessmentCurrent } from "../../../runtime/src/review/followup.js";
+import { resolveReviewRole } from "../../../runtime/src/review/roles.js";
+import { worktreeDependencies, gitRunner } from "./parallel-deps.js";
+import { productionRunContext } from "./run-deps.js";
+import { resolveCheckouts } from "../../../runtime/src/parallel/service.js";
+import { reconcileFollowups } from "../../../runtime/src/followup/intake.js";
+export async function followupRepositoryContext(cwd) {
+    const deps = worktreeDependencies(), checkouts = await resolveCheckouts(deps, cwd);
+    return { git: deps.git, mainRoot: checkouts.mainRoot, commonDir: checkouts.commonDir,
+        config: await deps.loadConfig(checkouts.mainRoot), loadConfig: async () => await deps.loadConfig(checkouts.mainRoot) };
+}
+/** Ordinary CLI reconciliation is advisory and never launches a provider or repair. */
+export async function reconcileRepositoryFollowups(cwd) {
+    try {
+        return await reconcileFollowups(await followupRepositoryContext(cwd));
+    }
+    catch (error) {
+        const code = error instanceof AgentOpsError && /^[A-Z0-9_]{1,80}$/u.test(error.code) ? error.code : "FOLLOWUP_COLLECTION_FAILED";
+        return { added: 0, candidates: 0, observations: 0,
+            warnings: code === "WORKTREE_NOT_GIT" ? [] : [`followup: ${code}; retry with followup import.`] };
+    }
+}
+/** Uses the ordinary production authority, including its exact native/platform/trust refusals. */
+export async function productionFollowupContext(cwd) {
+    const deps = worktreeDependencies(), checkouts = await resolveCheckouts(deps, cwd);
+    const branch = await deps.git(checkouts.currentRoot, ["symbolic-ref", "--short", "HEAD"]);
+    if (branch.exitCode !== 0)
+        throw new AgentOpsError("RUN_TARGET_REQUIRED", "Followup processing requires a checked-out target branch.");
+    const loadConfig = async () => await deps.loadConfig(checkouts.currentRoot);
+    const assessmentOptions = async (itemId, reviewOnlyReason) => {
+        const config = await loadConfig(), role = resolveReviewRole("independent-review", config.reviewRoles ?? []);
+        return {
+            root: checkouts.currentRoot, commonDir: checkouts.commonDir, itemId, targetBranch: branch.stdout.trim(),
+            gitRunner: gitRunner(checkouts.currentRoot), loadConfig,
+            review: { targets: role?.targets ?? [], ...(role?.timeoutMs === undefined ? {} : { timeoutMs: role.timeoutMs }) },
+            ...(reviewOnlyReason === undefined ? {} : { reviewOnlyReason })
+        };
+    };
+    return { ...checkouts,
+        assessmentOptions,
+        process: async (itemId, host, reviewOnlyReason) => {
+            const options = await assessmentOptions(itemId, reviewOnlyReason);
+            return await processFollowup({ ...options, host, start: async (input, proof) => {
+                    const run = await productionRunContext(cwd, { beforeStart: async () => {
+                            if (!await isFollowupAssessmentCurrent(options, proof))
+                                throw new AgentOpsError("FOLLOWUP_SOURCE_CHANGED", "The finding, target, source or config changed before repair startup.");
+                        } });
+                    return (await run.service.start({ ...input, root: run.mainRoot, commonDir: run.commonDir,
+                        targetBranch: run.targetBranch, ownerSessionId: run.ownerSessionId })).state;
+                } });
+        },
+        reconcile: async () => await reconcileFollowupRepairs({ git: deps.git, mainRoot: checkouts.mainRoot,
+            commonDir: checkouts.commonDir, config: await loadConfig(), loadConfig }) };
+}

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

@@ -7,9 +7,9 @@ import { fileURLToPath } from "node:url";
 import { setTimeout as delay } from "node:timers/promises";
 import { AgentOpsError } from "../../../runtime/src/fs/paths.js";
 import { sha256 } from "../../../runtime/src/fs/hash.js";
-import { resolveCheckouts, sessionWorktreeName } from "../../../runtime/src/parallel/service.js";
+import { resolveCheckouts, readWorktreeRecord, sessionWorktreeName } from "../../../runtime/src/parallel/service.js";
 import { createLaunchdDescriptor, LaunchdController, readBootIdentity, readGuiLoginIdentity } from "../../../runtime/src/run/macOS.js";
-import { FileRunRepository, RunService } from "../../../runtime/src/run/service.js";
+import { FileRunRepository, RunService, validateDeliveryRetry } from "../../../runtime/src/run/service.js";
 import { readPrivateFile, writePrivateFile } from "../../../runtime/src/security/permissions.js";
 import { collectChangeSurface } from "../../../runtime/src/verify/change-surface.js";
 import { worktreeDependencies, gitRunner, trustStore } from "./parallel-deps.js";
@@ -182,8 +182,10 @@ export async function productionRunContext(cwd, options = {}) {
         if (await deps.trust.status(checkouts.mainRoot, config) !== "TRUSTED")
             throw new AgentOpsError("RUN_REPO_UNTRUSTED", "The run requires current repository verifier trust.");
         const ownerSessionId = randomUUID();
+        const bootIdentity = await readBootIdentity(), loginDomain = await readGuiLoginIdentity();
+        await options.beforeStart?.();
         const result = await service.start({ ...input, root: checkouts.mainRoot, commonDir: checkouts.commonDir,
-            targetBranch: target.stdout.trim(), ownerSessionId, bootIdentity: await readBootIdentity(), loginDomain: await readGuiLoginIdentity() });
+            targetBranch: target.stdout.trim(), ownerSessionId, bootIdentity, loginDomain });
         try {
             await bindRunPolicy(repository, result.state.runId, { config,
                 baseTrustBinding: await repositoryTrustBinding(checkouts.mainRoot, config, CLI_VERSION), runtimeHash: await runRuntimeHash() });
@@ -209,8 +211,9 @@ export async function productionRunContext(cwd, options = {}) {
             throw cause;
         }
     };
-    const resume = async (runId, retryApprovalIds = [], upgradeBudget = true) => {
+    const resume = async (runId, retryApprovalIds = [], upgradeBudget = true, retryDeliveryTaskId) => {
         const before = await service.status(runId);
+        const retry = retryDeliveryTaskId === undefined ? null : validateDeliveryRetry(before, retryDeliveryTaskId);
         const runtimeHash = await runRuntimeHash();
         const policy = await readRunPolicy(before, before.policyBinding?.runtimeHash ?? runtimeHash, Date.now(), true);
         if (policy !== null && await deps.trust.status(checkouts.mainRoot, policy.baseConfig) !== "TRUSTED")
@@ -236,7 +239,15 @@ export async function productionRunContext(cwd, options = {}) {
                 if (exists === null || (await collectChangeSurface(gitRunner(worker.worktree))).paths.length > 0)
                     throw new AgentOpsError("RUN_RECOVERY_DIRTY", "Commit or preserve every writer checkout before explicit resume.");
             }
-        const result = await service.resume(runId, retryApprovalIds, upgradeBudget);
+        if (retry !== null) {
+            const record = retry.worktree === null ? null : await readWorktreeRecord(retry.worktree);
+            const head = retry.worktree === null ? null : await deps.git(retry.worktree, ["rev-parse", "HEAD"]);
+            if (record === null || record.runId !== runId || record.workerId !== retry.workerId ||
+                record.ownerSessionId !== retry.ownerSessionId || record.workerGeneration !== retry.generation ||
+                head?.exitCode !== 0 || head.stdout.trim() !== retry.stopIntent.sourceCommit)
+                throw new AgentOpsError("RUN_DELIVERY_RETRY_INVALID", "Interrupted checkout ownership or source changed; preserve it and reconcile before retrying.");
+        }
+        const result = await service.resume(runId, retryApprovalIds, upgradeBudget, retryDeliveryTaskId, retry?.lastFailure?.id);
         try {
             if (pending !== null)
                 await renewPendingRunPolicy(repository, runId, pending);