@kylecheng3146/agent-ops 0.11.1 → 0.11.3

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

@@ -322,10 +322,32 @@ const RECOVERABLE = new Set(["RUN_RECOVERY_DIRTY", "RUN_NATIVE_VERSION_CHANGED",
 function resumeBlocker(current, acknowledged = new Set()) {
     return [...current.events].reverse().find(e => !acknowledged.has(e.id) && (RECOVERABLE.has(e.code) || ["RUN_NO_PROGRESS_REPEAT", "RUN_COMMAND_DENIED"].includes(e.code)));
 }
-function cannotResume(current, acknowledged = new Set()) {
+function cannotResume(current, acknowledged = new Set(), retryingDelivery = false) {
     return current.status === "complete" || current.events.some(e => e.code === "RUN_COMMAND_DENIED" && !acknowledged.has(e.id)) ||
         (current.integration?.proofDigest === undefined && (current.workers.some(w => w.workerId === current.coordinatorId && w.status === "blocked" && w.lastFailure !== null && w.lastFailure.failureClass !== "native-start") ||
-            (current.status === "blocked" && !RECOVERABLE.has(resumeBlocker(current, acknowledged)?.code ?? ""))));
+            (current.status === "blocked" && !RECOVERABLE.has(resumeBlocker(current, acknowledged)?.code ?? "") &&
+                !(retryingDelivery && resumeBlocker(current, acknowledged) === undefined))));
+}
+/** A manual retry grants a fresh attempt, never proof or command authorization. */
+export function validateDeliveryRetry(state, taskId, now = Date.now()) {
+    const task = state.tasks.find(t => t.taskId === taskId);
+    const worker = state.workers.find(w => w.workerId === task?.workerId && w.taskId === taskId);
+    const intent = worker?.stopIntent;
+    const dead = (w) => !["assigned", "starting", "running", "idle", "handing-off"].includes(w.status) &&
+        (w.nativeSessionId === null && w.processId === null || w.stopIntent?.runId === state.runId &&
+            w.stopIntent.workerId === w.workerId && w.stopIntent.generation === w.generation &&
+            w.stopIntent.nativeSessionId === w.nativeSessionId && w.stopIntent.confirmedDeadAt !== null &&
+            Number.isFinite(Date.parse(w.stopIntent.confirmedDeadAt)) && Date.parse(w.stopIntent.confirmedDeadAt) <= now);
+    if (["complete", "failed", "stopping"].includes(state.status) || state.integration !== null || state.proofProcess != null ||
+        task === undefined || task.taskId === state.rootTaskId || task.status !== "blocked" || task.blockedReason !== "RUN_FINAL_PROOF_INTERRUPTED" ||
+        task.deliveryDigest !== null || task.sourceCommit !== null || worker === undefined || worker.workerId === state.coordinatorId ||
+        worker.status !== "blocked" || worker.lastFailure?.failureClass !== "RUN_FINAL_PROOF_INTERRUPTED" ||
+        worker.lastFailure.checkId !== "RUN_FINAL_PROOF_INTERRUPTED" || worker.lastFailure.pinId !== null ||
+        intent?.reason !== "handoff" || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u.test(intent.sourceCommit ?? "") ||
+        !/^[a-f0-9]{64}$/u.test(intent.contractDigest ?? "") || !/^[a-f0-9]{64}$/u.test(intent.deliveryDigest ?? "") ||
+        state.workers.some(w => w.proofProcess != null || !dead(w)))
+        throw new AgentOpsError("RUN_DELIVERY_RETRY_INVALID", "Retry requires an interrupted child handoff, unchanged identity and confirmed stopped writers/proof; inspect run status first.");
+    return worker;
 }
 /** Observations are not proof validation; resume still reconciles every authority and sealed artifact. */
 export function describeRunRecovery(state, now = Date.now()) {
@@ -418,12 +440,21 @@ export class RunService {
         }));
         return { state, message: `Run ${runId} is paused.` };
     }
