@kylecheng3146/agent-ops 0.5.2 → 0.5.3

package/README.md

@@ -347,6 +347,22 @@ agent-ops doctor --check-auth # one real print call per configured target
 
 ### Batch review
 
+For writing subagents in separate worktrees, record each child's complete
+modification intent at task creation (`--intent`), then commit and run its
+local verifier. The coordinator runs `agent-ops task advance --task <parent-id>
+--session <session-id> --yes` from the main checkout through the same trusted
+outer host runner used for review. Advance integrates the committed children,
+verifies every parent and child criterion on the integrated candidate, and
+runs one two-round tree review. Only `NOT_RUN / scope-too-large` falls back to
+per-task two-round reviews; FAIL requires a fix and a fresh final gate. A
+passing gate saves the complete local receipt in `.git/agent-ops/receipts/`
+before finish. A moved target gets at most one automatic rebase and repeat.
+Run `agent-ops review show --task <parent-id>` from the main checkout to read
+both full recorded reports for the latest candidate without invoking a reviewer.
+`task advance` prints a short summary of nonblocking findings and residual risks.
+
+`batch` remains the per-task review command for tasks already in one worktree.
+
 A change split into subtasks needs one verify and one review per subtask.
 `agent-ops batch --parent <task-id> --yes` runs them together for the parent's
 active subtasks and the parent itself, instead of one `review` at a time:

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

