@kylecheng3146/agent-ops 0.2.8 → 0.3.1

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

@@ -0,0 +1,281 @@
+import { chmod, copyFile, lstat, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { basename, dirname, join, sep } from "node:path";
+import { calculateConfigHash } from "../config/hash.js";
+import { parseInstallManifest } from "../fs/manifest.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { writeSessionMarker } from "../hooks/codex-loop.js";
+import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+/**
+ * One Git worktree per writing session, so parallel sessions stop sharing the
+ * change surface every fingerprint is taken over. Worktrees live inside the
+ * main checkout, kept out of its surface by `.git/info/exclude` — never by
+ * `.gitignore`, whose edit would itself be a change the gate has to explain.
+ */
+export const WORKTREE_DIRECTORY = ".worktrees";
+export const WORKTREE_BRANCH_PREFIX = "agent-ops/";
+export const WORKTREE_RECORD_PATH = ".agent-ops/tasks/worktree.json";
+const EXCLUDE_LINE = `/${WORKTREE_DIRECTORY}/`;
+const NAME = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/u;
+const SESSION = /^[^\0\r\n]{1,256}$/u;
+const DEFAULT_SETUP_TIMEOUT_MS = 10 * 60 * 1000;
+function worktreeError(code, message) {
+    return new AgentOpsError(code, message);
+}
+async function git(deps, cwd, args, code, message) {
+    const result = await deps.git(cwd, args);
+    if (result.exitCode !== 0) {
+        const detail = result.stderr.trim().split("\n")[0];
+        throw worktreeError(code, detail === undefined || detail === "" ? message : `${message} ${detail}`);
+    }
+    return result.stdout.trim();
+}
+export function assertWorktreeName(name) {
+    if (name === undefined || !NAME.test(name) || name.includes("..")) {
+        throw worktreeError("WORKTREE_NAME_INVALID", "A worktree name is 1-64 lowercase letters, digits, '.', '_' or '-', starting and ending with a letter or digit.");
+    }
+    return name;
+}
+export function assertSessionId(sessionId) {
+    if (sessionId === undefined || !SESSION.test(sessionId)) {
+        throw worktreeError("WORKTREE_SESSION_REQUIRED", "Pass --session <id>: the conversation that will work in this worktree.");
+    }
+    return sessionId;
+}
+/**
+ * The main checkout and the checkout `cwd` is in. They differ inside a linked
+ * worktree. A repository whose common directory is not `<root>/.git` (bare,
+ * or a separate git dir) has no main checkout to put worktrees in.
+ */
+export async function resolveCheckouts(deps, cwd) {
+    const commonDir = await realpath(await git(deps, cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"], "WORKTREE_NOT_GIT", "Worktrees require a Git repository."));
+    const currentRoot = await realpath(await git(deps, cwd, ["rev-parse", "--show-toplevel"], "WORKTREE_NOT_GIT", "Worktrees require a Git checkout."));
+    if (basename(commonDir) !== ".git") {
+        throw worktreeError("WORKTREE_LAYOUT_UNSUPPORTED", "Worktrees need a main checkout whose Git directory is <root>/.git.");
+    }
+    return { mainRoot: dirname(commonDir), currentRoot, commonDir };
+}
+export function worktreePath(mainRoot, name) {
+    return join(mainRoot, WORKTREE_DIRECTORY, name);
+}
+/** True when `path` is inside `<mainRoot>/.worktrees/`. */
+export function insideWorktreeDirectory(mainRoot, path) {
+    return path.startsWith(`${join(mainRoot, WORKTREE_DIRECTORY)}${sep}`);
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureExcluded(deps, mainRoot, commonDir) {
+    const probe = await deps.git(mainRoot, ["check-ignore", "-q", "--no-index", `${WORKTREE_DIRECTORY}/probe`]);
+    if (probe.exitCode === 0)
+        return;
+    const path = join(commonDir, "info", "exclude");
+    let current = "";
+    try {
+        current = await readFile(path, "utf8");
+    }
+    catch {
+        await mkdir(dirname(path), { recursive: true });
+    }
+    if (current.split(/\r?\n/u).includes(EXCLUDE_LINE))
+        return;
+    const separator = current.length === 0 || current.endsWith("\n") ? "" : "\n";
+    await writeFile(path, `${current}${separator}${EXCLUDE_LINE}\n`);
+}
+function portableRelative(path) {
+    return path.length > 0 && !path.startsWith("/") && !path.startsWith("~") &&
+        !path.includes("\\") && !path.includes("\0") &&
+        path.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+/**
+ * Files Git does not carry into a new worktree but the session needs there:
+ * what agent-ops installed (rules, hooks, its own config) and whatever
+ * `.worktreeinclude` names (gitignore syntax: `.env`, `local.properties`).
+ * Only files missing from the new checkout are copied, so a tracked file
+ * always keeps the branch's version.
+ */
+async function carriedFiles(deps, mainRoot) {
+    // The config is what makes the new checkout an agent-ops checkout at all:
+    // carried even when no manifest lists it.
+    const paths = new Set([".agent-ops/config.json"]);
+    const manifestSource = await readFile(join(mainRoot, ".agent-ops", "manifest.json"), "utf8").catch(() => null);
+    if (manifestSource !== null) {
+        paths.add(".agent-ops/manifest.json");
+        try {
+            const manifest = parseInstallManifest(manifestSource);
+            for (const { path } of [...manifest.artifacts, ...manifest.markers, ...(manifest.hooks ?? [])]) {
+                paths.add(path);
+            }
+        }
+        catch {
+            // An unreadable manifest still leaves the manifest itself to copy.
+        }
+    }
+    if (await exists(join(mainRoot, ".worktreeinclude"))) {
+        const listed = await git(deps, mainRoot, ["ls-files", "-z", "--others", "--ignored", "--exclude-from=.worktreeinclude"], "WORKTREE_INCLUDE_INVALID", ".worktreeinclude could not be read.");
+        for (const path of listed.split("\0"))
+            paths.add(path);
+    }
+    return [...paths].filter((path) => portableRelative(path) &&
+        !path.startsWith(`${WORKTREE_DIRECTORY}/`) &&
+        !path.startsWith(".agent-ops/tasks/") &&
+        !path.startsWith(".agent-ops/reviews/")).sort();
+}
+async function copyMissing(mainRoot, target, paths) {
+    const copied = [];
+    for (const path of paths) {
+        const source = join(mainRoot, ...path.split("/"));
+        const destination = join(target, ...path.split("/"));
+        let entry;
+        try {
+            entry = await lstat(source);
+        }
+        catch {
+            continue;
+        }
+        if (!entry.isFile() || await exists(destination))
+            continue;
+        await mkdir(dirname(destination), { recursive: true });
+        await copyFile(source, destination);
+        await chmod(destination, entry.mode & 0o777);
+        copied.push(path);
+    }
+    return copied;
+}
+export async function readWorktreeRecord(root) {
+    const source = await readPrivateFile(join(root, ...WORKTREE_RECORD_PATH.split("/")), root).catch(() => null);
+    if (source === null)
+        return null;
+    try {
+        const value = JSON.parse(source);
+        return value.schemaVersion === 1 && typeof value.name === "string" &&
+            typeof value.branch === "string" && typeof value.path === "string" &&
+            typeof value.mainRoot === "string" && typeof value.targetBranch === "string" &&
+            typeof value.base === "string" && typeof value.sessionId === "string" &&
+            typeof value.createdAt === "string"
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeWorktreeRecord(record) {
+    await writePrivateFile(join(record.path, ...WORKTREE_RECORD_PATH.split("/")), `${JSON.stringify(record, null, 2)}\n`, record.path);
+}
+/** Points the session at the worktree from both sides of the gate. */
+export async function bindSession(deps, record, mainConfig, baselineFingerprint) {
+    for (const harness of ["claude", "codex"]) {
+        if (await exists(join(record.mainRoot, `.${harness}`))) {
+            await writeSessionMarker({ root: record.path, harness, sessionId: record.sessionId });
+        }
+    }
+    if (!mainConfig.features.completionGate.enabled)
+        return;
+    const worktreeConfig = await deps.loadConfig(record.path);
+    await (await deps.gate(record.path, worktreeConfig)).seed(record.sessionId, baselineFingerprint);
+    await (await deps.gate(record.mainRoot, mainConfig)).redirect(record.sessionId, record.path);
+}
+export async function removeCheckout(deps, record, force) {
+    await git(deps, record.mainRoot, ["worktree", "remove", ...(force ? ["--force"] : []), record.path], "WORKTREE_REMOVE_FAILED", `Git could not remove ${record.path}.`);
+    await git(deps, record.mainRoot, ["branch", force ? "-D" : "-d", record.branch], "WORKTREE_REMOVE_FAILED", `Git could not delete ${record.branch}.`);
+}
+/**
+ * Creates `.worktrees/<name>` on `agent-ops/<name>` from the main checkout's
+ * HEAD and makes it a working agent-ops checkout for `sessionId`.
+ */
+export async function addWorktree(deps, options) {
+    const name = assertWorktreeName(options.name);
+    const sessionId = assertSessionId(options.sessionId);
+    const { mainRoot, currentRoot, commonDir } = await resolveCheckouts(deps, options.cwd);
+    if (currentRoot !== mainRoot) {
+        throw worktreeError("WORKTREE_NESTED", `Run worktree commands from the main checkout (${mainRoot}), not from inside a worktree.`);
+    }
+    const targetBranch = await git(deps, mainRoot, ["symbolic-ref", "--short", "-q", "HEAD"], "WORKTREE_DETACHED_HEAD", "The main checkout must be on a branch to merge back into.");
+    const base = await git(deps, mainRoot, ["rev-parse", "--verify", "HEAD^{commit}"], "WORKTREE_NO_COMMIT", "The main checkout has no commit to branch from.");
+    const path = worktreePath(mainRoot, name);
+    const branch = `${WORKTREE_BRANCH_PREFIX}${name}`;
+    if (await exists(path)) {
+        throw worktreeError("WORKTREE_EXISTS", `${path} already exists; pick another name or resume it.`);
+    }
+    if ((await deps.git(mainRoot, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`])).exitCode === 0) {
+        throw worktreeError("WORKTREE_EXISTS", `Branch ${branch} already exists; pick another name.`);
+    }
+    const mainConfig = await deps.loadConfig(mainRoot);
+    const mainTrust = await deps.trust.status(mainRoot, mainConfig);
+    const setupSteps = mainConfig.worktree?.setup ?? [];
+    if (setupSteps.length > 0 && mainTrust !== "TRUSTED") {
+        throw worktreeError("WORKTREE_SETUP_UNTRUSTED", "worktree.setup runs repository commands; run agent-ops trust grant in the main checkout first.");
+    }
+    await ensureExcluded(deps, mainRoot, commonDir);
+    await git(deps, mainRoot, ["worktree", "add", "-b", branch, path, base], "WORKTREE_ADD_FAILED", "Git could not create the worktree.");
+    const record = {
+        schemaVersion: 1,
+        name,
+        branch,
+        path: await realpath(path),
+        mainRoot,
+        targetBranch,
+        base,
+        sessionId,
+        createdAt: deps.now?.() ?? new Date().toISOString()
+    };
+    let trusted = false;
+    try {
+        const copied = await copyMissing(mainRoot, record.path, await carriedFiles(deps, mainRoot));
+        const worktreeConfig = await deps.loadConfig(record.path);
+        // The same commands the user already trusted, and nothing else: any
+        // difference in config leaves the new checkout untrusted.
+        if (mainTrust === "TRUSTED" && calculateConfigHash(worktreeConfig) === calculateConfigHash(mainConfig)) {
+            await deps.trust.grant(record.path, worktreeConfig);
+            trusted = true;
+        }
+        const setup = [];
+        for (const step of setupSteps) {
+            const result = await deps.runSetup(record.path, {
+                ...step,
+                timeoutMs: step.timeoutMs ?? DEFAULT_SETUP_TIMEOUT_MS
+            });
+            const label = [step.command, ...step.args].join(" ");
+            if (result.exitCode !== 0) {
+                throw worktreeError("WORKTREE_SETUP_FAILED", `Setup step failed (${label}, exit ${String(result.exitCode)}); the worktree was removed. ${result.output.trim().split("\n").slice(-5).join("\n")}`.trim());
+            }
+            setup.push(label);
+        }
+        await writeWorktreeRecord(record);
+        await bindSession(deps, record, mainConfig);
+        return { record, copied, trusted, setup };
+    }
+    catch (error) {
+        if (mainConfig.features.completionGate.enabled) {
+            await (await deps.gate(mainRoot, mainConfig)).redirect(sessionId, null).catch(() => undefined);
+        }
+        if (trusted)
+            await deps.trust.revoke(record.path, mainConfig).catch(() => undefined);
+        await removeCheckout(deps, record, true).catch(() => undefined);
+        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;
             }

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

@@ -28,6 +28,17 @@ export const DEFAULT_REVIEW_TIMEOUT_MS = 900_000;
  * thinking hard is never cut off.
  */
 export const DEFAULT_STALL_IDLE_MS = 90_000;
+/**
+ * agy writes nothing to stdout, stderr or its log while one generation
+ * streams, so a long think is indistinguishable from a wedge. Its own logs
+ * show normal generations silent for up to ~177s; 90s cut real reviews off.
+ */
+export const AGY_STALL_IDLE_MS = 240_000;
+/**
+ * A call the service dropped before answering. It produced no verdict, so
+ * one fresh retry is not review shopping.
+ */
+const TRANSIENT_NETWORK = /\b(?:network issue|503|service is currently unavailable|ECONNRESET|ETIMEDOUT|socket hang up)\b/iu;
 /** Two rounds at the per-target default: the previous worst case, now bounded. */
 export const DEFAULT_REVIEW_CHAIN_TIMEOUT_MS = 2 * DEFAULT_REVIEW_TIMEOUT_MS;
 /**
@@ -425,7 +436,8 @@ async function attemptTarget(request, options) {
         }
         throwIfInterrupted(target, options);
         options.onProgress?.(`${target}: review started (timeout: ${Math.ceil((options.timeoutMs ?? DEFAULT_REVIEW_TIMEOUT_MS) / 1_000)}s)`);
-        const stallIdleMs = options.stallIdleMs ?? DEFAULT_STALL_IDLE_MS;
+        const stallIdleMs = options.stallIdleMs ??
+            (target === "agy" ? AGY_STALL_IDLE_MS : DEFAULT_STALL_IDLE_MS);
         const stallWatch = watchForStall(heartbeatLog, options.signal, stallIdleMs);
         let spawned;
         try {
@@ -481,8 +493,11 @@ async function attemptTarget(request, options) {
         }
         if (spawned.failureClass === "nonzero-exit") {
             const output = `${spawned.stderr}\n${spawned.stdout}`;
-            return skip(rejectedCallReason(output), firstComplaint(spawned.stderr, spawned.stdout) ??
-                `the call was rejected with exit ${spawned.exitCode ?? "unknown"} and no output`);
+            return {
+                ...skip(rejectedCallReason(output), firstComplaint(spawned.stderr, spawned.stdout) ??
+                    `the call was rejected with exit ${spawned.exitCode ?? "unknown"} and no output`),
+                ...(TRANSIENT_NETWORK.test(output) ? { transient: true } : {})
+            };
         }
         if (spawned.failureClass === "signal-exit") {
             return skip("capability-unavailable", `the reviewer exited after ${spawned.signal ?? "an unknown signal"}`);
@@ -522,6 +537,18 @@ async function attemptTarget(request, options) {
         await rm(attemptDirectory, { recursive: true, force: true });
     }
 }
+/**
+ * `attemptTarget`, retried once in a fresh session when the service dropped
+ * the call. Only once: a service that is down stays down.
+ */
+async function attemptTargetWithRetry(request, options) {
+    const first = await attemptTarget(request, options);
+    if (first.kind !== "skip" || first.transient !== true || budgetSpent(options)) {
+        return first;
+    }
+    options.onProgress?.(`${request.target}: ${first.diagnostic} → retrying once`);
+    return attemptTarget(request, options);
+}
 /** Builds the `execute` callback with one necessary and one adversarial review. */
 export function createReviewExecutor(options) {
     const report = options.onProgress ?? (() => { });
@@ -630,7 +657,7 @@ export function createReviewExecutor(options) {
             report("chain: review deadline reached before the first round");
             return { status: "NOT_RUN", reason: "timeout", attempts: [] };
         }
-        const primaryOutcome = await attemptTarget({
+        const primaryOutcome = await attemptTargetWithRetry({
             ...shared,
             target: primaryTarget,
             label: `${primaryTarget}-primary`,
@@ -739,7 +766,7 @@ export function createReviewExecutor(options) {
             };
         }
         // The second round draws on what is left, never a fresh full budget.
-        const adversarialOutcome = await attemptTarget({
+        const adversarialOutcome = await attemptTargetWithRetry({
             ...shared,
             target: adversarialTarget,
             label: `${adversarialTarget}-adversarial`,

package/dist/runtime/src/schema/validate.js

@@ -300,7 +300,8 @@ export function validateConfig(value) {
         "reviewRoles",
         "schemaVersion",
         "securityExceptions",
-        "verification"
+        "verification",
+        "worktree"
     ], CONFIG_SCHEMA_VERSION);
     if (isFailure(root)) {
         return root;
@@ -411,8 +412,56 @@ export function validateConfig(value) {
             roles.add(role.value.role);
         }
     }
+    if (root.worktree !== undefined) {
+        const worktree = validateWorktree(root.worktree, "$.worktree");
+        if (!worktree.ok) {
+            return worktree;
+        }
+    }
     return success(root);
 }
+function validateWorktree(value, path) {
+    if (!isRecord(value)) {
+        return failure("INVALID_TYPE", path, "worktree must be an object.");
+    }
+    const unknown = unknownFieldFailure(value, ["mode", "setup"], path);
+    if (unknown !== undefined) {
+        return unknown;
+    }
+    if (value.mode !== "auto" && value.mode !== "off") {
+        return failure("INVALID_WORKTREE_MODE", `${path}.mode`, `Unsupported worktree mode: ${String(value.mode)}`);
+    }
+    if (value.setup === undefined) {
+        return success(value);
+    }
+    if (!Array.isArray(value.setup)) {
+        return failure("INVALID_TYPE", `${path}.setup`, "setup must be an array.");
+    }
+    for (const [index, step] of value.setup.entries()) {
+        const stepPath = `${path}.setup[${index}]`;
+        if (!isRecord(step)) {
+            return failure("INVALID_TYPE", stepPath, "Expected a setup command object.");
+        }
+        const stepUnknown = unknownFieldFailure(step, ["args", "command", "timeoutMs"], stepPath);
+        if (stepUnknown !== undefined) {
+            return stepUnknown;
+        }
+        if (!isNonEmptyString(step.command)) {
+            return failure("INVALID_COMMAND", `${stepPath}.command`, "command must be a non-empty string.");
+        }
+        if (!isStringArray(step.args) ||
+            step.args.some((argument) => argument.includes("\0"))) {
+            return failure("INVALID_ARGS", `${stepPath}.args`, "args must be an array of strings.");
+        }
+        if (step.timeoutMs !== undefined &&
+            (!Number.isSafeInteger(step.timeoutMs) ||
+                step.timeoutMs <= 0 ||
+                step.timeoutMs > MAX_TIMEOUT_MS)) {
+            return failure("INVALID_TIMEOUT", `${stepPath}.timeoutMs`, "timeoutMs must be a positive integer.");
+        }
+    }
+    return success(value);
+}
 function validateReviewRole(value, path) {
     if (!isRecord(value)) {
         return failure("INVALID_TYPE", path, "Expected a review role object.");