-    async resume(runId, retryApprovalIds = [], upgradeBudget = true) {
+    async resume(runId, retryApprovalIds = [], upgradeBudget = true, retryDeliveryTaskId, expectedFailureId) {
         const state = await this.#repository.mutate(runId, async (current) => {
-            const acknowledged = await approvalRetryEvents(current, retryApprovalIds);
+            if (retryDeliveryTaskId !== undefined && retryApprovalIds.length > 0)
+                throw new AgentOpsError("RUN_DELIVERY_RETRY_INVALID", "Delivery and approval retries require separate explicit controls.");
+            const retry = retryDeliveryTaskId === undefined ? null : validateDeliveryRetry(current, retryDeliveryTaskId, Date.parse(this.#now()));
+            if (retry !== null && expectedFailureId !== undefined && retry.lastFailure.id !== expectedFailureId)
+                throw new AgentOpsError("RUN_DELIVERY_RETRY_INVALID", "The interrupted attempt changed during recovery.");
+            const acknowledged = new Set(await approvalRetryEvents(current, retryApprovalIds));
+            if (retry !== null)
+                for (const e of current.events)
+                    if (e.code === "RUN_NO_PROGRESS_REPEAT" && e.workerId === retry.workerId && e.taskId === retry.taskId)
+                        acknowledged.add(e.id);
             const recoverable = RECOVERABLE;
             const blocker = resumeBlocker(current, acknowledged);
-            if (cannotResume(current, acknowledged)) {
+            if (cannotResume(current, acknowledged, retry !== null)) {
                 throw new AgentOpsError("RUN_NOT_RESUMABLE", `Run ${runId} is ${current.status}.`);
             }
             if (current.integration?.proofDigest === undefined && !upgradeBudget && budgetExpired(current, Date.parse(this.#now())))
@@ -439,11 +470,17 @@ export class RunService {
                 ...(recover ? { workers: current.workers.map(w => w.status === "blocked" && (w.lastFailure === null || w.lastFailure.failureClass === "native-start") &&
                         !current.tasks.some(t => t.taskId === w.taskId && t.status === "blocked" && !recoverable.has(t.blockedReason ?? "")) ? { ...w, status: "stopped" } : w),
                     tasks: current.tasks.map(t => t.status === "blocked" && recoverable.has(t.blockedReason ?? "") ? { ...t, status: "ready", blockedReason: null } : t) } : {}),
+                ...(retry === null ? {} : {
+                    workers: current.workers.map(w => w.workerId === retry.workerId ? { ...w, status: "stopped", lastFailure: null } : w),
+                    tasks: current.tasks.map(t => t.taskId === retry.taskId ? { ...t, status: "ready", blockedReason: null } : t)
+                }),
                 status: "active",
                 awaitingResume: false,
                 disableRestart: false,
                 controls: [...current.controls, {
-                        action: "resume", actor: "user", reason: retryApprovalIds.length === 0 ? null : "retry-approval:" + JSON.stringify(retryApprovalIds), requestedAt: this.#now(), expiresAt: null, appliedAt: null
+                        action: "resume", actor: "user", reason: retry !== null ? "retry-delivery:" + JSON.stringify({ taskId: retry.taskId,
+                            workerId: retry.workerId, generation: retry.generation, failure: retry.lastFailure }) :
+                            retryApprovalIds.length === 0 ? null : "retry-approval:" + JSON.stringify(retryApprovalIds), requestedAt: this.#now(), expiresAt: null, appliedAt: null
                     }]
             };
         });
@@ -461,9 +498,25 @@ export class RunService {
             if (question.answeredAt !== null)
                 throw new AgentOpsError("RUN_QUESTION_ANSWERED", `Question already answered: ${cleanQuestion}`);
             const answeredAt = this.#now();
+            const coordinator = current.workers.find(worker => worker.workerId === current.coordinatorId);
+            const intent = coordinator?.stopIntent;
+            const wake = coordinator?.status === "stopped" && coordinator.taskId === current.rootTaskId &&
+                coordinator.nativeSessionId === null && coordinator.nativeJobId === null && coordinator.nativeGoalState === "inactive" &&
+                coordinator.proofProcess == null && intent?.reason === "handoff" && intent.runId === runId &&
+                intent.workerId === coordinator.workerId && intent.generation === coordinator.generation &&
+                intent.confirmedDeadAt !== null && Number.isFinite(Date.parse(intent.confirmedDeadAt)) &&
+                Date.parse(intent.confirmedDeadAt) <= Date.parse(answeredAt);
             return {
                 ...current,
                 status: "active",
+                // Consume this wait once; ordinary resume still requires death reconciliation and a fresh lease.
+                ...(wake ? {
+                    workers: current.workers.map(worker => worker.workerId === current.coordinatorId
+                        ? { ...worker, stopIntent: { ...intent, reason: "stop" } } : worker),
+                    events: [...current.events, event({ type: "diagnostic", code: "RUN_COORDINATOR_RESPONSE_WAKE",
+                            workerId: coordinator.workerId, taskId: coordinator.taskId,
+                            detail: `Answer ${cleanQuestion} released coordinator wait at generation ${coordinator.generation}; normal recovery is required.` }, answeredAt)].slice(-MAX_EVENTS)
+                } : {}),
                 questions: current.questions.map((item) => item.questionId === cleanQuestion
                     ? { ...item, answeredAt, answerDigest: sha256(cleanAnswer) }
                     : item),

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

@@ -66,7 +66,9 @@ export async function recordNativeRunUsage(repository, event) {
     }
     else if (event.host === "codex" && plain(payload.tokenUsage) && plain(payload.tokenUsage.total)) {
         const usage = payload.tokenUsage.total;
-        incoming = { source: "codex", epoch: `${worker.workerId}:${worker.nativeSessionId}:thread`, inputTokens: count(usage.inputTokens),
+        const threadKey = worker.nativeJobId !== null && worker.nativeJobId !== worker.nativeSessionId
+            ? `${worker.nativeSessionId}:${worker.nativeJobId}` : worker.nativeSessionId;
+        incoming = { source: "codex", epoch: `${worker.workerId}:${threadKey}:thread`, inputTokens: count(usage.inputTokens),
             outputTokens: count(usage.outputTokens), totalTokens: count(usage.totalTokens), costUsd: null,
             completeness: "partial", observedAt: event.at };
     }
@@ -74,7 +76,8 @@ export async function recordNativeRunUsage(repository, event) {
         return;
     await repository.mutate(event.runId, current => {
         const saved = current.workers.find(w => w.workerId === event.workerId);
-        if (saved?.generation !== event.generation || saved.nativeSessionId !== worker.nativeSessionId)
+        if (saved?.generation !== event.generation || saved.nativeSessionId !== worker.nativeSessionId ||
+            saved.nativeJobId !== worker.nativeJobId)
             return current;
         return appendUsage(current, incoming);
     });

package/dist/runtime/src/security/permissions.js

@@ -607,7 +607,22 @@ export async function writePrivateFile(path, content, anchorDirectory) {
         await handle.close();
         handle = undefined;
         await chmod(temporaryPath, 0o600);
-        await rename(temporaryPath, path);
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                await rename(temporaryPath, path);
+                break;
+            }
+            catch (error) {
+                // Windows readers can temporarily deny replacement of an existing file.
+                if (process.platform !== "win32" || attempt >= 4 ||
+                    typeof error !== "object" || error === null || !("code" in error) ||
+                    !["EPERM", "EACCES", "EBUSY"].includes(String(error.code))) {
+                    throw error;
+                }
+                await delay(50 * (attempt + 1));
+                await inspectPath(path, anchorDirectory, "file");
+            }
+        }
         await chmod(path, 0o600);
         await syncDirectory(parent);
     }

package/dist/runtime/src/verify/acceptance-coverage.js

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { sha256 } from "../fs/hash.js";
 import { criterionContractHash, evidenceMatchesContract } from "../task/contract.js";
 /** Only current, paired check evidence discharges a mechanical contract. */
-export async function acceptanceCoverage(record, config, sourceFingerprint, store) {
+export async function acceptanceCoverage(record, config, sourceFingerprint, store, readExecution = path => readPrivateFile(join(store.root, ...path.split("/")), store.root)) {
     const configHash = calculateConfigHash(config);
     const rows = [];
     for (const criterion of record.task.criteria) {
@@ -26,7 +26,7 @@ export async function acceptanceCoverage(record, config, sourceFingerprint, stor
         for (const item of matching) {
             const proof = item.evidence.acceptance;
             try {
-                const source = await readPrivateFile(join(store.root, ...proof.executionArtifact.split("/")), store.root);
+                const source = await readExecution(proof.executionArtifact);
                 if (source === null || proof.executionArtifact !== ".agent-ops/tasks/acceptance/" + sha256(source) + ".json")
                     continue;
                 const artifact = JSON.parse(source);

package/dist/runtime/src/verify/service.js

@@ -5,7 +5,7 @@ import { validateTaskAgainstConfig } from "../schema/validate.js";
 import { collectChangeSurface } from "./change-surface.js";
 import { resolveReviewScope, reviewScopeSignature } from "../review/scope.js";
 import { calculateSourceFingerprint } from "./source-fingerprint.js";
-import { buildVerificationEvidence } from "./evidence.js";
+import { buildVerificationEvidence, calculateConfigHash, isPassingVerificationEvidence } from "./evidence.js";
 import { createFailureFingerprint } from "./fingerprint.js";
 import { aggregateVerificationStatus, executeConfiguredCommand } from "./command-executor.js";
 import { selectVerificationScope } from "./scope.js";
@@ -70,6 +70,64 @@ export class VerificationService {
         }
         return references;
     }
+    async #sharedTreeCommandReport(task, command, sourceFingerprint) {
+        if (!this.#options.trusted)
+            return null;
+        const active = (await this.#options.taskService.list()).filter((record) => record.status === "active" && record.supersededBy === undefined);
+        const byId = new Map(active.map((record) => [record.task.id, record]));
+        const rootOf = (id) => {
+            let current = id;
+            const seen = new Set();
+            while (!seen.has(current)) {
+                seen.add(current);
+                const parentId = byId.get(current)?.task.parentTaskId;
+                if (parentId === undefined || !byId.has(parentId))
+                    return current;
+                current = parentId;
+            }
+            return current;
+        };
+        const rootId = rootOf(task.id);
+        const peers = active.filter((record) => record.task.id !== task.id &&
+            rootOf(record.task.id) === rootId);
+        if (peers.length === 0)
+            return null;
+        const configHash = calculateConfigHash(this.#options.config);
+        for (const peer of peers) {
+            for (const reference of new Set(Object.values(peer.evidence).flat())) {
+                let loaded;
+                try {
+                    loaded = await this.#options.evidenceStore.load(reference);
+                }
+                catch {
+                    continue;
+                }
+                if (loaded === null || typeof loaded !== "object")
+                    continue;
+                const evidence = loaded;
+                if (evidence.commandId === command.id &&
+                    evidence.sourceFingerprint === sourceFingerprint &&
+                    evidence.configHash === configHash &&
+                    evidence.scope === this.#options.scope &&
+                    isPassingVerificationEvidence(command, evidence)) {
+                    return {
+                        commandId: command.id,
+                        required: command.required,
+                        status: "PASS",
+                        failureClass: "none",
+                        exitCode: evidence.exitCode,
+                        timedOut: false,
+                        testCount: evidence.testCount,
+                        diagnostic: "",
+                        evidenceReferences: [],
+                        startedAt: evidence.startedAt,
+                        finishedAt: evidence.finishedAt
+                    };
+                }
+            }
+        }
+        return null;
+    }
     async #runCommand(task, command) {
         const startedAt = (this.#options.now ?? (() => new Date().toISOString()))();
         const result = await executeConfiguredCommand(command, {
@@ -144,7 +202,9 @@ export class VerificationService {
         };
         const results = [];
         for (const commandId of selection.verifierIds) {
-            results.push(await this.#runCommand(validation.value, commandById(this.#options.config, commandId)));
+            const command = commandById(this.#options.config, commandId);
+            const shared = await this.#sharedTreeCommandReport(validation.value, command, sourceFingerprint);
+            results.push(shared ?? (await this.#runCommand(validation.value, command)));
         }
         const acceptance = validation.value.criteria.some(c => c.acceptance !== undefined && c.acceptance.mode !== "review-only")
             ? await replayAcceptance({ ...this.#options, task: validation.value, sourceFingerprint }) : [];

package/dist/runtime/src/verify/spawn.js

@@ -1,6 +1,6 @@
 import { execFile as execFileCallback, spawn } from "node:child_process";
 import { promisify } from "node:util";
-const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
 const DEFAULT_OUTPUT_LIMIT_BYTES = 64 * 1024;
 const MAX_OUTPUT_LIMIT_BYTES = 1024 * 1024;
 const DEFAULT_TERMINATION_GRACE_MS = 500;
@@ -137,6 +137,64 @@ async function terminatePosixTree(processId, completion, graceMs) {
         }
     }
 }
+async function collectPosixSubtree(seen, excluded) {
+    try {
+        const { stdout } = await execFile("ps", ["-axo", "pid=,ppid="], {
+            encoding: "utf8"
+        });
+        const rows = stdout
+            .trim()
+            .split("\n")
+            .map((line) => {
+            const [pid, ppid] = line.trim().split(/\s+/u).map(Number);
+            return { pid, ppid };
+        })
+            .filter((row) => Number.isSafeInteger(row.pid) &&
+            row.pid > 0 &&
+            Number.isSafeInteger(row.ppid) &&
+            row.ppid >= 0);
+        for (let added = true; added;) {
+            added = false;
+            for (const { pid, ppid } of rows) {
+                if (!excluded.has(pid) && !seen.has(pid) && seen.has(ppid)) {
+                    seen.add(pid);
+                    added = true;
+                }
+            }
+        }
+        const alive = new Set(rows.map((row) => row.pid));
+        const root = [...seen][0];
+        return [...seen].filter((pid) => !excluded.has(pid) && (pid === root || alive.has(pid)));
+    }
+    catch {
+        return [...seen].filter((pid) => !excluded.has(pid));
+    }
+}
+async function terminatePosixSubtree(processId, processGroupId, completion, graceMs) {
+    const excluded = new Set([process.pid, processGroupId]);
+    const seen = new Set([processId]);
+    for (const pid of (await collectPosixSubtree(seen, excluded)).reverse()) {
+        try {
+            process.kill(pid, "SIGTERM");
+        }
+        catch (error) {
+            if (errorCode(error) !== "ESRCH") {
+                throw error;
+            }
+        }
+    }
+    await waitForCompletion(completion, graceMs);
+    for (const pid of (await collectPosixSubtree(seen, excluded)).reverse()) {
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch (error) {
+            if (errorCode(error) !== "ESRCH") {
+                throw error;
+            }
+        }
+    }
+}
 async function defaultTerminateWindowsTree(processId, graceMs) {
     await execFile("taskkill", ["/pid", String(processId), "/T", "/F"], {
         encoding: "utf8",
@@ -208,7 +266,11 @@ export class NodeVerificationProcessRunner {
                     await this.#terminateWindowsTree(processId, graceMs);
                     return;
                 }
-                await terminatePosixTree(this.#processGroupId ?? processId, completion, graceMs);
+                if (this.#processGroupId !== undefined) {
+                    await terminatePosixSubtree(processId, this.#processGroupId, completion, graceMs);
+                    return;
+                }
+                await terminatePosixTree(processId, completion, graceMs);
             }
         };
     }

package/docs/en/guides/configuration.md

@@ -263,6 +263,11 @@ evidence. Give each editing conversation its own worktree instead:
   are never pre-authorized. Turning auto mode off, or `uninstall`, takes
   exactly those entries back out; a rules file of that name agent-ops did not
   write is left alone.
+- The opt-in `run` profile additionally authorizes `agent-ops run` and the
+  selected `agent-ops followup process` action on Claude and Codex. Normal
+  init/update plans disclose the exact entries; dropping the profile removes
+  them. Followup metadata actions grant no native execution authority. Processing
+  still enforces current repository trust and all ordinary native start controls.
 - `review` and `doctor` take `--output <file>`: the JSON envelope is written
   there (mode 0600) and one summary line is printed. Use it instead of a shell
   redirect, which Codex wraps in `zsh -lc` and can only allow by matching the

package/docs/en/guides/task-debug.md

@@ -39,3 +39,39 @@ gone. `task debug` now fails with `TASK_DEBUG_REMOVED`.
 Older state still loads: tasks keep their `debug` tag, stored budget and
 hypothesis state is ignored, `originRequired` no longer blocks finish, and a
 config's `features.debug` is accepted and dropped by the next `update`.
+
+## Retained review followups
+
+After finish, inspect `agent-ops followup list` and `followup show <followup-id>`
+(add `--json` for agents). `followup import` / `followup sync` retries metadata-only local
+history collection without models or repairs. Ledger state is private in the
+Git common directory and shared by linked worktrees. Collection warnings leave
+original completion intact; retry after fixing the reported source/state problem.
+
+A free-text observation needs explicit clarification first:
+
+```sh
+agent-ops followup clarify <followup-id> --finding-file finding.json --reason 'Concrete claim and supporting source'
+agent-ops followup defer <followup-id> --reason 'Revisit after the dependency upgrade'
+agent-ops followup accept <followup-id> --reason 'Accepted tradeoff for this release'
+agent-ops followup reopen <followup-id>
+env -u CODEX_SANDBOX_NETWORK_DISABLED agent-ops followup process <followup-id> --host codex
+```
+
+`finding.json` is an ordinary nonblocking ReviewFinding: severity, blocking=false,
+title, details, locations (`path`, `line`), evidence, recommendation and criterionIds.
+Accept/defer require reasons and never mean resolved. Reopen and process again
+preserve source/proof history. Process is an explicit authorization for two fresh
+isolated read-only current-source reviews and, on conclusive PRESENT only, a new
+bounded production repair run. UNKNOWN, drift or reviewer errors stay unresolved.
+Native macOS/clean main/checked-out target/trust/run-policy controls remain; a
+refusal preserves its exact code and never triggers a nested-run workaround.
+
+Use the trusted outer host for process; `update --auto-run on` can propose scoped
+run-profile permissions. Do not modify trust or installed settings to bypass a
+refusal. A non-executable claim may use `--review-only-reason 'specific reason'`;
+ABSENT then needs two fresh reasoned reviews. Reproducible bugs need corresponding
+behavioral red-to-green checks. Repair closure uses the exact original finding,
+`followup-resolution` contract, delivered receipt, exact commit and evidence
+digests; generic suite PASS, changed paths or run completion alone cannot close it.
+This workflow adds no DEBUG investigation ceremony or SessionStart summary.

package/docs/en/spec/acceptance-and-evidence.md

@@ -270,3 +270,57 @@ Before committing, use the default worktree scope for verify, review and complet
 This enforces the toolkit's completion command, not a host's natural-language completion claim. It does not prevent a process with the same filesystem authority from editing task/evidence files directly, and it does not lock Git or external source writers.
 
 Project init/update installs `.agent-ops/.gitignore` for `/tasks/` and `/reviews/` on every harness and profile. An existing user-owned `.agent-ops/.gitignore` blocks init/update with `UNMANAGED_INSTALL_PATH`: first back it up outside that path and move its custom rules to the root `.gitignore` (prefix them with `/.agent-ops/`), then retry. Git collection fails with `CHANGE_SURFACE_TRACKED_RUNTIME` if these directories contain indexed files (even clean tracked files), or staged runtime removals. Move any real source files out of the runtime directories, install ignore rules, then use `git rm -r --cached --ignore-unmatch -- .agent-ops/tasks/ .agent-ops/reviews/` to keep local files while removing them from the index. Commit any staged removals before producing fresh verification/review evidence. The active completion Stop gate also blocks this condition with `COMPLETION_GATE_TRACKED_RUNTIME` and the recovery message. Run verify/review from the Git repository root; nested project roots are not supported by the current path/fingerprint collector. Uninstall removes the managed ignore file but preserves runtime output.
+
+## EVIDENCE-FOLLOWUP-001
+
+Retained nonblocking findings and free-text residual risks MUST keep their original
+provenance and MUST NOT be treated as resolved by generic passing checks.
+
+- Trigger: Successful receipt-bound delivery, local history import or explicit selected processing.
+- Action: Collect metadata, preserve provenance/dispositions and assess the current source before any bounded repair.
+- Evidence: Resolution binds the original finding, exact commit and corresponding acceptance artifacts or a reasoned review-only contract with two fresh reviews.
+- Positive: A selected PRESENT finding starts a new native repair; its corresponding red-to-green proof and sealed delivery resolve the exact item.
+- Negative: A generic passing suite, changed path or completed run resolves a retained finding without its specific proof.
+
+- Successful ordinary finish, native final delivery and recovery collect from
+  authenticated local receipts, Git-note digests and full sealed reports. Ordinary
+  repository CLI use retries collection and linked-result reconciliation. Historical
+  `agent-ops followup import` (alias `sync`) is metadata-only: no model calls,
+  assessment, repair or provider quota. Invalid sources warn conservatively;
+  collection is advisory and fail-open after valid completion.
+- Versioned private state lives under the repository Git common directory at
+  `agent-ops/followup/`, shared by linked worktrees, never committed. Exact
+  provenance identities make repeated import idempotent; dispositions, assessment
+  links, repair runs and proof history survive retries. Schema 1 readable receipts
+  retain an explicit legacy contract provenance limit. Source tasks, runs and
+  receipts remain immutable.
+- `followup list` and `show <followup-id>` expose text or `--json` state. Concrete
+  findings are candidates; text risks are observations. `clarify <followup-id>
+  --finding-file <json> --reason <text>` retains the original observation and
+  supplies a concrete nonblocking ReviewFinding with locations and evidence.
+  `accept` and `defer` require nonempty reasons, retain history and are distinct
+  from resolution. `reopen` retains proof history; `process` may be selected again.
+- `followup process <followup-id> --host <claude|codex>` explicitly authorizes
+  current-source revalidation and, only on conclusive PRESENT, a fresh bounded
+  production native repair run without another confirmation. Two independent
+  read-only sessions inspect isolated current source and the immutable finding.
+  UNKNOWN (including reviewer failure, invalid output, timeout, source/config
+  drift or insufficient evidence) cannot launch repair or resolve. Fingerprints,
+  changed paths and path existence alone prove no semantic conclusion.
+- Native repair preserves macOS support, clean main checkout, checked-out target,
+  current trust, run policy, native controls and worktree ownership. Refusals
+  retain the item and exact code; there is no nested-run workaround or restart
+  of the completed source run. An exclusive private claim and reserved run
+  identity prevent duplicate starts; ambiguous interrupted startup stays pending.
+- ABSENT can resolve only under `--review-only-reason <text>` with a specific
+  justified contract and two fresh reviews. Reproducible bugs need corresponding
+  behavioral red-to-green acceptance. Completed repair closure validates the
+  exact original finding's `followup-resolution` criterion, baseline, target,
+  source/config, paired checks or reasoned review-only contract, two fresh sealed
+  reviews, delivered receipt and exact commit/evidence digests. Generic test PASS,
+  run status, acceptance or deferral cannot close it; stale/unlinked proof stays
+  unresolved. Cleanup recovery must retain links.
+- CLI permissions for `followup process` follow the opt-in run profile and appear
+  in normal init/update plans. They grant no trust/policy changes. No Office
+  write UI, SessionStart summary, cloud service or additional mandatory gate is
+  introduced.

package/docs/en/spec/loop-engineering.md

@@ -62,6 +62,17 @@
   Repeat the flag for multiple failures. Successful acknowledgements are audited
   and revalidated on later resumes. This grants no command permission: native
   approval runs again. Existing writer-death, checkout, trust and budget checks apply.
+  `run resume <id> --retry-delivery <task-id>` MAY explicitly requeue one child
+  blocked by `RUN_FINAL_PROOF_INTERRUPTED` after the harness cause is repaired.
+  It MUST require the matching interrupted handoff, confirmed stopped writers
+  and proof, clean owned checkouts and current trust/policy. It MUST preserve
+  run/task/goal/baselines/commits, accounting and failure history, record the
+  acknowledged attempt, and require a fresh native generation and normal proof.
+  It MUST NOT mark delivery, reset another blocker or acknowledge command denial;
+  approval retry is a separate control. Ordinary resume retains no-progress blocks.
+  Interrupted controlled proof MUST record bounded redacted exit/signal, result
+  failure stage and subprocess diagnostics without treating invalid output or a
+  nonzero successful envelope as proof.
   Initial recovery after a current manual resume MAY ignore an owned Codex limit
   snapshot received before activation whose native update second strictly predates
   that resume. Automatic restarts, unknown/equal/future timestamps, clock rollback,
@@ -83,6 +94,31 @@ status and delivered commit. With `jobs=1`, child execution MUST wait for that
 confirmed death. Native registration, recovery and start MUST enforce at most
 `jobs` active agents; changing task slot accounting alone is insufficient.
 
+An explicit answer to a pending run question MAY release a confirmed stopped
+coordinator wait before all children finish. The response consumes only this
+run's current-generation wait, records `RUN_COORDINATOR_RESPONSE_WAKE`, and starts
+no process. Normal resume still reconciles death, trust and policy, then issues a
+fresh generation within the job limit. Ordinary resume and replayed answers do
+not consume a new wait. Child delivery, failure history and policy bindings remain
+unchanged; an answer itself grants no additional command capability.
+
+A run-level proof MUST match its persisted proof PID, process group and process
+start identity, plus the current coordinator ID and generation. That actor may
+read the run policy for the main root and registered worker checkouts, including
+delivered children during integration, without changing its worker environment.
+Worker-local proof remains bound to its own checkout and worker identity; its
+record MUST NOT shadow an independently authenticated run-level proof. Ordinary
+checkout record checks and integration ownership checks remain authoritative.
+Invalid actor, group, generation or unregistered checkout claims return
+`RUN_WORKER_STALE`; an inactive, disabled or awaiting-resume run still returns
+`RUN_POLICY_DISABLED` after identity validation. Policy reads grant no additional
+capability and do not alter config, trust, registration or delivery state.
+
+Known limitation: an inner verification command timeout can terminate the shared
+proof process group before the evidence CLI emits JSON. Response recovery does
+not fix this process isolation defect; a bounded run-only command timeout may be
+assessed through the existing coordinator policy flow, with the failure retained.
+
 This module defines the bounded loop used to plan, implement, verify, and hand off work.
 
 ## LOOP-START-001

package/docs/en/spec/review.md

@@ -5,14 +5,14 @@
 - Trigger: Production task criteria become ready before implementation.
 - Action: Await one scoped advisory and let the writer record adoption/rejection reasons.
 - Evidence: Private snapshot report plus safe local status/usage log; no completion attestation.
-- Positive: `A revised task shows historical advice and only an explicit rerun spends another round.`
-- Negative: `Automatically re-review every revise or treat advice as final PASS proof.`
+- Positive: `Adopting advice rewrites a criterion; that revise reruns the advisory once and shows the new advice.`
+- Negative: `Re-review every revise, including surface-only ones, or treat advice as final PASS proof.`
 
 Every production task creation (including DEBUG, replan children and native run root/child tasks) MUST wait for one independent criteria advisory before implementation. A fresh session uses one configured independent-review target, preferring a different target from the host. It receives only the original goal, assigned intent/covers, criteria and surface audit in an empty disposable workspace. It MUST NOT inspect repository files or run tests. Missing goals are insufficient information; child completeness is scoped to its assignment. Verification materials/import validity remain deferred until implementation; reasoned review-only acceptance is valid.
 
 The advisory has no agent-ops execution deadline, stall cutoff or token budget. Provider limitations, genuine launch/auth/output errors and explicit cancellation remain effective. Errors produce NOT_RUN and permit work; cancellation preserves the task and MUST stop implementation. Native review processes remain registered and stoppable. Normal verification and final two-round review retain their existing deadlines and gates.
 
-Task creation shows advice and a private report reference. The writer decides which recommendations to adopt and records acceptance/rejection reasons through task revise (a same-criteria revision may record rejected advice). Requirements that are ambiguous or expand scope require user clarification. Reports bind the original task/goal/criteria/surface snapshot; task status and revise show historical reports as stale when those inputs change. A revision MUST NOT automatically re-review. Repeated initial requests reuse the first attempt, including NOT_RUN; only explicit `agent-ops review --criteria --task <id> --rerun --yes` starts another fresh single round. Without --rerun the same command reads/waits for the current attempt.
+Task creation shows advice and a private report reference. The writer decides which recommendations to adopt and records acceptance/rejection reasons through task revise (a same-criteria revision may record rejected advice). Requirements that are ambiguous or expand scope require user clarification. Reports bind the original task/goal/criteria/surface snapshot and record their trigger (`create`, `rerun` or `revise`; absent on older reports). Task status and revise show a report as stale when the goal, intent, criteria or assigned scope change; a surface-only change leaves it current. The first saved revision that makes the current report stale, when that report was not itself revise-triggered, MUST wait for one automatic fresh round (trigger `revise`) and show its advice; the revision is kept whether that round completes, reports NOT_RUN or is cancelled. Further revisions MUST NOT automatically re-review until an explicit rerun. Repeated initial requests reuse the first attempt, including NOT_RUN; outside that one automatic round, only explicit `agent-ops review --criteria --task <id> --rerun --yes` starts another fresh single round. Without --rerun the same command reads/waits for the current attempt.
 
 Detailed redacted reports remain private in `.agent-ops/reviews/criteria-<task-id>*.json`; the local log contains only status, duration, counts, reported usage and report reference. CLI invocation counts are distinct from provider model calls, which may be unreported. Report/log failures MUST NOT roll back a task or fabricate evidence. These advisory artifacts MUST NOT satisfy verify, final review or finish.
 
@@ -112,6 +112,40 @@ successful refutation MUST make the run FAIL.
   replays the recorded queries and reads every listed `valueChanges` consumer;
   this is the only exception to "do not survey the repository".
 
+## REVIEW-ORIGIN-001
+
+A defect the change did not cause MUST NOT block the change; it MUST be
+reported as `origin: "pre-existing"` with `blocking: false` and flow to the
+followup ledger.
+
+- Trigger: A reviewer meets a defect while reading for the review.
+- Action: Mark it pre-existing only when it is present identically at the base
+  and the change did not introduce, expose, worsen or depend on it. Report only
+  defects met on the normal read path; do not search for old ones.
+- Evidence: The report validator rejects a pre-existing finding with
+  `blocking: true` at any severity, including critical. A finding without
+  `origin` means introduced and keeps the old severity rules, so stored reports
+  stay valid. Nonblocking findings of a delivered PASS reach followup as before.
+- Positive: `A critical injection in an untouched helper is reported as pre-existing, nonblocking, and collected into followup.`
+- Negative: `A caller in an unchanged file breaks because of this change and is marked pre-existing because its lines were not edited.`
+
+## REVIEW-ROUNDS-001
+
+Review MUST stop after three failed reviews of one task contract and ask for a
+new approach instead of another fix round.
+
+- Trigger: `review` (directly or through `batch`, `task advance` or a run) for a
+  task with three or more FAIL reports bound to its current task contract hash
+  and newer than its latest PASS.
+- Action: Return NOT_RUN `round-cap` before resolving scope or starting any
+  reviewer, printing the exact `task revise` command. Reconsider the approach and
+  revise the criteria or intent with a reason, or ask the user.
+- Evidence: NOT_RUN reports never count; each source fingerprint keeps one
+  report, so re-reviewing unchanged code adds nothing; a contract revision or a
+  newer PASS starts the count again. The cap is a constant, not configuration.
+- Positive: `Third FAIL on the same contract; the agent revises the intent to a different design and reviews again.`
+- Negative: `Keep committing one fix per finding through a fifth review of the same contract.`
+
 ## REVIEW-HOST-001
 
 A host that cannot provide network and loopback capability MUST fail closed

package/docs/zh-TW/guides/configuration.md

@@ -227,6 +227,9 @@ fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方
   `npx lint-staged` 的 allow 規則，讓 pre-commit hook 能寫入主 `.git`。`trust`、
   `allow-stop`、`init`、`update`、`uninstall` 永遠不會被預先授權。關閉 auto 模式或
   `uninstall` 會精確移除這些項目；同名但不是 agent-ops 寫的規則檔不會被動到。
+- opt-in `run` profile 另外在 Claude 與 Codex 授權 `agent-ops run` 與明確選取的
+  `agent-ops followup process`。一般 init/update 計畫會列出精確項目；移除 profile
+  會移除這些權限。中繼資料操作不授予原生執行權限，process 仍遵守目前儲存庫信任與所有原生啟動限制。
 - `review` 與 `doctor` 支援 `--output <file>`：JSON envelope 寫入該檔（權限 0600），
   並只印出一行摘要。請用它取代 shell 重導向；Codex 會把重導向包成 `zsh -lc`，只能
   以整串指令比對來放行。

package/docs/zh-TW/guides/task-debug.md

@@ -35,3 +35,34 @@ prompt hook 自動建立 DEBUG、DEBUG 專用 Stop 阻擋，以及 Codex `Interr
 `originRequired` 不再阻擋 finish，config 的 `features.debug` 仍被接受並在下次 `update` 時移除。
 
 完整說明見英文 [Task DEBUG](../../en/guides/task-debug.md)。
+
+## 保留的審查 followup
+
+finish 後以 `agent-ops followup list`、`followup show <followup-id>` 檢視，agent 可加
+`--json`。`followup import` / `followup sync` 只回填本機歷史中繼資料，不呼叫模型或修復。
+私有狀態在 Git common directory，所有連結 worktree 共用。收集警告不影響原始完成；
+修正來源或狀態問題後可重試。
+
+自由文字觀察需先明確釐清：
+
+```sh
+agent-ops followup clarify <followup-id> --finding-file finding.json --reason '具體主張與來源證據'
+agent-ops followup defer <followup-id> --reason '相依套件升級後再處理'
+agent-ops followup accept <followup-id> --reason '接受此版本的取捨'
+agent-ops followup reopen <followup-id>
+env -u CODEX_SANDBOX_NETWORK_DISABLED agent-ops followup process <followup-id> --host codex
+```
+
+`finding.json` 是一般非阻擋 ReviewFinding：severity、blocking=false、title、details、
+locations（path、line）、evidence、recommendation、criterionIds。接受與延後必須有理由，
+不等於結案；reopen 與再次 process 均保留來源及證據歷史。process 明確授權兩次隔離、
+唯讀、針對目前原始碼的新鮮審查，且只在確定 PRESENT 時啟動全新有界的正式原生修復 run。
+UNKNOWN、漂移與 reviewer 錯誤維持未解決。仍遵守 macOS、乾淨主 checkout、目標分支、
+信任與 run policy；拒絕保留原始碼，不繞過 nested-run 限制。
+
+process 必須透過可信任外層 host；`update --auto-run on` 可提出限定 run profile 權限。
+不可自行修改信任或已安裝設定繞過拒絕。無法用可執行檢查判定的主張可加
+`--review-only-reason '具體理由'`；ABSENT 仍需兩次新鮮且有理由的審查。
+可重現錯誤仍需對應 behavioral 紅轉綠。修復結案驗證原始 finding、`followup-resolution`
+契約、交付 receipt、精確 commit 與證據摘要；一般測試 PASS、路徑變動或 run 完成不能結案。
+本流程不新增 DEBUG 調查手續或 SessionStart 摘要。