@@ -70,6 +70,7 @@ export function parseArgs(argv) {
     let parentTaskId;
     let targetVersion;
     let title;
+    let intent;
     let sessionId;
     let base;
     let parentBase;
@@ -85,6 +86,7 @@ export function parseArgs(argv) {
     let json = false;
     let yes = false;
     let rerun = false;
+    let tree = false;
     let helpSeen = false;
     let versionSeen = false;
     let worktreeName;
@@ -187,6 +189,19 @@ export function parseArgs(argv) {
                 index += 1;
                 break;
             }
+            case "--intent": {
+                if (intent !== undefined)
+                    duplicate(token);
+                intent = readOptionValue(argv, index, token);
+                index += 1;
+                break;
+            }
+            case "--tree": {
+                if (tree)
+                    duplicate(token);
+                tree = true;
+                break;
+            }
             case "--criterion": {
                 criteria.push(readOptionValue(argv, index, token));
                 index += 1;
@@ -365,6 +380,7 @@ export function parseArgs(argv) {
                 if (command === "task" &&
                     action === undefined &&
                     [
+                        "advance",
                         "archive",
                         "attach",
                         "complete",
@@ -375,6 +391,10 @@ export function parseArgs(argv) {
                     action = token;
                     break;
                 }
+                if (command === "review" && action === undefined && token === "show") {
+                    action = "show";
+                    break;
+                }
                 if (command === "worktree" &&
                     action === undefined &&
                     WORKTREE_ACTIONS.includes(token)) {
@@ -433,6 +453,7 @@ export function parseArgs(argv) {
             parentTaskId !== undefined ||
             targetVersion !== undefined ||
             title !== undefined ||
+            intent !== undefined ||
             criteria.length > 0 ||
             evidence.length > 0 ||
             reviewTargets.length > 0 ||
@@ -446,6 +467,7 @@ export function parseArgs(argv) {
             dryRun ||
             yes ||
             rerun ||
+            tree ||
             worktree !== undefined ||
             worktreeFrom !== undefined ||
             worktreeMessage !== undefined ||
@@ -475,11 +497,12 @@ export function parseArgs(argv) {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--message may be used only with worktree commit.", "--message");
     }
     if (command === "task" && action === undefined) {
-        throw new CliArgumentError("CLI_ACTION_REQUIRED", "The task command requires one of: create, status, attach, complete, archive, export.");
+        throw new CliArgumentError("CLI_ACTION_REQUIRED", "The task command requires one of: create, status, attach, complete, archive, export, advance.");
     }
     const hasTaskTargetOptions = taskId !== undefined ||
         sessionId !== undefined;
     const hasTaskMutationOptions = title !== undefined ||
+        intent !== undefined ||
         criteria.length > 0 ||
         evidence.length > 0;
     if (command !== "task" &&
@@ -532,7 +555,7 @@ export function parseArgs(argv) {
         if (harness !== undefined ||
             profiles.length > 0 ||
             dryRun ||
-            yes ||
+            (yes && action !== "advance") ||
             rerun) {
             throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Task commands do not accept harness, profile, dry-run, or yes options.");
         }
@@ -540,7 +563,7 @@ export function parseArgs(argv) {
             (taskId !== undefined ||
                 evidence.length > 0)) ||
             (action === "status" &&
-                (title !== undefined ||
+                (title !== undefined || intent !== undefined ||
                     criteria.length > 0 ||
                     evidence.length > 0 ||
                     // --parent filters the listing, so it cannot name a single target.
@@ -548,21 +571,25 @@ export function parseArgs(argv) {
                         (taskId !== undefined || sessionId !== undefined)) ||
                     (taskId !== undefined && sessionId !== undefined))) ||
             (action === "attach" &&
-                (title !== undefined ||
+                (title !== undefined || intent !== undefined ||
                     criteria.length > 0 ||
                     evidence.length > 0 ||
                     parentTaskId !== undefined)) ||
             (action === "complete" &&
-                (title !== undefined ||
+                (title !== undefined || intent !== undefined ||
                     criteria.length > 0 ||
                     sessionId !== undefined ||
                     parentTaskId !== undefined)) ||
             ((action === "archive" || action === "export") &&
-                (title !== undefined ||
+                (title !== undefined || intent !== undefined ||
                     criteria.length > 0 ||
                     evidence.length > 0 ||
                     sessionId !== undefined ||
-                    parentTaskId !== undefined));
+                    parentTaskId !== undefined)) ||
+            (action === "advance" &&
+                (taskId === undefined || title !== undefined || intent !== undefined ||
+                    criteria.length > 0 || evidence.length > 0 || parentTaskId !== undefined ||
+                    !yes));
         if (taskOptionInvalid) {
             throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", `Unsupported option for task ${action}.`);
         }
@@ -585,7 +612,19 @@ export function parseArgs(argv) {
     if (command === "review" && taskId === undefined) {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Review requires --task for the complete task-bound review.");
     }
-    if (command === "review" && !yes) {
+    if (command === "review" && action === "show" &&
+        (yes || rerun || tree || base !== undefined || output !== undefined ||
+            scope !== undefined || harness !== undefined || profiles.length > 0 ||
+            criteria.length > 0 || evidence.length > 0)) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "review show accepts only --task and optional --json; it never runs a reviewer.");
+    }
+    if (tree && command !== "review") {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--tree may be used only with review.");
+    }
+    if (intent !== undefined && !(command === "task" && action === "create")) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--intent may be used only with task create.");
+    }
+    if (command === "review" && action !== "show" && !yes) {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Review requires --yes to authorize both reviewer sessions.");
     }
     if (command === "review" && harness !== undefined) {
@@ -668,6 +707,7 @@ export function parseArgs(argv) {
         ...(parentTaskId === undefined ? {} : { parentTaskId }),
         ...(targetVersion === undefined ? {} : { targetVersion }),
         ...(title === undefined ? {} : { title }),
+        ...(intent === undefined ? {} : { intent }),
         ...(reviewTargets.length === 0 ? {} : { reviewTargets }),
         ...(completionGate === undefined ? {} : { completionGate }),
         ...(criteria.length === 0 ? {} : { criteria }),
@@ -683,6 +723,7 @@ export function parseArgs(argv) {
         ...(checkAuth ? { checkAuth } : {}),
         ...(checkAuthTargets.length === 0 ? {} : { checkAuthTargets }),
         rerun,
+        ...(tree ? { tree } : {}),
         dryRun,
         json,
         yes,

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

@@ -42,6 +42,8 @@ import { resolveReviewScope } from "../../../runtime/src/review/scope.js";
 import { resolveReviewRole } from "../../../runtime/src/review/roles.js";
 import { runTrustCommand } from "./commands/trust.js";
 import { runVerifyCommand } from "./commands/verify.js";
+import { runAdvanceCommand } from "./commands/advance.js";
+import { runReviewShowCommand } from "./commands/review-show.js";
 import { runAllowStopCommand } from "./commands/allow-stop.js";
 import { CompletionGateService } from "../../../runtime/src/hooks/completion-gate.js";
 import { formatUpdatePlan, runUpdateCommand } from "./commands/update.js";
@@ -402,6 +404,14 @@ else {
                     const sessionId = args.sessionId ?? (actsAsSession
                         ? await resolveCommandSessionId(root)
                         : sessionIdFromEnvironment() ?? await readRecordedSessionId(root));
+                    if (args.action === "advance") {
+                        return await runAdvanceCommand({
+                            cwd: root,
+                            sessionId: sessionId ?? await resolveCommandSessionId(root),
+                            parentTaskId: args.taskId,
+                            deps: worktreeDependencies()
+                        });
+                    }
                     const createConfig = args.action === "create"
                         ? (await loadEffectiveConfig(root, args.scope === "user" ? "user" : "project")).config
                         : undefined;
@@ -519,6 +529,9 @@ else {
                     };
                 };
                 if (args.command === "review") {
+                    if (args.action === "show") {
+                        return await runReviewShowCommand({ cwd: root, taskId: args.taskId, deps: worktreeDependencies() });
+                    }
                     const controller = new AbortController();
                     let interruptedBy;
                     const interrupt = (signal) => {

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

@@ -28,7 +28,7 @@ Commands:
   task <create|status|attach|complete|archive|export>
              Manage independent task acceptance state
   verify     Run configured verification
-  review     Run an independent review
+  review     Run an independent review or show recorded reports
   batch      Verify and review a parent task's subtasks together
   allow-stop Grant one fingerprint-bound completion-gate Stop permit (requires --session)
   agy-run    Run headless agy with a process-exit completion recheck
@@ -141,19 +141,21 @@ Options:
   --json
   --yes
 `,
-    task: `Usage: agent-ops task <create|status|attach|complete|archive|export> [options]
+    task: `Usage: agent-ops task <create|status|attach|complete|archive|export|advance> [options]
 
 Manage independent task acceptance state. Task commands accept none of
---harness, --profile, --dry-run or --yes.
+--harness, --profile or --dry-run. Only advance accepts --yes.
 
 Options:
   --title <text>                        create
+  --intent <text>                       create: intended behavior and constraints before editing
   --criterion <json>                    create, repeatable, two to five total
   --parent <task-id>                    create: record a subtask; status: list subtasks
-  --task <id>                           status, attach, complete, archive, export
-  --session <id>                        attach, status
+  --task <id>                           status, attach, complete, archive, export, advance
+  --session <id>                        create, attach, status, advance
   --evidence <criterion-id=reference>   complete, repeatable
   --base <git-ref>                      complete: a clean committed range
+  --yes                                 advance: authorize the two review sessions
   --json
 
 Each --criterion is one JSON object with exactly these keys:
@@ -174,12 +176,15 @@ Options:
   --json
 `,
     review: `Usage: agent-ops review --task <id> --yes [options]
+       agent-ops review show --task <id> [--json]
 
 Run the complete task-bound review: one necessary reviewer followed by one
-fresh adversarial reviewer from the configured pair.
+fresh adversarial reviewer from the configured pair. Show reads recorded
+reports without running a reviewer, including from the main checkout.
 
 Options:
   --task <id>          Required task whose original criteria are reviewed
+  --tree               Cover this task and every non-archived descendant in one two-round review
   --base <git-ref>     Review a clean committed range
   --output <file>      Write the JSON envelope to <file> (mode 0600) and print
                        one summary line, so no shell redirect is needed

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

@@ -0,0 +1,153 @@
+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 { 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";
+import { renderReviewDetails, renderReviewHighlights } from "../../../../runtime/src/review/render.js";
+import { calculateSourceFingerprint } from "../../../../runtime/src/verify/source-fingerprint.js";
+import { okEnvelope } from "../output.js";
+import { readFinishedReview } from "./review-show.js";
+/** The child process runs the existing CLI in the candidate checkout. */
+export async function runAdvanceStep(cwd, args) {
+    const bin = process.argv[1];
+    if (bin === undefined)
+        throw new AgentOpsError("ADVANCE_CLI_MISSING", "Cannot locate the agent-ops CLI entry point.");
+    return await new Promise((resolveStep, reject) => {
+        const child = spawn(process.execPath, [resolve(bin), ...args, "--json"], {
+            cwd, env: process.env, stdio: ["ignore", "pipe", "inherit"]
+        });
+        const chunks = [];
+        let bytes = 0;
+        child.stdout.on("data", (chunk) => {
+            bytes += chunk.length;
+            if (bytes > 4 * 1024 * 1024)
+                child.kill();
+            else
+                chunks.push(chunk);
+        });
+        child.once("error", reject);
+        child.once("close", () => {
+            try {
+                const value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+                if (value.status !== "ok" && value.status !== "error")
+                    throw new Error("Invalid CLI envelope.");
+                resolveStep(value);
+            }
+            catch {
+                reject(new AgentOpsError("ADVANCE_STEP_UNREADABLE", `Could not read ${args[0]} result from the candidate checkout.`));
+            }
+        });
+    });
+}
+function runner(deps, cwd) {
+    return { run: async (args) => {
+            const result = await deps.git(cwd, args);
+            return { exitCode: result.exitCode, stdout: Buffer.from(result.stdout, "utf8") };
+        } };
+}
+async function git(deps, cwd, args) {
+    const result = await deps.git(cwd, args);
+    if (result.exitCode !== 0)
+        throw new AgentOpsError("ADVANCE_GIT_FAILED", `${args.join(" ")}: ${result.stderr.trim()}`);
+    return result.stdout.trim();
+}
+function requirePass(step, label) {
+    if (step.status === "ok" && (step.data?.result?.status === "PASS" || step.data?.report?.status === "PASS"))
+        return;
+    const result = step.data?.result;
+    const details = result?.report !== undefined || result?.attempts !== undefined
+        ? `\n${renderReviewDetails([{ taskId: result.taskId ?? label, title: label, artifact: result }], "active")}`
+        : step.data?.text ?? "";
+    throw new AgentOpsError(step.code, `${label}: ${step.errors?.[0]?.message ?? result?.reason ?? "proof did not pass"}${details ? `\n${details}` : ""}`);
+}
+export async function reviewFinalTree(step, cwd, parentTaskId, taskIds, base) {
+    const reviewed = await step(cwd, ["review", "--task", parentTaskId, "--tree", "--base", base, "--yes"]);
+    if (reviewed.status === "error" && reviewed.data?.result?.status === "NOT_RUN" &&
+        reviewed.data.result.reason === "scope-too-large") {
+        for (const taskId of taskIds) {
+            requirePass(await step(cwd, ["review", "--task", taskId, "--base", base, "--yes"]), `Review ${taskId}`);
+        }
+        return "per-task-fallback";
+    }
+    requirePass(reviewed, "Tree review");
+    return "tree";
+}
+export async function runAdvanceCommand(options) {
+    const { deps, cwd } = options;
+    if (options.sessionId === undefined || options.parentTaskId === undefined) {
+        throw new AgentOpsError("ADVANCE_TARGET_REQUIRED", "task advance requires --task and a current or explicit --session.");
+    }
+    const { mainRoot, currentRoot, commonDir } = await resolveCheckouts(deps, cwd);
+    if (mainRoot !== currentRoot)
+        throw new AgentOpsError("WORKTREE_NESTED", `Run task advance from ${mainRoot}.`);
+    const name = sessionWorktreeName(options.sessionId);
+    const record = await readWorktreeRecord(worktreePath(mainRoot, name));
+    if (record === null || record.sessionId !== options.sessionId || record.agentId !== undefined) {
+        throw new AgentOpsError("ADVANCE_WORKTREE_MISSING", `No coordinator worktree for session ${options.sessionId}.`);
+    }
+    const parent = await deps.tasks(record.path).status({ taskId: options.parentTaskId });
+    if (parent.status !== "active" || parent.task.parentTaskId !== undefined) {
+        throw new AgentOpsError("ADVANCE_PARENT_INVALID", "Advance requires an active root task in the coordinator worktree.");
+    }
+    const children = await integrateSessionChildren(deps, record, parent.task.id);
+    const step = options.step ?? runAdvanceStep;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const target = await git(deps, mainRoot, ["rev-parse", `${record.targetBranch}^{commit}`]);
+        const branchHead = await git(deps, record.path, ["rev-parse", "HEAD"]);
+        if ((await deps.git(record.path, ["merge-base", "--is-ancestor", target, "HEAD"])).exitCode !== 0) {
+            const rebase = await deps.git(record.path, ["rebase", "--rebase-merges", "--no-autostash", target]);
+            if (rebase.exitCode !== 0) {
+                const files = (await deps.git(record.path, ["diff", "--name-only", "--diff-filter=U"])).stdout.trim();
+                await deps.git(record.path, ["rebase", "--abort"]);
+                throw new AgentOpsError("WORKTREE_REBASE_CONFLICT", `Target moved; rebase conflicted in ${files || "unknown files"}. Candidate remains at ${branchHead}.`);
+            }
+        }
+        const head = await git(deps, record.path, ["rev-parse", "HEAD"]);
+        const all = (await deps.tasks(record.path).list()).filter(({ status }) => status !== "archived");
+        const selected = new Set([parent.task.id]);
+        for (let changed = true; changed;) {
+            changed = false;
+            for (const item of all) {
+                if (item.task.parentTaskId !== undefined && selected.has(item.task.parentTaskId) && !selected.has(item.task.id)) {
+                    selected.add(item.task.id);
+                    changed = true;
+                }
+            }
+        }
+        if (selected.size !== all.length || all.some(({ task, status }) => !selected.has(task.id) || status !== "active")) {
+            throw new AgentOpsError("ADVANCE_TASK_TREE_INVALID", "The candidate has unrelated or already completed tasks; final proof must cover one active tree.");
+        }
+        const ordered = all.filter(({ task }) => selected.has(task.id));
+        for (const task of ordered) {
+            requirePass(await step(record.path, ["verify", "--task", task.task.id, "--base", target]), `Verify ${task.task.id}`);
+        }
+        const reviewMode = await reviewFinalTree(step, record.path, parent.task.id, ordered.map(({ task }) => task.id), target);
+        const scope = await resolveReviewScope({ root: record.path, runner: runner(deps, record.path), base: target });
+        const sourceFingerprint = await calculateSourceFingerprint(record.path, scope, runner(deps, record.path));
+        try {
+            const finished = await finishWorktree(deps, {
+                cwd: mainRoot, name,
+                finalProof: { target, head, sourceFingerprint, children }
+            });
+            if (finished.receipt === undefined)
+                throw new AgentOpsError("WORKTREE_RECEIPT_MISSING", "Finish returned without a final review receipt.");
+            const review = await readFinishedReview(deps, mainRoot, commonDir, finished.receipt);
+            const highlights = renderReviewHighlights(review.entries);
+            return okEnvelope("TASK_ADVANCED", {
+                parentTaskId: parent.task.id,
+                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}`
+            });
+        }
+        catch (failure) {
+            if (failure instanceof AgentOpsError && failure.code === "WORKTREE_TARGET_MOVED" && attempt === 0)
+                continue;
+            throw failure;
+        }
+    }
+    throw new AgentOpsError("WORKTREE_TARGET_MOVED", "The target moved again; preserve the candidate and rerun after coordination.");
+}

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

@@ -0,0 +1,189 @@
+import { readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { sha256 } from "../../../../runtime/src/fs/hash.js";
+import { AgentOpsError } from "../../../../runtime/src/fs/paths.js";
+import { listWorktrees } from "../../../../runtime/src/parallel/manage.js";
+import { NOTES_REF, resolveCheckouts } from "../../../../runtime/src/parallel/service.js";
+import { REVIEW_ATTESTATION_DIRECTORY, REVIEW_REPORT_ARTIFACT_SUFFIX } from "../../../../runtime/src/review/attestation.js";
+import { renderReviewDetails } from "../../../../runtime/src/review/render.js";
+import { validateReviewReport } from "../../../../runtime/src/review/report.js";
+import { resolveReviewScope } from "../../../../runtime/src/review/scope.js";
+import { readPrivateFile } from "../../../../runtime/src/security/permissions.js";
+import { calculateSourceFingerprint } from "../../../../runtime/src/verify/source-fingerprint.js";
+import { okEnvelope } from "../output.js";
+function invalid(message) {
+    throw new AgentOpsError("REVIEW_RECORD_INVALID", message);
+}
+function checkedArtifact(value, fingerprint, taskId) {
+    if (typeof value !== "object" || value === null)
+        invalid("Review artifact is unreadable.");
+    const artifact = value;
+    if (artifact.schemaVersion !== 1 || artifact.sourceFingerprint !== fingerprint ||
+        artifact.taskId !== taskId || !["PASS", "FAIL", "NOT_RUN"].includes(artifact.status) ||
+        !Array.isArray(artifact.attempts) ||
+        (artifact.report !== undefined && !validReport(artifact.report, artifact)) ||
+        (artifact.adversarial !== undefined && !validReport(artifact.adversarial.report, artifact))) {
+        invalid(`Review artifact for ${taskId} does not match the candidate.`);
+    }
+    return artifact;
+}
+function validReport(report, artifact) {
+    const ids = artifact.tree?.criterionIds ?? report?.results?.map(({ criterionId }) => criterionId);
+    return ids !== undefined && validateReviewReport(report, ids).ok;
+}
+function entriesFromReceipt(receipt) {
+    const records = receipt.reviewMode === "tree"
+        ? [receipt.tasks.find(({ task }) => task.parentTaskId === undefined) ?? receipt.tasks[0]]
+        : receipt.tasks;
+    return records.map(({ task }) => {
+        const sealed = receipt.reviews[task.id]?.report;
+        if (sealed === undefined || sha256(JSON.stringify(sealed.value)) !== sealed.digest) {
+            invalid(`Review evidence for ${task.id} is missing or changed.`);
+        }
+        return { taskId: task.id, title: task.title,
+            artifact: checkedArtifact(sealed.value, receipt.sourceFingerprint, task.id) };
+    });
+}
+/** The note binds the private receipt to the merged commit and its exact bytes. */
+export async function readFinishedReview(deps, mainRoot, commonDir, path) {
+    if (dirname(path) !== join(commonDir, "agent-ops", "receipts"))
+        invalid("Final review receipt path is outside the receipt directory.");
+    const source = await readPrivateFile(path, commonDir);
+    if (source === null)
+        invalid("Final review receipt is missing.");
+    let receipt;
+    try {
+        receipt = JSON.parse(source);
+    }
+    catch {
+        return invalid("Final review receipt is malformed.");
+    }
+    if (receipt.schemaVersion !== 1 || !/^[a-f0-9]{40,64}$/u.test(receipt.candidateHead) ||
+        !Array.isArray(receipt.tasks) || receipt.tasks.length === 0 ||
+        !["tree", "per-task-fallback"].includes(receipt.reviewMode) ||
+        typeof receipt.reviews !== "object" || receipt.reviews === null) {
+        invalid("Final review receipt is invalid.");
+    }
+    const note = await deps.git(mainRoot, ["notes", `--ref=${NOTES_REF}`, "show", receipt.candidateHead]);
+    const binding = `\nreceipt: ${path}\nreceipt-sha256: ${sha256(source)}`;
+    if (note.exitCode !== 0 || !note.stdout.trimEnd().endsWith(binding)) {
+        invalid("Final review receipt does not match its Git note.");
+    }
+    return { mode: receipt.reviewMode, candidateHead: receipt.candidateHead,
+        sourceFingerprint: receipt.sourceFingerprint, entries: entriesFromReceipt(receipt), receipt: path };
+}
+async function finishedPath(commonDir, taskId) {
+    const directory = join(commonDir, "agent-ops", "receipts");
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    let latest = null;
+    for (const name of names.filter((item) => /^[a-f0-9]{64}-[a-f0-9]{40,64}\.json$/u.test(item))) {
+        const path = join(directory, name);
+        const source = await readPrivateFile(path, commonDir);
+        if (source === null)
+            continue;
+        try {
+            const receipt = JSON.parse(source);
+            if (!Array.isArray(receipt.tasks) || !receipt.tasks.some(({ task }) => task.id === taskId))
+                continue;
+            if (latest === null || receipt.createdAt > latest.createdAt)
+                latest = { path, createdAt: receipt.createdAt };
+        }
+        catch { /* An unrelated malformed receipt cannot name this task. */ }
+    }
+    return latest?.path ?? null;
+}
+function runner(deps, cwd) {
+    return { run: async (args) => {
+            const result = await deps.git(cwd, args);
+            return { exitCode: result.exitCode, stdout: Buffer.from(result.stdout, "utf8") };
+        } };
+}
+async function activeReview(deps, mainRoot, taskId) {
+    const matching = [];
+    for (const { record } of await listWorktrees(deps, mainRoot)) {
+        const records = await deps.tasks(record.path).list();
+        if (records.some(({ task }) => task.id === taskId))
+            matching.push({ record, records });
+    }
+    if (matching.length > 1)
+        invalid(`Task ${taskId} exists in more than one active worktree.`);
+    const current = matching[0];
+    if (current === undefined)
+        return null;
+    const { record, records } = current;
+    const headResult = await deps.git(record.path, ["rev-parse", "HEAD"]);
+    if (headResult.exitCode !== 0)
+        invalid("Cannot read the active candidate HEAD.");
+    const candidateHead = headResult.stdout.trim();
+    const selected = new Set([taskId]);
+    for (let changed = true; changed;) {
+        changed = false;
+        for (const { task } of records) {
+            if (task.parentTaskId !== undefined && selected.has(task.parentTaskId) && !selected.has(task.id)) {
+                selected.add(task.id);
+                changed = true;
+            }
+        }
+    }
+    const tree = [records.find(({ task }) => task.id === taskId),
+        ...records.filter(({ task }) => selected.has(task.id) && task.id !== taskId)];
+    const target = await deps.git(mainRoot, ["rev-parse", `${record.targetBranch}^{commit}`]);
+    if (target.exitCode !== 0)
+        invalid("Cannot read the target branch for the active candidate.");
+    let fingerprint;
+    try {
+        const scope = await resolveReviewScope({ root: record.path, runner: runner(deps, record.path), base: target.stdout.trim() });
+        fingerprint = await calculateSourceFingerprint(record.path, scope, runner(deps, record.path));
+    }
+    catch (error) {
+        if (error instanceof AgentOpsError && error.code === "REVIEW_DIRTY_WORKTREE") {
+            try {
+                const scope = await resolveReviewScope({ root: record.path, runner: runner(deps, record.path) });
+                fingerprint = await calculateSourceFingerprint(record.path, scope, runner(deps, record.path));
+            }
+            catch { /* No report for this source state. */ }
+        }
+    }
+    const entries = [];
+    for (const { task } of tree) {
+        let artifact = null;
+        if (fingerprint !== undefined) {
+            const source = await readPrivateFile(join(record.path, REVIEW_ATTESTATION_DIRECTORY, `${fingerprint}.${task.id}${REVIEW_REPORT_ARTIFACT_SUFFIX}`), record.path);
+            if (source !== null) {
+                try {
+                    artifact = checkedArtifact(JSON.parse(source), fingerprint, task.id);
+                }
+                catch (error) {
+                    if (error instanceof AgentOpsError)
+                        throw error;
+                    invalid(`Review artifact for ${task.id} is malformed.`);
+                }
+            }
+        }
+        entries.push({ taskId: task.id, title: task.title, artifact });
+    }
+    // A failed whole-tree review writes one parent artifact; its criterion IDs
+    // already cover the whole tree, so do not print empty child aliases.
+    const first = entries[0];
+    const wholeTree = first?.artifact?.report?.results.some(({ criterionId }) => criterionId.includes(":"));
+    return { mode: "active", candidateHead, ...(fingerprint === undefined ? {} : { sourceFingerprint: fingerprint }),
+        entries: wholeTree ? [first] : entries };
+}
+export async function runReviewShowCommand(options) {
+    const { mainRoot, commonDir } = await resolveCheckouts(options.deps, options.cwd);
+    const active = await activeReview(options.deps, mainRoot, options.taskId);
+    const path = active === null ? await finishedPath(commonDir, options.taskId) : null;
+    const view = active ?? (path === null ? null : await readFinishedReview(options.deps, mainRoot, commonDir, path));
+    if (view === null)
+        throw new AgentOpsError("REVIEW_TASK_NOT_FOUND", `No active or finished review task ${options.taskId}.`);
+    return okEnvelope("REVIEW_SHOWN", { ...view,
+        text: `Candidate: ${view.candidateHead}\n${renderReviewDetails(view.entries, view.mode)}` });
+}