@kylecheng3146/agent-ops 0.3.0 → 0.3.2

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

@@ -193,6 +193,20 @@ export async function completeInitChoices(args, io, setup = {}) {
         const reviewTargets = args.reviewTargets ?? (enabled && eligibleReviewChoices.length > 0
             ? await selectOptions("Review targets (multi-select: tried in listed order)", eligibleReviewChoices, selectorIo, REVIEW_TARGET_ORDER.filter((target) => harness.includes(target)), { startEmpty: true })
             : []);
+        const worktree = args.worktree ?? (scope === "project"
+            ? (await selectOption("Enable Git worktree isolation for parallel agent sessions?", [
+                {
+                    label: "yes",
+                    value: "auto",
+                    description: "Recommended. Isolates each agent session in a dedicated worktree."
+                },
+                {
+                    label: "no",
+                    value: "off",
+                    description: "Keep a single shared checkout."
+                }
+            ], selectorIo))
+            : undefined);
         await probeReviewTargets(reviewTargets, setup);
         return {
             ...args,
@@ -200,7 +214,8 @@ export async function completeInitChoices(args, io, setup = {}) {
             harness,
             profiles,
             ...(completionGate ? { completionGate: true } : {}),
-            ...(reviewTargets.length === 0 ? {} : { reviewTargets })
+            ...(reviewTargets.length === 0 ? {} : { reviewTargets }),
+            ...(worktree !== undefined ? { worktree } : {})
         };
     }
     const session = await createPromptSession(io);
@@ -220,13 +235,17 @@ export async function completeInitChoices(args, io, setup = {}) {
             ? selectReviewTargets(await session.question(`Review targets (${defaultReviewTargets.join(",") || "none"}): `), defaultReviewTargets)
             : []);
         await probeReviewTargets(reviewTargets, setup);
+        const worktree = args.worktree ?? (scope === "project"
+            ? (!/^(n|no)$/i.test((await session.question("Enable Git worktree isolation for parallel agent sessions? [Y/n]: ")).trim()) ? "auto" : "off")
+            : undefined);
         return {
             ...args,
             scope,
             harness,
             profiles,
             ...(completionGate ? { completionGate: true } : {}),
-            ...(reviewTargets.length === 0 ? {} : { reviewTargets })
+            ...(reviewTargets.length === 0 ? {} : { reviewTargets }),
+            ...(worktree !== undefined ? { worktree } : {})
         };
     }
     finally {

package/dist/runtime/src/adapters/claude/config.js

@@ -42,7 +42,8 @@ function commandHook(event, runtimePath, completionGate = false) {
             CLAUDE_HOOK_MARKER,
             ...(completionGate ? ["--completion-gate"] : [])
         ],
-        timeout: 30
+        // PreToolUse may create the session's worktree, setup steps included.
+        timeout: event === "PreToolUse" ? 600 : 30
     };
 }
 function matcherGroup(event, runtimePath, completionGate = false) {

package/dist/runtime/src/hooks/completion-gate.js

@@ -228,7 +228,7 @@ export class CompletionGateService {
             this.#options.config.worktree?.mode === "auto" &&
             state.root === undefined &&
             await readWorktreeRecord(this.#options.root) === null) {
-            return gateResult("continue", "UNKNOWN", "COMPLETION_GATE_WORKTREE_MODE", `worktree.mode is auto. Session: ${sessionId}. Before your first edit run agent-ops worktree add <name> --session ${shellQuote(sessionId)} and work only inside the printed path.`);
+            return gateResult("continue", "UNKNOWN", "COMPLETION_GATE_WORKTREE_MODE", `worktree.mode is auto. Session: ${sessionId}. Before your first edit run agent-ops task create from this checkout, which creates this session's worktree and puts the task there (or agent-ops worktree add <name> --session ${shellQuote(sessionId)}), and work only inside the printed path. Verify and review there, then finish with agent-ops worktree finish from this checkout, which completes the tasks; do not run task complete in the worktree.`);
         }
         return gateResult("continue", changed ? "UNKNOWN" : "PASS", changed ? "COMPLETION_GATE_CHANGED" : "COMPLETION_GATE_READY", changed
             ? `Git-visible changes require an attached completed task, current PASS evidence, and a PASS review. Session: ${sessionId}. Create with --session ${sessionId}; one-time permit: agent-ops allow-stop --session ${sessionId}.`

package/dist/runtime/src/install/harness.js

@@ -311,7 +311,7 @@ export function managedRules(descriptor, context) {
         lines.push("For every change:", "", "1. Define two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope and preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Start this command through the trusted outer host runner as its first", "   and only invocation. On Codex, the outer tool request must use", "   `sandbox_permissions: \"require_escalated\"` so network and loopback", "   are available; in that same request, unset", "   `CODEX_SANDBOX_NETWORK_DISABLED` and set `AGENT_OPS_HOST` when three", "   targets are configured. The Codex shell form is", "   `env -u CODEX_SANDBOX_NETWORK_DISABLED AGENT_OPS_HOST=<current-host> agent-ops review --task <task-id> --yes`.", "   Do not run it once in the restricted sandbox and retry; changing the", "   variable inside that sandbox is not elevation.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
     }
     if (context.capabilities.includes("task")) {
-        lines.push("Split a change that exceeds five acceptance criteria into subtasks:", "`agent-ops task create --parent <task-id>` records one, and", "`agent-ops task status --parent <task-id>` lists them. Each subtask", "carries its own criteria, verification, and independent review;", "completing one never completes its parent.", "", "Delegate a subtask whose scope spans unknown files, broad scans, or an", "independent workstream instead of doing it inline. Name the bounded", "scope, the artifact to return, and the acceptance criteria it serves.", subagentInstruction(descriptor), "Read every returned artifact back yourself: integration, verification,", "and review stay with the coordinator.", "", "One writer at a time. `agent-ops verify` and `agent-ops review`", "fingerprint the working tree and report UNKNOWN when anything else", "writes it during the run, so delegate edits to one subagent at a time,", "or give each writer its own Git worktree and merge before verifying.", "Read-only delegation has no such limit and may run in parallel.", "", "Parallel conversations in one repository each need their own worktree.", "When `.agent-ops/config.json` sets `worktree.mode` to `auto`, run", "`agent-ops worktree add <name> --session <session-id>` from the main", "checkout before your first edit, and work only inside the printed path", "(Claude Code: EnterWorktree with that path; otherwise use it as every", "command's working directory). Commit, then run verify, review and", "`task complete` with the printed `--base`; leave the worktree (Claude", "Code: ExitWorktree with action keep) and run `agent-ops worktree finish", "<name>` from the main checkout. A finish that reports a conflict is", "resolved once, as a new task whose criteria cover both intents; if its", "verification or review fails, reset as instructed and report.", "");
+        lines.push("Split a change that exceeds five acceptance criteria into subtasks:", "`agent-ops task create --parent <task-id>` records one, and", "`agent-ops task status --parent <task-id>` lists them. Each subtask", "carries its own criteria, verification, and independent review;", "completing one never completes its parent.", "", "Delegate a subtask whose scope spans unknown files, broad scans, or an", "independent workstream instead of doing it inline. Name the bounded", "scope, the artifact to return, and the acceptance criteria it serves.", subagentInstruction(descriptor), "Read every returned artifact back yourself: integration, verification,", "and review stay with the coordinator.", "", "One writer at a time. `agent-ops verify` and `agent-ops review`", "fingerprint the working tree and report UNKNOWN when anything else", "writes it during the run, so delegate edits to one subagent at a time,", "or give each writer its own Git worktree and merge before verifying.", "Read-only delegation has no such limit and may run in parallel.", "", "Parallel conversations in one repository each need their own worktree.", "When `.agent-ops/config.json` sets `worktree.mode` to `auto`, run", "`agent-ops task create` from the main checkout before your first edit:", "it creates this session's worktree and puts the task there (`agent-ops", "worktree add <name> --session <session-id>` does the same without a", "task). Work only inside the printed path", "(Claude Code: EnterWorktree with that path; otherwise use it as every", "command's working directory). Commit, then run verify and review for", "each task with the printed `--base`; do not run `task complete` in the", "worktree. Leave it (Claude Code: ExitWorktree with action keep) and run", "`agent-ops worktree finish <name>` from the main checkout: it completes", "every task in the worktree, subtasks first, then merges. A finish that", "reports an incomplete task names it; verify or review that task again", "in the worktree and finish again. A finish that reports a conflict is", "resolved once, as a new task whose criteria cover both intents; if its", "verification or review fails, reset as instructed and report.", "");
     }
     if (context.capabilities.includes("lifecycle-summary")) {
         lines.push("Advisory lifecycle summaries and local logs are informational. Advisory", "failures must remain fail-open and cannot become verification evidence.", "");

package/dist/runtime/src/install/parallel-setup.js

@@ -0,0 +1,63 @@
+import { lstat } from "node:fs/promises";
+import { join } from "node:path";
+const LOCKFILES = [
+    { path: "bun.lock", packageManager: "bun" },
+    { path: "bun.lockb", packageManager: "bun" },
+    { path: "npm-shrinkwrap.json", packageManager: "npm" },
+    { path: "package-lock.json", packageManager: "npm" },
+    { path: "pnpm-lock.yaml", packageManager: "pnpm" },
+    { path: "yarn.lock", packageManager: "yarn" }
+];
+const SETUP_COMMANDS = {
+    npm: ["ci"],
+    pnpm: ["install", "--frozen-lockfile"],
+    yarn: ["install", "--immutable"],
+    bun: ["install", "--frozen-lockfile"]
+};
+function hasErrorCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+async function regularFileExists(filePath) {
+    try {
+        const status = await lstat(filePath);
+        return status.isFile() && !status.isSymbolicLink();
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT")) {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * Detects project lockfiles and proposes safe, deterministic dependency installation
+ * commands for freshly cloned worktrees. Returns an empty array if detection is
+ * ambiguous or unsupported.
+ */
+export async function detectWorktreeSetup(root) {
+    const detected = await Promise.all(LOCKFILES.map(async (def) => (await regularFileExists(join(root, def.path))) ? def.packageManager : null));
+    const managers = [...new Set(detected.filter((m) => m !== null))];
+    if (managers.length !== 1) {
+        return [];
+    }
+    const manager = managers[0];
+    const args = SETUP_COMMANDS[manager];
+    return [{ command: manager, args: [...args] }];
+}
+/**
+ * Returns a warning message if local environment files (.env) are detected
+ * without a .worktreeinclude file to carry them into new worktrees.
+ */
+export async function checkWorktreeEnvWarning(root) {
+    const hasWorktreeInclude = await regularFileExists(join(root, ".worktreeinclude"));
+    if (hasWorktreeInclude) {
+        return undefined;
+    }
+    const envCandidates = [".env", ".env.local"];
+    for (const candidate of envCandidates) {
+        if (await regularFileExists(join(root, candidate))) {
+            return "Local environment files (.env) detected without .worktreeinclude; consider creating .worktreeinclude to copy them to new worktrees.";
+        }
+    }
+    return undefined;
+}

package/dist/runtime/src/install/plan.js

@@ -78,7 +78,7 @@ async function detectVerificationCommands(root) {
         blockers: discovery.decisions.map((decision) => `${decision.adapter}: ${decision.message}`)
     };
 }
-function buildConfig(profiles, existing, reviewTargets = [], detectedCommands = [], completionGateEnabled = false) {
+function buildConfig(profiles, existing, reviewTargets = [], detectedCommands = [], completionGateEnabled = false, worktree) {
     // Absent reviewRoles means external review is disabled; an empty selection
     // must therefore omit the field rather than write an empty array.
     const reviewRoles = reviewTargets.length > 0
@@ -88,6 +88,9 @@ function buildConfig(profiles, existing, reviewTargets = [], detectedCommands =
         existing.verification.commands.length > 0
         ? existing.verification
         : { commands: [...detectedCommands] };
+    const effectiveWorktree = worktree !== undefined
+        ? (worktree === null ? undefined : structuredClone(worktree))
+        : (existing?.worktree === undefined ? undefined : structuredClone(existing.worktree));
     return {
         schemaVersion: CONFIG_SCHEMA_VERSION,
         profiles: [...profiles],
@@ -103,12 +106,10 @@ function buildConfig(profiles, existing, reviewTargets = [], detectedCommands =
         pathMappings: existing?.pathMappings ?? [],
         securityExceptions: existing?.securityExceptions ?? [],
         ...(reviewRoles === undefined ? {} : { reviewRoles: [...reviewRoles] }),
-        ...(existing?.worktree === undefined
-            ? {}
-            : { worktree: structuredClone(existing.worktree) })
+        ...(effectiveWorktree === undefined ? {} : { worktree: effectiveWorktree })
     };
 }
-async function planConfig(root, profiles, existingManifest, suppliedConfig, reviewTargets = [], completionGateEnabled = false) {
+async function planConfig(root, profiles, existingManifest, suppliedConfig, reviewTargets = [], completionGateEnabled = false, worktree) {
     const current = await readCurrentFile(root, CONFIG_PATH);
     const owned = findOwnedArtifact(existingManifest, CONFIG_PATH);
     if (current !== null && owned === undefined) {
@@ -144,7 +145,7 @@ async function planConfig(root, profiles, existingManifest, suppliedConfig, revi
         existingConfig.verification.commands.length === 0
         ? await detectVerificationCommands(root)
         : { commands: [], blockers: [] };
-    const config = buildConfig(profiles, existingConfig, reviewTargets, detected.commands, completionGateEnabled);
+    const config = buildConfig(profiles, existingConfig, reviewTargets, detected.commands, completionGateEnabled, worktree);
     const content = `${JSON.stringify(config, null, 2)}\n`;
     return {
         operation: {
@@ -493,7 +494,7 @@ export async function createInstallPlan(options) {
         : [];
     const operations = [];
     const artifacts = [];
-    const config = await planConfig(options.root, resolved.profiles, existing?.manifest ?? null, options.existingConfig, options.reviewTargets ?? [], completionGateEnabled);
+    const config = await planConfig(options.root, resolved.profiles, existing?.manifest ?? null, options.existingConfig, options.reviewTargets ?? [], completionGateEnabled, options.worktree);
     operations.push(config.operation);
     artifacts.push(config.record);
     for (const artifact of contribution.artifacts) {

package/dist/runtime/src/install/update.js

@@ -123,7 +123,10 @@ export async function createUpdatePlan(options) {
         existingConfig: {
             value: configPreview.migrated,
             sourceHash: configPreview.sourceHash
-        }
+        },
+        ...(options.worktree === undefined
+            ? {}
+            : { worktree: options.worktree })
     });
     return {
         targetVersion,

package/dist/runtime/src/parallel/finish.js

@@ -159,12 +159,35 @@ async function targetIntents(deps, cwd, target) {
     }
     return intents;
 }
-function noteText(record, task) {
+/** Each tree top first, its subtasks after it; `depth` counts parents. */
+function taskTree(tasks) {
+    const ids = new Set(tasks.map(({ task }) => task.id));
+    const ordered = [];
+    const visit = (parent, depth) => {
+        for (const task of tasks) {
+            const own = task.task.parentTaskId !== undefined && ids.has(task.task.parentTaskId)
+                ? task.task.parentTaskId
+                : undefined;
+            if (own === parent) {
+                ordered.push({ task, depth });
+                visit(task.task.id, depth + 1);
+            }
+        }
+    };
+    visit(undefined, 0);
+    return ordered;
+}
+function noteText(record, tasks) {
     return [
-        `agent-ops task ${task.task.id}: ${task.task.title}`,
         `worktree: ${record.name} (${record.branch})`,
-        "criteria:",
-        ...task.task.criteria.map(({ id, description }) => `- ${id}: ${description}`)
+        ...tasks.flatMap(({ task, depth }) => {
+            const indent = "  ".repeat(depth);
+            return [
+                `${indent}agent-ops task ${task.task.id}: ${task.task.title}`,
+                `${indent}criteria:`,
+                ...task.task.criteria.map(({ id, description }) => `${indent}- ${id}: ${description}`)
+            ];
+        })
     ].join("\n");
 }
 /**
@@ -200,12 +223,29 @@ export async function finishWorktree(deps, options) {
             throw finishError("WORKTREE_NOTHING_TO_MERGE", `${record.branch} has no commits beyond ${record.targetBranch}; remove the worktree instead.`);
         }
         const worktreeConfig = await deps.loadConfig(record.path);
+        // The whole branch merges, so every task in the worktree completes first,
+        // subtasks before their parents, each over the range its review covered.
+        // Before any rebase: rebasing rewrites the commits those fingerprints name.
+        const tree = taskTree((await deps.tasks(record.path).list()).filter(({ status }) => status !== "archived"));
+        if (tree.length === 0) {
+            throw finishError("WORKTREE_TASK_INCOMPLETE", "The worktree has no task; create one, verify and review it before finishing.");
+        }
+        for (const { task } of [...tree].sort((left, right) => right.depth - left.depth)) {
+            if (task.status === "complete")
+                continue;
+            const base = task.reviewBase ?? record.base;
+            try {
+                await deps.tasks(record.path, base).complete(task.task.id, {});
+            }
+            catch (error) {
+                throw finishError("WORKTREE_TASK_INCOMPLETE", `Task ${task.task.id} (${task.task.title}) could not be completed against ${base}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
         const worktreeGate = await deps.gate(record.path, worktreeConfig);
         const problem = await worktreeGate.validate(record.sessionId);
         if (problem !== null) {
             throw finishError("WORKTREE_TASK_INCOMPLETE", `The worktree's task is not ready to merge (${problem.code}). ${problem.remedy ?? ""}`.trim());
         }
-        const task = await deps.tasks(record.path).status({ sessionId: record.sessionId });
         const head = await git(deps, record.path, ["rev-parse", "HEAD"], "WORKTREE_LOG_FAILED", "Git could not read HEAD.");
         const fastForward = (await deps.git(record.path, ["merge-base", "--is-ancestor", target, "HEAD"])).exitCode === 0;
         if (!fastForward) {
@@ -248,7 +288,7 @@ export async function finishWorktree(deps, options) {
                 warnings.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
             }
         };
-        await attempt("note", async () => await git(deps, mainRoot, ["notes", `--ref=${NOTES_REF}`, "add", "-f", "-m", noteText(record, task), mergedHead], "WORKTREE_NOTE_FAILED", "Git could not write the agent-ops note."));
+        await attempt("note", async () => await git(deps, mainRoot, ["notes", `--ref=${NOTES_REF}`, "add", "-f", "-m", noteText(record, tree), mergedHead], "WORKTREE_NOTE_FAILED", "Git could not write the agent-ops note."));
         if (gateEnabled) {
             await attempt("gate", async () => {
                 const mainGate = await deps.gate(mainRoot, mainConfig);
@@ -258,6 +298,6 @@ export async function finishWorktree(deps, options) {
         }
         await attempt("trust", async () => await deps.trust.revoke(record.path, worktreeConfig));
         await attempt("remove", async () => await removeCheckout(deps, record, true));
-        return { record, mergedHead, rebased: !fastForward, taskId: task.task.id, warnings };
+        return { record, mergedHead, rebased: !fastForward, taskIds: tree.map(({ task }) => task.task.id), warnings };
     });
 }

package/dist/runtime/src/parallel/guard.js

@@ -1,5 +1,5 @@
 import { realpath } from "node:fs/promises";
-import { basename, dirname, join, sep } from "node:path";
+import { basename, dirname, join, relative, sep } from "node:path";
 import { insideWorktreeDirectory } from "./service.js";
 /** The main checkout of the repository `runner` runs in, or null. */
 export async function resolveMainRoot(runner) {
@@ -41,17 +41,34 @@ export async function canonicalPath(path) {
  * `.worktrees/<name>`. Paths outside the repository are not this guard's
  * business.
  */
-export async function evaluateWorktreeWrite(mainRoot, paths, sessionId) {
+export async function evaluateWorktreeWrite(mainRoot, paths, sessionId, 
+/** Creates or reuses this session's worktree and returns its path. */
+ensureWorktree) {
     for (const path of paths) {
         const target = await canonicalPath(path);
         const inMain = target === mainRoot || target.startsWith(`${mainRoot}${sep}`);
         if (inMain && !insideWorktreeDirectory(mainRoot, target)) {
+            let failure = "";
+            if (sessionId !== undefined && ensureWorktree !== undefined) {
+                try {
+                    const worktree = await ensureWorktree(sessionId);
+                    return {
+                        action: "block",
+                        status: "FAIL",
+                        code: "WORKTREE_CREATED",
+                        remedy: `worktree.mode is auto, so this session now has its own worktree at ${worktree}. Enter it (Claude Code: EnterWorktree with path ${worktree}) and redo this edit there, at ${join(worktree, relative(mainRoot, target))}.`
+                    };
+                }
+                catch (error) {
+                    failure = ` Creating this session's worktree failed: ${error instanceof Error ? error.message : String(error)}`;
+                }
+            }
             const session = sessionId ?? "<session-id>";
             return {
                 action: "block",
                 status: "FAIL",
                 code: "WORKTREE_REQUIRED",
-                remedy: `worktree.mode is auto, so the main checkout is shared and not edited directly. Run \`agent-ops worktree add <name> --session ${session}\` in ${mainRoot}, enter the printed path (Claude Code: EnterWorktree with that path), and edit there.`
+                remedy: `worktree.mode is auto, so the main checkout is shared and not edited directly.${failure} Run \`agent-ops worktree add <name> --session ${session}\` in ${mainRoot}, enter the printed path (Claude Code: EnterWorktree with that path), and edit there.`
             };
         }
     }

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

@@ -261,3 +261,21 @@ export async function addWorktree(deps, options) {
         throw error;
     }
 }
+/** `session-` plus the session id's first eight name-safe characters. */
+export function sessionWorktreeName(sessionId) {
+    const slug = sessionId.toLowerCase().replace(/[^a-z0-9]/gu, "").slice(0, 8);
+    return `session-${slug === "" ? "0" : slug}`;
+}
+/**
+ * The worktree `sessionId` works in, created on first use. One already bound
+ * to the same session is reused, so a session blocked twice before it moves
+ * still gets exactly one worktree.
+ */
+export async function ensureSessionWorktree(deps, options) {
+    const { mainRoot } = await resolveCheckouts(deps, options.cwd);
+    const name = sessionWorktreeName(options.sessionId);
+    const existing = await readWorktreeRecord(worktreePath(mainRoot, name));
+    if (existing?.sessionId === options.sessionId)
+        return existing;
+    return (await addWorktree(deps, { cwd: mainRoot, name, sessionId: options.sessionId })).record;
+}

package/dist/runtime/src/review/attestation.js

@@ -39,8 +39,18 @@ function safePreflight(attempt) {
         ...(attempt.diagnostic === undefined ? {} : { diagnostic: safeText(attempt.diagnostic) })
     };
 }
-function artifactPath(root, fingerprint) {
-    return join(root, ...REVIEW_ATTESTATION_DIRECTORY.split("/"), `${fingerprint}${REVIEW_REPORT_ARTIFACT_SUFFIX}`);
+/**
+ * A task's review records live under `<fingerprint>.<task id>`, so a parent
+ * and its subtask reviewed on the same source each keep their own PASS until
+ * `worktree finish` completes both. A bare `<fingerprint>` is a record with no
+ * task, or one written before records were kept per task; readers fall back
+ * to it.
+ */
+function recordKey(fingerprint, taskId) {
+    return taskId === undefined ? fingerprint : `${fingerprint}.${taskId}`;
+}
+function artifactPath(root, fingerprint, taskId) {
+    return join(root, ...REVIEW_ATTESTATION_DIRECTORY.split("/"), `${recordKey(fingerprint, taskId)}${REVIEW_REPORT_ARTIFACT_SUFFIX}`);
 }
 export function reviewReportDigest(report) {
     return sha256(JSON.stringify(redactReviewReport(report)));
@@ -127,7 +137,8 @@ function matchingReportArtifact(value, attestation) {
         attempts.every((attempt, index) => attempt.sessionId === attestation.reviewSessionIds[index]));
 }
 async function hasMatchingReportArtifact(root, attestation) {
-    const source = await readPrivateFile(artifactPath(root, attestation.sourceFingerprint), root);
+    // `reportArtifact` was validated to name this fingerprint's own record.
+    const source = await readPrivateFile(join(root, ...attestation.reportArtifact.split("/")), root);
     if (source === null) {
         return false;
     }
@@ -150,12 +161,12 @@ export async function saveReviewReportArtifact(root, result, sourceFingerprint,
     if (Buffer.byteLength(serialized, "utf8") > REPORT_ARTIFACT_MAX_BYTES) {
         throw new AgentOpsError("REVIEW_REPORT_ARTIFACT_TOO_LARGE", "Review report artifact exceeds the capture limit.");
     }
-    const relativePath = `${REVIEW_ATTESTATION_DIRECTORY}/${sourceFingerprint}${REVIEW_REPORT_ARTIFACT_SUFFIX}`;
-    await writePrivateFile(artifactPath(root, sourceFingerprint), serialized, root);
+    const relativePath = `${REVIEW_ATTESTATION_DIRECTORY}/${recordKey(sourceFingerprint, taskId)}${REVIEW_REPORT_ARTIFACT_SUFFIX}`;
+    await writePrivateFile(artifactPath(root, sourceFingerprint, taskId), serialized, root);
     return relativePath;
 }
-function attestationPath(root, fingerprint) {
-    return join(root, ...REVIEW_ATTESTATION_DIRECTORY.split("/"), `${fingerprint}.json`);
+function attestationPath(root, fingerprint, taskId) {
+    return join(root, ...REVIEW_ATTESTATION_DIRECTORY.split("/"), `${recordKey(fingerprint, taskId)}.json`);
 }
 function parseAttestation(value) {
     if (typeof value !== "object" || value === null) {
@@ -183,8 +194,12 @@ function parseAttestation(value) {
         typeof record.adversarialReportDigest !== "string" ||
         !DIGEST_PATTERN.test(record.adversarialReportDigest) ||
         typeof record.reportArtifact !== "string" ||
-        record.reportArtifact !==
-            `${REVIEW_ATTESTATION_DIRECTORY}/${record.sourceFingerprint}${REVIEW_REPORT_ARTIFACT_SUFFIX}` ||
+        // Its own per-task record, or the bare one an older review wrote.
+        ![
+            recordKey(record.sourceFingerprint, record.taskId),
+            record.sourceFingerprint
+        ].some((key) => record.reportArtifact ===
+            `${REVIEW_ATTESTATION_DIRECTORY}/${key}${REVIEW_REPORT_ARTIFACT_SUFFIX}`) ||
         (record.hostTarget !== undefined && !isReviewTarget(record.hostTarget)) ||
         typeof record.createdAt !== "string" ||
         !Number.isFinite(Date.parse(record.createdAt))) {
@@ -214,33 +229,61 @@ export async function saveReviewAttestation(root, attestation) {
     if (!(await hasMatchingReportArtifact(root, validated))) {
         throw new AgentOpsError("REVIEW_ATTESTATION_INVALID", "Review attestation has no matching report artifact.");
     }
-    const relativePath = `${REVIEW_ATTESTATION_DIRECTORY}/${validated.sourceFingerprint}.json`;
-    await writePrivateFile(attestationPath(root, validated.sourceFingerprint), `${JSON.stringify(validated, null, 2)}\n`, root);
+    const relativePath = `${REVIEW_ATTESTATION_DIRECTORY}/${recordKey(validated.sourceFingerprint, validated.taskId)}.json`;
+    await writePrivateFile(attestationPath(root, validated.sourceFingerprint, validated.taskId), `${JSON.stringify(validated, null, 2)}\n`, root);
     return relativePath;
 }
 /**
- * Returns the attestation recorded for this exact source state, or null. A
- * malformed file reads as absent: a gate must fail closed on garbage, never
- * treat it as a passing review.
+ * The record keys that may hold `taskId`'s review of this source: its own,
+ * then the bare one. Without a task, every task's record for the source.
  */
-export async function findReviewAttestation(root, sourceFingerprint) {
-    if (!FINGERPRINT_PATTERN.test(sourceFingerprint)) {
-        return null;
-    }
-    const source = await readPrivateFile(attestationPath(root, sourceFingerprint), root);
-    if (source === null) {
-        return null;
+async function candidateKeys(root, sourceFingerprint, taskId, suffix) {
+    if (taskId !== undefined) {
+        return [recordKey(sourceFingerprint, taskId), sourceFingerprint];
     }
+    let names = [];
     try {
-        const attestation = parseAttestation(JSON.parse(source));
-        return attestation?.sourceFingerprint === sourceFingerprint &&
-            await hasMatchingReportArtifact(root, attestation)
-            ? attestation
-            : null;
+        names = await readdir(join(root, ...REVIEW_ATTESTATION_DIRECTORY.split("/")));
     }
     catch {
+        // No reviews yet.
+    }
+    const own = names
+        .filter((name) => name.startsWith(`${sourceFingerprint}.`) && name.endsWith(suffix))
+        .map((name) => name.slice(0, -suffix.length))
+        .filter((key) => key !== sourceFingerprint && !key.endsWith(".reports") &&
+        TASK_ID_PATTERN.test(key.slice(sourceFingerprint.length + 1)));
+    return [sourceFingerprint, ...own];
+}
+/**
+ * Returns the attestation recorded for this exact source state, or null. A
+ * malformed file reads as absent: a gate must fail closed on garbage, never
+ * treat it as a passing review. With `taskId`, only that task's record or the
+ * bare one; callers still check the task the attestation names.
+ */
+export async function findReviewAttestation(root, sourceFingerprint, taskId) {
+    if (!FINGERPRINT_PATTERN.test(sourceFingerprint) ||
+        (taskId !== undefined && !TASK_ID_PATTERN.test(taskId))) {
         return null;
     }
+    for (const key of await candidateKeys(root, sourceFingerprint, taskId, ".json")) {
+        const source = await readPrivateFile(join(root, ...REVIEW_ATTESTATION_DIRECTORY.split("/"), `${key}.json`), root);
+        if (source === null) {
+            continue;
+        }
+        try {
+            const attestation = parseAttestation(JSON.parse(source));
+            if (attestation?.sourceFingerprint === sourceFingerprint &&
+                recordKey(sourceFingerprint, key === sourceFingerprint ? undefined : attestation.taskId) === key &&
+                await hasMatchingReportArtifact(root, attestation)) {
+                return attestation;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
 }
 /**
  * The stored report behind an attestation, for a caller that wants to reuse
@@ -248,35 +291,64 @@ export async function findReviewAttestation(root, sourceFingerprint) {
  * parses, matches this exact source and records a PASS: a reuse path must fail
  * closed exactly like the gates that read the attestation.
  */
-export async function readReviewReportArtifact(root, sourceFingerprint) {
-    if (!FINGERPRINT_PATTERN.test(sourceFingerprint)) {
+export async function readReviewReportArtifact(root, sourceFingerprint, taskId) {
+    if (!FINGERPRINT_PATTERN.test(sourceFingerprint) ||
+        (taskId !== undefined && !TASK_ID_PATTERN.test(taskId))) {
         return null;
     }
-    const source = await readPrivateFile(artifactPath(root, sourceFingerprint), root);
+    const keys = taskId === undefined
+        ? [sourceFingerprint]
+        : [recordKey(sourceFingerprint, taskId), sourceFingerprint];
+    for (const key of keys) {
+        const source = await readPrivateFile(join(root, ...REVIEW_ATTESTATION_DIRECTORY.split("/"), `${key}${REVIEW_REPORT_ARTIFACT_SUFFIX}`), root);
+        if (source === null) {
+            continue;
+        }
+        try {
+            const value = JSON.parse(source);
+            if (value.sourceFingerprint === sourceFingerprint &&
+                value.status === "PASS" &&
+                value.report !== undefined &&
+                value.adversarial !== undefined) {
+                return value;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * A new authorized attempt supersedes any earlier PASS for this source: the
+ * task's own record, and the bare one when it is this task's (or no task's).
+ * Another task's bare record from before per-task records is left alone.
+ */
+export async function invalidateReviewAttestation(root, sourceFingerprint, taskId) {
+    if (!FINGERPRINT_PATTERN.test(sourceFingerprint) ||
+        (taskId !== undefined && !TASK_ID_PATTERN.test(taskId))) {
+        throw new AgentOpsError("REVIEW_ATTESTATION_INVALID", "Invalid source fingerprint.");
+    }
+    if (taskId !== undefined) {
+        const own = attestationPath(root, sourceFingerprint, taskId);
+        if (await readPrivateFile(own, root) !== null) {
+            await writePrivateFile(own, "null\n", root);
+        }
+    }
+    const bare = attestationPath(root, sourceFingerprint);
+    const source = await readPrivateFile(bare, root);
     if (source === null) {
-        return null;
+        return;
     }
+    let owner;
     try {
-        const value = JSON.parse(source);
-        return value.sourceFingerprint === sourceFingerprint &&
-            value.status === "PASS" &&
-            value.report !== undefined &&
-            value.adversarial !== undefined
-            ? value
-            : null;
+        owner = JSON.parse(source)?.taskId;
     }
     catch {
-        return null;
-    }
-}
-/** A new authorized attempt supersedes any earlier PASS for this source. */
-export async function invalidateReviewAttestation(root, sourceFingerprint) {
-    if (!FINGERPRINT_PATTERN.test(sourceFingerprint)) {
-        throw new AgentOpsError("REVIEW_ATTESTATION_INVALID", "Invalid source fingerprint.");
+        owner = undefined;
     }
-    const path = attestationPath(root, sourceFingerprint);
-    if (await readPrivateFile(path, root) !== null) {
-        await writePrivateFile(path, "null\n", root);
+    if (taskId === undefined || owner === undefined || owner === taskId) {
+        await writePrivateFile(bare, "null\n", root);
     }
 }
 /** Prior findings stay a short checklist, never a second report to digest. */
@@ -328,12 +400,15 @@ export async function findPriorFailingFindings(root, taskId) {
     // ponytail: linear scan of every report; index by task if the directory grows large.
     let latest;
     for (const name of names) {
-        const fingerprint = name.slice(0, -REVIEW_REPORT_ARTIFACT_SUFFIX.length);
-        if (!name.endsWith(REVIEW_REPORT_ARTIFACT_SUFFIX) || !FINGERPRINT_PATTERN.test(fingerprint)) {
+        // `<fingerprint>` or `<fingerprint>.<task id>`, then the suffix.
+        const key = name.slice(0, -REVIEW_REPORT_ARTIFACT_SUFFIX.length);
+        const fingerprint = key.slice(0, 64);
+        if (!name.endsWith(REVIEW_REPORT_ARTIFACT_SUFFIX) || !FINGERPRINT_PATTERN.test(fingerprint) ||
+            (key !== fingerprint && key !== recordKey(fingerprint, taskId))) {
             continue;
         }
         try {
-            const source = await readPrivateFile(artifactPath(root, fingerprint), root);
+            const source = await readPrivateFile(join(directory, name), root);
             if (source === null) {
                 continue;
             }