@webpresso/agent-kit 3.1.28 → 3.2.0

package/dist/esm/cli/commands/review.js

@@ -7,19 +7,26 @@ import { z } from "zod";
 import { MAX_PORTABLE_REPOSITORY_PATH_LENGTH } from "#audit/absolute-path-policy.js";
 import { getProjectRoot } from "#cli/utils";
 import { relativeBlueprintSlug, resolveBlueprintFile } from "#lifecycle/local.js";
+import { readBlueprintOverviewAtRef } from "#lifecycle/review-provenance.js";
 import { scanBlueprintDirectory } from "#service/scanner.js";
 import { resolveBlueprintRoot } from "#utils/blueprint-root.js";
+import { assertFolderBlueprintIdentity } from "#utils/document-paths.js";
 import { CLAUDE_DEFAULT_REVIEW_MODEL, CODEX_DEFAULT_REVIEW_MODEL, GROK_DEFAULT_REVIEW_MODEL, DEFAULT_REVIEW_MAX_PROGRESS_EVENTS, runReviewExecution, } from "#review/execution/index.js";
 import { REVIEW_OUTPUT_MAX_BYTES, REVIEW_OUTPUT_TOO_LARGE, applyReviewOutputPolicy, } from "#review/execution/output-policy.js";
 import { removeOwnedRunningReviewState } from "#review/execution/artifacts.js";
 import { createReviewTargetCheckout, } from "#review/execution/review-checkout.js";
 import { loadReviewProcessRecords, readReviewProcessIdentity, removeReviewProcessRecord, } from "#review/execution/process-registry.js";
-import { isProviderSuppressed, loadReviewAvailability, pruneExpiredAvailabilitySuppressions, recordReviewAvailability, recordReviewAvailabilityWithLock, reviewAvailabilityPath, saveReviewAvailability, suppressedReviewers, } from "#review/availability.js";
+import { isProviderSuppressed, loadOpencodeAccountAvailability, loadReviewAvailability, pruneExpiredAvailabilitySuppressions, pruneExpiredOpencodeAccountSuppressions, recordOpencodeAccountAvailabilityWithLock, recordReviewAvailability, recordReviewAvailabilityWithLock, reviewAvailabilityPath, saveReviewAvailability, suppressedReviewers, } from "#review/availability.js";
+import { opencodeAccountCanonicalId, opencodeAccountDataDir, selectActiveOpencodeAccount, } from "#review/opencode-account.js";
+import { materializeOpencodeGoAuth } from "#review/opencode-auth.js";
+import { resolveOpencodeAccountsGracefully } from "#runtime/opencode-account-materializer.js";
+import { resolveAgentSecretProfile } from "#cli/commands/agent-launch.js";
 import { evaluateApprovalGate, evaluateApprovalReviewers, formatApprovalGateRequirement, } from "#lifecycle/audit";
 import { assertReviewRefUnchanged, readReviewAuthorityAtRef, readWorkingReviewEvents, } from "#review/authority.js";
-import { appendReviewEvent, evaluateReviewEvents } from "#review/events.js";
+import { appendReviewEvent, evaluateReviewEvents, MAINTAINER_OVERRIDE_REVIEWER, parseReviewEventLog, } from "#review/events.js";
 import { isPolicyApprovalVerdict } from "#review/verdict.js";
-import { createDeliverySubjectAtRef, createPlanSubjectAtRef, } from "#review/subject.js";
+import { verificationArtifactSection, verificationPromptSummary, verifyDeliveryPromotionGates, } from "#review/delivery-verifier.js";
+import { createDeliverySubjectAtRef, createPlanSubjectAtRef, findUnreviewedWorkingTreeChanges, } from "#review/subject.js";
 import { runCommand } from "#mcp/tools/_shared/run-command.js";
 import { NotInGitRepoError, withLock } from "#paths/state-root.js";
 import { writeFileAtomic, writeJsonFileAtomic } from "#shared-utils/write-json-file.js";
@@ -148,6 +155,18 @@ function defaultReviewModel(provider) {
         return GROK_DEFAULT_REVIEW_MODEL;
     return undefined;
 }
+/**
+ * Claude's CLI accepts `fable` as its moving alias and `claude-fable-N` as a
+ * versioned identifier. Accept the common human shorthand `fableN` too, so a
+ * request for a specific Fable generation is never forwarded as an invalid
+ * provider model id.
+ */
+function resolveReviewModel(provider, model) {
+    if (provider !== "claude")
+        return model;
+    const fableVersion = /^fable[-\s]?(\d+)$/iu.exec(model)?.[1];
+    return fableVersion ? `claude-fable-${fableVersion}` : model;
+}
 function classificationForFailureCode(code) {
     if (!code)
         return undefined;
@@ -188,9 +207,10 @@ export async function runReviewRunCommand(projectRoot, options, deps = {}) {
     if (!options.artifactRoot)
         throw new Error("Missing required --artifact-root.");
     const provider = parseReviewProvider(options.provider);
-    const model = options.model?.trim() || defaultReviewModel(provider);
-    if (!model)
+    const requestedModel = options.model?.trim() || defaultReviewModel(provider);
+    if (!requestedModel)
         throw new Error(`Missing required --model for ${provider}.`);
+    const model = resolveReviewModel(provider, requestedModel);
     const effort = parseReviewEffort(options.effort);
     const stage = parseReviewStage(options.stage);
     const idleSeconds = options.idleSeconds === undefined ? 180 : Number(options.idleSeconds);
@@ -353,6 +373,13 @@ function reviewsPathForBlueprint(blueprintPath) {
     }
     return path.join(path.dirname(blueprintPath), "reviews.md");
 }
+function assertReviewEvidenceCapable(location) {
+    assertFolderBlueprintIdentity({
+        documentPath: location.path,
+        lifecycleSlug: location.slug,
+        shape: location.shape,
+    });
+}
 function parseLegacyTableEntries(markdown, blueprintSlug, blueprintPath, reviewsPath) {
     const entries = [];
     for (const line of markdown.split("\n")) {
@@ -687,6 +714,7 @@ async function resolveReviewBlueprint(projectRoot, slug) {
 }
 export async function logReviewEntry(projectRoot, slug, input) {
     const location = await resolveReviewBlueprint(projectRoot, slug);
+    assertReviewEvidenceCapable(location);
     const reviewsPath = reviewsPathForBlueprint(location.path);
     const timestamp = new Date().toISOString();
     const reviewer = parseReviewerId(input.reviewer);
@@ -748,6 +776,7 @@ export async function logReviewEntry(projectRoot, slug, input) {
 }
 export async function logReviewEvent(projectRoot, slug, input) {
     const location = await resolveReviewBlueprint(projectRoot, slug);
+    assertReviewEvidenceCapable(location);
     const stableSlug = relativeBlueprintSlug(location.slug);
     const purpose = normalizeReviewPurpose(input.purpose);
     const targetSha = resolveImmutableSha(projectRoot, input.target);
@@ -809,6 +838,127 @@ export async function logReviewEvent(projectRoot, slug, input) {
     updateReviewCache(projectRoot, scanAllReviewLedgers(projectRoot));
     return event;
 }
+function renderMaintainerOverrideArtifact(input) {
+    return [
+        `# Maintainer override — ${input.blueprintSlug} (${input.purpose})`,
+        "",
+        "A maintainer has adjudicated this subject after a formal Claude/Codex/Grok/OpenCode-Go",
+        "reviewer rejected it and the blocking finding cannot be remediated (a physical or",
+        "maximalist residual). This override satisfies the promotion approval gate DISTINCTLY;",
+        "it is never counted as a strong-reviewer or OpenCode-Go approval.",
+        "",
+        `- Subject scheme: ${input.subjectScheme}`,
+        `- Subject digest: ${input.subjectDigest}`,
+        `- Reviewed commit: ${input.reviewedCommit}`,
+        `- Overridden rejection artifact: ${input.rejectionArtifactPath}`,
+        `- Recorded: ${input.timestamp}`,
+        "",
+        "## Maintainer reason",
+        "",
+        input.reason,
+        "",
+    ].join("\n");
+}
+/**
+ * `wp review override` — the gated, auditable human escape hatch for the
+ * promotion approval gate. It records a `maintainer-override` approval that
+ * satisfies the gate distinctly (never as a strong/OpenCode-Go approval).
+ *
+ * Trust properties:
+ * - REFUSES unless a formal strong-reviewer gate has already REJECTED the exact
+ *   current subject (precondition + target binding are the same lookup).
+ * - Requires an explicit `--reason` and `--confirm` — no accidental invocation.
+ * - Reviewer id `maintainer-override` is not in the `wp review log` reviewer
+ *   enum, so neither `wp review log` nor `wp_blueprint_review_log` can mint it;
+ *   this command is the only writer. The read-time policy in
+ *   `#review/events` treats it as human-like, so its manual-stage record is a
+ *   legitimate governance approval rather than a disguised machine approval.
+ */
+export async function runReviewOverride(projectRoot, slug, input) {
+    const location = await resolveReviewBlueprint(projectRoot, slug);
+    assertReviewEvidenceCapable(location);
+    if (lstatSync(location.path).isSymbolicLink()) {
+        throw new Error(`Blueprint overview must not be a symlink: ${location.path}`);
+    }
+    const reason = normalizeOptionalText(input.reason);
+    if (!reason) {
+        throw new Error("Missing required --reason for `review override`: a maintainer adjudication must state why an automated reviewer cannot converge.");
+    }
+    if (input.confirm !== true) {
+        throw new Error("`review override` requires explicit --confirm: it mints a promotion-gate-satisfying human adjudication that bypasses the strong-reviewer gate.");
+    }
+    const stableSlug = relativeBlueprintSlug(location.slug);
+    const purpose = normalizeReviewPurpose(input.purpose);
+    const targetSha = resolveImmutableSha(projectRoot, input.target);
+    const repositoryBlueprintPath = blueprintPathAtGitRoot(projectRoot, location.path);
+    const subject = purpose === "plan"
+        ? createPlanSubjectAtRef(projectRoot, targetSha, stableSlug, repositoryBlueprintPath)
+        : createDeliverySubjectAtRef(projectRoot, targetSha, stableSlug, repositoryBlueprintPath);
+    const ledgerPath = path.join(path.dirname(location.path), "review-events.jsonl");
+    const events = existsSync(ledgerPath)
+        ? parseReviewEventLog(readFileSync(ledgerPath, "utf8"))
+        : [];
+    // Precondition AND target binding in one lookup: the override is valid only
+    // when a formal strong-reviewer gate REJECTED the exact current subject. This
+    // refuses overriding content that was never properly reviewed, and refuses a
+    // stale rejection of content that has since changed.
+    const rejection = rejectedReviewSubjects({
+        events,
+        projectRoot,
+        purpose,
+        stableSlug,
+    }).find((entry) => entry.subjectDigest === subject.digest);
+    if (!rejection) {
+        throw new Error(`Refusing to record a maintainer override: no formal Claude/Codex/Grok/OpenCode-Go rejection exists for the current ${purpose} subject (${subject.digest.slice(0, 12)}) of ${stableSlug}. A maintainer override is only valid after a strong reviewer has rejected the exact content under review.`);
+    }
+    const timestamp = new Date().toISOString();
+    const artifactSuffix = timestamp.replace(/[^0-9]/gu, "").slice(0, 14);
+    const artifactPath = `review-artifacts/maintainer-override-${subject.digest.slice(0, 12)}-${artifactSuffix}.md`;
+    const artifactAbsolute = safeArtifactPath(location.path, artifactPath);
+    const artifactContent = Buffer.from(renderMaintainerOverrideArtifact({
+        blueprintSlug: stableSlug,
+        purpose,
+        subjectScheme: subject.scheme,
+        subjectDigest: subject.digest,
+        reviewedCommit: targetSha,
+        rejectionArtifactPath: rejection.artifactPath,
+        reason,
+        timestamp,
+    }), "utf8");
+    const event = {
+        schemaVersion: 2,
+        // The timestamp keeps the id unique across re-invocations. Re-running the
+        // override for the same subject therefore appends a second approve event
+        // rather than being idempotent; that is harmless (each is gated by the same
+        // real rejection, and evaluateReviewEvents keeps the latest per reviewer)
+        // and avoids a same-id/different-timestamp collision in appendReviewEvent.
+        id: `${purpose}:maintainer-override:${subject.digest}:${timestamp}`,
+        purpose,
+        blueprintSlug: stableSlug,
+        subjectScheme: subject.scheme,
+        subjectDigest: subject.digest,
+        reviewedCommit: targetSha,
+        gateId: "manual",
+        promptHash: createHash("sha256")
+            .update(`maintainer-override\0${purpose}\0${subject.scheme}\0${subject.digest}`)
+            .digest("hex"),
+        reviewer: MAINTAINER_OVERRIDE_REVIEWER,
+        // No `provider`: a maintainer override has no AI backend.
+        stage: "manual",
+        status: "complete",
+        verdict: "approve",
+        timestamp,
+        artifactPath,
+        artifactSha256: createHash("sha256").update(artifactContent).digest("hex"),
+    };
+    appendReviewEvent({
+        ledgerPath,
+        event,
+        artifact: { path: artifactAbsolute, content: artifactContent },
+    });
+    updateReviewCache(projectRoot, scanAllReviewLedgers(projectRoot));
+    return event;
+}
 function resolveImmutableSha(projectRoot, target) {
     let resolved;
     try {
@@ -860,14 +1010,10 @@ function readBlueprintAtTarget(projectRoot, blueprintPath, targetSha) {
         throw new Error(`Blueprint path is outside Git toplevel: ${blueprintPath}`);
     }
     const relative = gitRelativePath.replace(/\\/gu, "/");
-    try {
-        return runBoundedReviewGit(gitRoot, ["show", `${targetSha}:${relative}`]);
-    }
-    catch (error) {
-        throw new Error(`Blueprint ${relative} is not tracked at target ${targetSha}.`, {
-            cause: error,
-        });
-    }
+    const content = readBlueprintOverviewAtRef(gitRoot, targetSha, absoluteBlueprintPath);
+    if (content)
+        return content.toString("utf8");
+    throw new Error(`Blueprint ${relative} is not tracked at target ${targetSha}.`);
 }
 function blueprintPathAtGitRoot(projectRoot, blueprintPath) {
     const gitRoot = resolveReviewGitToplevel(projectRoot);
@@ -949,8 +1095,15 @@ function dedupeGateAttempts(attempts) {
     return result;
 }
 function gateAttemptFromEvent(event) {
+    // Only real gate events reach here (callers filter by the content-hash gateId
+    // + promptHash); those always carry a provider. A `provider`-less event (e.g.
+    // a maintainer override) is a caller bug — fail loudly rather than fabricate.
+    const provider = event.provider;
+    if (!provider) {
+        throw new Error(`Gate attempt event ${event.id} is missing a provider.`);
+    }
     return {
-        provider: event.provider,
+        provider,
         ...(event.model ? { model: event.model } : {}),
         ...(event.effort ? { effort: event.effort } : {}),
         reviewer: event.reviewer,
@@ -1002,6 +1155,19 @@ const reviewGateAttemptSchema = z.object({
     retryAfterMs: z.number().optional(),
     artifact: z.string().optional(),
 });
+const reviewGateVerificationCommandSchema = z.object({
+    command: z.string(),
+    outcome: z.enum(["passed", "failed", "timed-out"]),
+    durationMs: z.number(),
+    exitCode: z.number().nullable(),
+    signal: z.string().optional(),
+});
+const reviewGateVerificationSchema = z.object({
+    status: z.enum(["passed", "failed"]),
+    commands: z.array(reviewGateVerificationCommandSchema),
+    failureCode: z.string().optional(),
+    logPath: z.string().optional(),
+});
 const reviewGateStateSchema = z
     .object({
     schemaVersion: z.literal(2),
@@ -1014,10 +1180,18 @@ const reviewGateStateSchema = z
     targetSha: z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u),
     baseSha: z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u),
     promptHash: z.string().length(64),
-    status: z.enum(["approved", "needs-review", "rejected", "recorded-untracked"]),
+    status: z.enum([
+        "approved",
+        "needs-review",
+        "rejected",
+        "scope-exhausted",
+        "recorded-untracked",
+        "verification-failed",
+    ]),
     approvalGate: z.object({
         distinct: z.number(),
         openCodeGoModelReviewers: z.array(z.string()),
+        overrideReviewers: z.array(z.string()),
         satisfied: z.boolean(),
         strongReviewers: z.array(z.string()),
     }),
@@ -1039,6 +1213,7 @@ const reviewGateStateSchema = z
     // Optional so resuming a gate state persisted before issue tracking existed
     // still validates under .strict().
     issues: z.array(z.string()).optional(),
+    verification: reviewGateVerificationSchema.optional(),
     message: z.string(),
 })
     .strict();
@@ -1080,6 +1255,16 @@ function buildGatePrompt(input) {
         `Review purpose: ${input.purpose}`,
         `Reviewed content subject: ${input.subject.scheme}:${input.subject.digest}`,
         `Immutable target SHA: ${input.targetSha}`,
+        ...(input.verificationSummary ? ["", input.verificationSummary, ""] : []),
+        ...(input.priorRejections && input.priorRejections.length > 0
+            ? [
+                "",
+                "Prior formal rejection evidence (this is the final semantic remediation review):",
+                ...input.priorRejections.map((entry) => `- ${entry.subjectDigest}: ${entry.artifactPath}`),
+                "Inspect every prior finding and its disposition. Return all remaining blockers together; do not defer discoverable blockers to another review round.",
+                "",
+            ]
+            : []),
         "Inspect the target SHA and blueprint directly. Focus on correctness, security, concurrency, recovery, tests, and scope compliance.",
         "End with exactly one standalone verdict line: APPROVED, APPROVE-WITH-NITS, or BLOCKED.",
         "APPROVE-WITH-NITS satisfies the gate only when every finding is non-blocking.",
@@ -1171,7 +1356,10 @@ function chooseOpenCodeModels(catalog, explicitModel) {
     return selected;
 }
 function isProviderWideOpenCodeGateResult(result) {
-    return result.reviewer === "opencode" || result.failureCode === "opencode-go-usage-limit";
+    // A per-account usage limit (failureCode "opencode-go-usage-limit") is NO
+    // LONGER provider-wide — the gate fails over to the next account first. Only a
+    // systemic opencode failure (the family-agnostic "opencode" reviewer) is.
+    return result.reviewer === "opencode";
 }
 function contaminatedReviewResult(result, changes) {
     return {
@@ -1229,12 +1417,18 @@ function gateFailureFromSummary(summary) {
         verdict: "no-verdict",
         terminalClassification,
         ...(summary.failureCode ? { failureCode: summary.failureCode } : {}),
+        ...(summary.providerErrorDetail ? { providerErrorDetail: summary.providerErrorDetail } : {}),
         ...(summary.limitWindow ? { limitWindow: summary.limitWindow } : {}),
         ...(summary.retryAfterMs === undefined ? {} : { retryAfterMs: summary.retryAfterMs }),
     };
 }
-export async function invokeProvider(input, executeReview = runReviewExecution, runCatalogCommand = runCommand, createTargetCheckout = createReviewTargetCheckout, existingCheckout) {
+export async function invokeProvider(input, executeReview = runReviewExecution, runCatalogCommand = runCommand, createTargetCheckout = createReviewTargetCheckout, 
+// A thunk (not a checkout instance) so callers that never reach a real
+// provider attempt — injected fakes included — never pay the checkout's
+// git-archive/tar setup cost.
+getSharedCheckout) {
     let checkout;
+    const existingCheckout = getSharedCheckout?.();
     const ownsCheckout = existingCheckout === undefined;
     try {
         checkout = existingCheckout ?? createTargetCheckout(input.projectRoot, input.targetSha);
@@ -1249,7 +1443,8 @@ export async function invokeProvider(input, executeReview = runReviewExecution,
                 // The attempt already fails closed as an isolation failure.
             }
         }
-        const model = input.model ?? defaultReviewModel(input.provider) ?? "unresolved";
+        const requestedModel = input.model ?? defaultReviewModel(input.provider) ?? "unresolved";
+        const model = resolveReviewModel(input.provider, requestedModel);
         return {
             output: "Unable to create the disposable review checkout; review was not started.",
             model,
@@ -1283,6 +1478,7 @@ async function invokeProviderInCheckout(input, executeReview = runReviewExecutio
         cwd: input.executionCwd,
         registryRoot: input.projectRoot,
         ...(input.signal ? { signal: input.signal } : {}),
+        ...(input.authDataDir ? { authDataDir: input.authDataDir } : {}),
     };
     async function probeProvider(args) {
         const probe = await executeReview({
@@ -1305,7 +1501,7 @@ async function invokeProviderInCheckout(input, executeReview = runReviewExecutio
         };
     }
     if (input.provider === "claude") {
-        const model = input.model ?? defaultReviewModel("claude");
+        const model = resolveReviewModel("claude", input.model ?? defaultReviewModel("claude"));
         const probeFailure = await probeProvider({ provider: "claude", model, reviewer: "claude" });
         if (probeFailure)
             return probeFailure;
@@ -1445,6 +1641,101 @@ async function invokeProviderInCheckout(input, executeReview = runReviewExecutio
             : gateFailureFromSummary(result)),
     };
 }
+/**
+ * Default credential preparer: materialize the account's key into its own
+ * isolated `<stateRoot>/opencode-accounts/<id>/opencode/auth.json` (0600) and
+ * return the `XDG_DATA_HOME` directory. Never mutates the user's global store.
+ */
+function prepareOpencodeCredentialDefault(account) {
+    const dataDir = opencodeAccountDataDir(account.id);
+    materializeOpencodeGoAuth(account.key, { dataDir });
+    return dataDir;
+}
+/**
+ * Multi-account failover for the opencode-go gateway. Resolves Doppler accounts
+ * once, materializes the freshest non-cooled account's isolated auth store, and
+ * rotates to the next account on a per-account usage limit — never touching the
+ * user's global `auth.json`. Degrades to a no-op (undefined `authDataDir`, the
+ * historical global-auth behavior) when no accounts are provisioned.
+ */
+function createOpencodeFailoverController(deps) {
+    // Resolve through the same agent secret profile the launch path uses; without
+    // an environment selector the secret manager falls back to its own ambient,
+    // path-scoped config, which only resolves inside a checkout that happens to
+    // sit under that scope (so account discovery silently finds nothing in a
+    // managed worktree, CI clone, or fresh checkout).
+    const resolution = deps.resolveAccounts({
+        cwd: deps.projectRoot,
+        secretProfile: resolveAgentSecretProfile(),
+    });
+    const accounts = resolution.ok ? resolution.accounts : [];
+    const tried = new Set();
+    let active;
+    let authDataDir;
+    function prepare(account) {
+        try {
+            authDataDir = deps.prepareCredential(account);
+            active = account;
+            tried.add(account.id);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * @param allowCooled Accept the soonest-expiring account when every account is
+     *   already cooled. True for the initial pick (mirrors `wp opencode`: a known
+     *   account beats falling back to whatever the global auth store happens to
+     *   hold); false when rotating after a usage limit, where retrying a capped
+     *   account would only burn an attempt.
+     */
+    function selectNext(allowCooled) {
+        const state = pruneExpiredOpencodeAccountSuppressions(loadOpencodeAccountAvailability()).state;
+        const selection = selectActiveOpencodeAccount(accounts, state);
+        if (!selection || tried.has(selection.account.id))
+            return undefined;
+        if (selection.cooled && !allowCooled)
+            return undefined;
+        return selection.account;
+    }
+    if (accounts.length > 0) {
+        const first = selectNext(true);
+        if (first)
+            prepare(first);
+    }
+    return {
+        authDataDir: () => authDataDir,
+        async onUsageLimit(event) {
+            if (active) {
+                await recordOpencodeAccountAvailabilityWithLock(opencodeAccountCanonicalId(active.id), {
+                    failureCode: "opencode-go-usage-limit",
+                    terminalClassification: "provider-limit-reached",
+                    ...(event.limitWindow ? { limitWindow: event.limitWindow } : {}),
+                    ...(event.retryAfterMs === undefined ? {} : { retryAfterMs: event.retryAfterMs }),
+                });
+            }
+            const next = selectNext(false);
+            if (next && prepare(next))
+                return "retry";
+            // No account left: suppress the opencode PROVIDER (the per-attempt record
+            // is family-scoped and does not) so the gate moves to the next provider.
+            // Sync (unlocked) write — the gate already holds the worktree lock, so
+            // re-locking here would self-deadlock (ELOCKED).
+            recordReviewAvailability(deps.projectRoot, {
+                provider: "opencode",
+                reviewer: "opencode",
+                effort: event.effort,
+                stage: event.stage,
+                terminalClassification: "provider-limit-reached",
+                failureCode: "opencode-go-usage-limit",
+                ...(event.limitWindow ? { limitWindow: event.limitWindow } : {}),
+                ...(event.retryAfterMs === undefined ? {} : { retryAfterMs: event.retryAfterMs }),
+            });
+            return "suppress-provider";
+        },
+    };
+}
 function currentReviewHost(env = process.env) {
     const host = env["WP_REVIEW_HOST"] ?? env["WP_HOOK_HOST"];
     return host === "claude" || host === "codex" || host === "opencode" || host === "grok"
@@ -1527,11 +1818,52 @@ function reviewArtifactRelativePath(input) {
     return path.posix.join(artifactDirectory, filename);
 }
 function reviewGateEventId(input) {
-    return input.stage === "approval-gate"
-        ? input.ordinal === 1
-            ? `gate:${input.gateId}:${input.provider}:${input.model}`
-            : `gate:${input.gateId}:${input.provider}:approval-retry:${input.ordinal}:${input.model}`
-        : `gate:${input.gateId}:${input.provider}:${input.stage}:${input.ordinal}:${input.model}`;
+    if (input.stage !== "approval-gate") {
+        return `gate:${input.gateId}:${input.provider}:${input.stage}:${input.ordinal}:${input.model}`;
+    }
+    return input.ordinal === 1
+        ? `gate:${input.gateId}:${input.provider}:${input.model}`
+        : `gate:${input.gateId}:${input.provider}:approval-retry:${input.ordinal}:${input.model}`;
+}
+function isFormalGateRejection(event) {
+    const provider = event.provider;
+    if (event.status !== "complete" ||
+        event.verdict !== "reject" ||
+        event.stage !== "approval-gate" ||
+        !/^[a-f0-9]{16}$/u.test(event.gateId) ||
+        !provider ||
+        !event.model ||
+        !event.artifactPath) {
+        return false;
+    }
+    return (event.id ===
+        reviewGateEventId({
+            gateId: event.gateId,
+            provider,
+            model: event.model,
+            stage: "approval-gate",
+            ordinal: event.attemptOrdinal ?? 1,
+        }));
+}
+function rejectedReviewSubjects(input) {
+    const bySubject = new Map();
+    for (const event of input.events) {
+        if (event.blueprintSlug !== input.stableSlug ||
+            event.purpose !== input.purpose ||
+            !isFormalGateRejection(event)) {
+            continue;
+        }
+        const canonical = input.purpose === "plan"
+            ? createPlanSubjectAtRef(input.projectRoot, event.reviewedCommit, input.stableSlug)
+            : createDeliverySubjectAtRef(input.projectRoot, event.reviewedCommit, input.stableSlug);
+        if (!bySubject.has(canonical.digest)) {
+            bySubject.set(canonical.digest, {
+                artifactPath: event.artifactPath,
+                subjectDigest: canonical.digest,
+            });
+        }
+    }
+    return [...bySubject.values()];
 }
 /**
  * Sanctioned fallback when `wp review gate` does not reach "approved" — points
@@ -1540,13 +1872,46 @@ function reviewGateEventId(input) {
  * workaround. See catalog/agent/rules/pre-implementation.md.
  */
 export function reviewGateNonConvergenceHint(slug, context = {}) {
+    if (context.status === "scope-exhausted") {
+        return `hint: formal review budget is exhausted for ${slug}. Stop automated review retries and obtain an explicit human scope decision before creating a successor blueprint.`;
+    }
     if (context.failureCode === "provider-event-too-large" && context.gateId) {
         return `hint: provider transport emitted a single provider JSON event above the bounded capture limit for ${slug}; no review verdict was produced. Retry the unchanged gate with "wp review gate ${slug} --resume ${context.gateId} --provider <provider>" and select a different provider when possible. Retrying the same provider/model is allowed for recovery but is likely to recur for deterministic oversized output. An independent "wp review run" can be recorded only as a human-adjudicated verdict through wp_blueprint_review_log; that tool cannot create a Claude/Codex/Grok/OpenCode-Go approval. The event-size and timeout bounds were not increased. See catalog/agent/rules/pre-implementation.md.`;
     }
     return `hint: wp review gate did not satisfy the approval policy for ${slug}. Retry interrupted or structural failures with --resume${context.gateId ? ` ${context.gateId}` : " <gate-id>"} and optionally switch --provider. For a separate review, wp_blueprint_review_log can record only a human-adjudicated approval; it cannot create a Claude/Codex/Grok/OpenCode-Go approval and cannot substitute for the strong-reviewer gate. It is NOT the same as this CLI's own "wp review log" subcommand, which writes only the machine ledger and requires --provider plus a human reviewer for any approval verdict. See catalog/agent/rules/pre-implementation.md.`;
 }
+/**
+ * Guards the invariant this file must never silently violate: a
+ * `wp-git-tree-v1` delivery subject digest is computed purely from the
+ * committed tree at `targetSha` (see createDeliverySubjectAtRef). When that
+ * target is the currently checked-out HEAD — the default and overwhelmingly
+ * common case — any uncommitted non-evidence change in the working tree is
+ * content nobody has reviewed yet. Reporting a "satisfied" verdict in that
+ * state (whether by reusing a prior approval for `targetSha` or by running a
+ * fresh review whose prompt still only sees `targetSha`'s committed content)
+ * would silently ship edits that were never reviewed. Fail closed instead.
+ *
+ * Plan purpose is intentionally exempt: its `wp-blueprint-v1` digest is
+ * scoped to a single file and already neutralizes lifecycle bookkeeping by
+ * design (see normalizePlanSubjectContent), so uncommitted lifecycle moves
+ * are expected to keep reusing an existing plan approval.
+ */
+function assertWorkingTreeMatchesDeliveryTarget(projectRoot, purpose, targetSha, baseSha) {
+    if (purpose !== "delivery" || targetSha !== baseSha)
+        return;
+    const gitRoot = resolveReviewGitToplevel(projectRoot);
+    const divergentPaths = findUnreviewedWorkingTreeChanges(gitRoot);
+    if (divergentPaths.length === 0)
+        return;
+    throw new Error(`Review target ${targetSha} is the current HEAD, but the working tree has uncommitted ` +
+        `changes not reflected in that reviewed commit: ${divergentPaths.join(", ")}. A ` +
+        `wp-git-tree-v1 approval bound to ${targetSha} does not cover these edits. Commit (or ` +
+        `discard) the changes so the reviewed content matches what will actually ship, then ` +
+        `re-run "wp review gate".`);
+}
 export async function runReviewGate(projectRoot, slug, input, dependencies = { invokeProvider }) {
     const location = await resolveReviewBlueprint(projectRoot, slug);
+    assertReviewEvidenceCapable(location);
     if (lstatSync(location.path).isSymbolicLink()) {
         throw new Error(`Blueprint overview must not be a symlink: ${location.path}`);
     }
@@ -1560,6 +1925,7 @@ export async function runReviewGate(projectRoot, slug, input, dependencies = { i
     const subject = purpose === "plan"
         ? createPlanSubjectAtRef(projectRoot, targetSha, stableSlug, repositoryBlueprintPath)
         : createDeliverySubjectAtRef(projectRoot, targetSha, stableSlug, repositoryBlueprintPath);
+    assertWorkingTreeMatchesDeliveryTarget(projectRoot, purpose, targetSha, baseSha);
     const promptHash = hashPrompt({
         blueprintContent,
         blueprintSlug: stableSlug,
@@ -1578,13 +1944,16 @@ export async function runReviewGate(projectRoot, slug, input, dependencies = { i
     }
     const explicitProvider = normalizeGateProvider(input.provider);
     const effort = normalizeGateEffort(input.effort);
-    const prompt = buildGatePrompt({
+    const renderPrompt = (verificationSummary, priorRejections) => buildGatePrompt({
         blueprintPath: projectBlueprintPath,
         blueprintSlug: stableSlug,
         purpose,
         subject,
         targetSha,
+        ...(verificationSummary ? { verificationSummary } : {}),
+        ...(priorRejections ? { priorRejections } : {}),
     });
+    let prompt = renderPrompt();
     return withLock("worktree", async () => {
         const resumed = loadGateState(projectRoot, gateId, {
             purpose,
@@ -1597,17 +1966,32 @@ export async function runReviewGate(projectRoot, slug, input, dependencies = { i
                 resumed.subjectDigest !== subject.digest)) {
             throw new Error(`Gate ${gateId} does not match target ${targetSha} and prompt ${promptHash}.`);
         }
-        let reusedEvents = [];
         const gateIssues = [];
+        let lineageFailure;
+        let rejectedSubjects = [];
+        let reusedApprovals = [];
         try {
             const reusedAuthority = readReviewAuthorityAtRef(projectRoot, targetSha, stableSlug, purpose);
-            reusedEvents = reusedAuthority.approvals;
+            reusedApprovals = reusedAuthority.approvals;
             gateIssues.push(...reusedAuthority.issues);
+            const formalRejectionIds = new Set(reusedAuthority.events.filter(isFormalGateRejection).map((event) => event.id));
+            const compromisedRejection = reusedAuthority.issues.find((issue) => [...formalRejectionIds].some((eventId) => issue.includes(`(${eventId})`)));
+            if (compromisedRejection) {
+                lineageFailure = `Formal rejection evidence failed integrity verification: ${compromisedRejection}`;
+            }
+            else {
+                rejectedSubjects = rejectedReviewSubjects({
+                    events: reusedAuthority.events,
+                    projectRoot,
+                    purpose,
+                    stableSlug,
+                });
+            }
         }
-        catch {
-            reusedEvents = [];
+        catch (error) {
+            lineageFailure = `Review lineage authority is unreadable: ${error instanceof Error ? error.message : String(error)}`;
+            gateIssues.push(lineageFailure);
         }
-        const reusedApprovals = reusedEvents;
         const statePath = reviewGateStatePath(projectRoot, gateId);
         const reusedSummary = reusedApprovals.map((entry) => ({
             reviewer: entry.reviewer,
@@ -1617,7 +2001,9 @@ export async function runReviewGate(projectRoot, slug, input, dependencies = { i
             targetHash: entry.subjectDigest,
             rev: entry.id,
         }));
-        const workingAtStart = readWorkingReviewEvents(location.path, stableSlug);
+        const workingAtStart = lineageFailure
+            ? { events: [], compromisedIds: new Set(), issues: [] }
+            : readWorkingReviewEvents(location.path, stableSlug);
         gateIssues.push(...workingAtStart.issues);
         const durableGateEvents = workingAtStart.events.filter((event) => event.gateId === gateId &&
             event.promptHash === promptHash &&
@@ -1630,6 +2016,7 @@ export async function runReviewGate(projectRoot, slug, input, dependencies = { i
             ...(resumed?.attempts ?? []),
             ...durableGateEvents.map(gateAttemptFromEvent),
         ]);
+        let verification;
         let publicationProgress = resumed?.publicationProgress ??
             (durableGateEvents.length > 0
                 ? { artifact: true, ledger: true, frontmatter: false }
@@ -1648,7 +2035,7 @@ export async function runReviewGate(projectRoot, slug, input, dependencies = { i
             }, working.compromisedIds);
             return evaluateApprovalReviewers(evaluation.approvals.map((entry) => entry.reviewer));
         };
-        const makeResult = (approvalGate, status) => ({
+        const makeResult = (approvalGate, status, messageOverride) => ({
             schemaVersion: 2,
             gateId,
             purpose,
@@ -1666,222 +2053,336 @@ export async function runReviewGate(projectRoot, slug, input, dependencies = { i
             publicationProgress,
             reusedApprovals: reusedSummary,
             ...(gateIssues.length > 0 ? { issues: [...gateIssues] } : {}),
-            message: `${approvalGate.satisfied
-                ? `Approval gate satisfied (${formatApprovalGateRequirement(approvalGate)}).`
-                : `Approval gate not satisfied (${formatApprovalGateRequirement(approvalGate)}).`}${gateIssues.length > 0 ? ` Warnings: ${gateIssues.join("; ")}` : ""}`,
+            ...(verification ? { verification } : {}),
+            message: messageOverride ??
+                `${approvalGate.satisfied
+                    ? `Approval gate satisfied (${formatApprovalGateRequirement(approvalGate)}).`
+                    : `Approval gate not satisfied (${formatApprovalGateRequirement(approvalGate)}).`}${gateIssues.length > 0 ? ` Warnings: ${gateIssues.join("; ")}` : ""}`,
         });
-        let approvalGate = currentApprovalGate();
-        if (approvalGate.satisfied) {
-            const result = makeResult(approvalGate, reusedApprovals.length > 0 ? "approved" : "recorded-untracked");
-            assertReviewRefUnchanged(projectRoot, input.target ?? "HEAD", targetSha);
-            persistGateState(projectRoot, result);
-            return result;
-        }
-        if (attempts.some((attempt) => attempt.status === "complete" && attempt.verdict === "reject")) {
-            const result = makeResult(approvalGate, "rejected");
+        if (lineageFailure) {
+            const result = makeResult(evaluateApprovalReviewers([]), "verification-failed", `${lineageFailure} No review provider was invoked.`);
             assertReviewRefUnchanged(projectRoot, input.target ?? "HEAD", targetSha);
             persistGateState(projectRoot, result);
             return result;
         }
-        const artifactDirectory = path.join(path.dirname(location.path), "review-artifacts");
-        if (existsSync(artifactDirectory) && lstatSync(artifactDirectory).isSymbolicLink()) {
-            throw new Error(`Review artifact directory must not be a symlink: ${artifactDirectory}`);
-        }
-        const availabilityPrune = pruneExpiredAvailabilitySuppressions(loadReviewAvailability(projectRoot));
-        if (availabilityPrune.pruned.length > 0) {
-            saveReviewAvailability(projectRoot, availabilityPrune.state);
-        }
-        const availability = availabilityPrune.state;
-        const providerQueue = selectGateProviders({
-            availability,
-            ...(explicitProvider ? { explicitProvider } : {}),
-        });
-        const usedReviewers = new Set([
-            ...attempts
-                .filter((attempt) => !isRetryableGateAttempt(attempt))
-                .map((attempt) => attempt.reviewer)
-                .filter((value) => Boolean(value)),
-            ...suppressedReviewers(availability),
-        ]);
         const checkoutFactory = dependencies.createTargetCheckout ?? createReviewTargetCheckout;
         let sharedCheckout;
         let checkoutSetupFailed = false;
-        if (!dependencies.invokeProvider) {
+        // Deferred: a review checkout costs a full `git archive` + tar tree copy
+        // plus status fingerprints, so it must not be created on gate calls that
+        // never need one (plan-purpose reuse of an existing approval, terminal
+        // rejections, exhausted scope). A setup failure is remembered so provider
+        // attempts still surface the same isolation-failure evidence.
+        const ensureSharedCheckout = () => {
+            if (sharedCheckout !== undefined || checkoutSetupFailed)
+                return sharedCheckout;
             try {
                 sharedCheckout = checkoutFactory(projectRoot, targetSha);
             }
             catch {
                 checkoutSetupFailed = true;
             }
-        }
-        const createCheckoutForAttempt = checkoutSetupFailed
-            ? () => {
-                throw new Error("review checkout setup failed");
-            }
-            : checkoutFactory;
+            return sharedCheckout;
+        };
+        const createCheckoutForAttempt = () => {
+            // Only reachable when ensureSharedCheckout() already failed — a live
+            // shared checkout is always passed to the attempt as existingCheckout.
+            throw new Error("review checkout setup failed");
+        };
+        let sharedCheckoutCleaned = false;
+        const cleanupSharedCheckout = () => {
+            if (sharedCheckoutCleaned)
+                return;
+            sharedCheckoutCleaned = true;
+            sharedCheckout?.cleanup();
+        };
         try {
-            reviewAttempts: for (const provider of providerQueue) {
-                const maxAttempts = provider === "claude" ||
-                    provider === "codex" ||
-                    provider === "grok" ||
-                    (provider === explicitProvider && input.model)
-                    ? 1
-                    : OPENCODE_FAMILY_ORDER.length;
-                for (let index = 0; index < maxAttempts && !approvalGate.satisfied; index += 1) {
-                    if (dependencies.signal?.aborted)
-                        break reviewAttempts;
-                    const providerResult = enforceReviewPublicationOutput(await (dependencies.invokeProvider ?? invokeProvider)({
-                        provider,
-                        projectRoot,
-                        prompt,
-                        effort,
-                        ...(provider === explicitProvider && input.model ? { model: input.model } : {}),
-                        excludedReviewers: usedReviewers,
-                        targetSha,
-                        ...(dependencies.signal ? { signal: dependencies.signal } : {}),
-                    }, dependencies.runReviewExecution, dependencies.runCatalogCommand, createCheckoutForAttempt, sharedCheckout));
-                    if (providerResult.reviewer !== "opencode")
-                        usedReviewers.add(providerResult.reviewer);
-                    const providerStage = gateAttemptStage(providerResult.stage ?? "review");
-                    let attemptOrdinal = nextGateAttemptOrdinal(attempts, provider, providerResult.model, providerStage);
-                    let artifactRelative;
-                    let artifactAbsolute;
-                    let rev;
-                    while (true) {
-                        artifactRelative = reviewArtifactRelativePath({
+            // Only the delivery purpose runs checkout-backed gate verification
+            // (verifyDeliveryPromotionGates is a no-op for every other purpose).
+            const deliveryCheckout = purpose === "delivery" ? ensureSharedCheckout() : undefined;
+            if (deliveryCheckout) {
+                verification = verifyDeliveryPromotionGates({
+                    purpose,
+                    blueprintContent,
+                    projectRoot,
+                    gateId,
+                    checkout: deliveryCheckout,
+                    ...(dependencies.signal ? { signal: dependencies.signal } : {}),
+                });
+                const summary = verificationPromptSummary(verification);
+                if (summary) {
+                    prompt = renderPrompt(summary);
+                }
+                if (verification?.status === "failed") {
+                    const result = makeResult(currentApprovalGate(), "verification-failed");
+                    assertReviewRefUnchanged(projectRoot, input.target ?? "HEAD", targetSha);
+                    persistGateState(projectRoot, result);
+                    cleanupSharedCheckout();
+                    return result;
+                }
+            }
+            let approvalGate = currentApprovalGate();
+            if (approvalGate.satisfied) {
+                const result = makeResult(approvalGate, reusedApprovals.length > 0 ? "approved" : "recorded-untracked");
+                assertReviewRefUnchanged(projectRoot, input.target ?? "HEAD", targetSha);
+                persistGateState(projectRoot, result);
+                cleanupSharedCheckout();
+                return result;
+            }
+            if (attempts.some((attempt) => attempt.status === "complete" && attempt.verdict === "reject")) {
+                const result = makeResult(approvalGate, "rejected");
+                assertReviewRefUnchanged(projectRoot, input.target ?? "HEAD", targetSha);
+                persistGateState(projectRoot, result);
+                cleanupSharedCheckout();
+                return result;
+            }
+            const currentSubjectRejection = rejectedSubjects.find((entry) => entry.subjectDigest === subject.digest);
+            if (currentSubjectRejection) {
+                const result = makeResult(approvalGate, "rejected", `This semantic review subject was already rejected (${currentSubjectRejection.artifactPath}). No review provider was invoked.`);
+                assertReviewRefUnchanged(projectRoot, input.target ?? "HEAD", targetSha);
+                persistGateState(projectRoot, result);
+                cleanupSharedCheckout();
+                return result;
+            }
+            if (rejectedSubjects.length >= 2) {
+                const result = makeResult(approvalGate, "scope-exhausted", "Formal review budget exhausted after two rejected semantic subjects. No review provider was invoked; stop and obtain an explicit human scope decision before creating a successor blueprint.");
+                assertReviewRefUnchanged(projectRoot, input.target ?? "HEAD", targetSha);
+                persistGateState(projectRoot, result);
+                cleanupSharedCheckout();
+                return result;
+            }
+            if (rejectedSubjects.length > 0) {
+                prompt = renderPrompt(verification ? verificationPromptSummary(verification) : undefined, rejectedSubjects.slice(0, 2));
+            }
+            const artifactDirectory = path.join(path.dirname(location.path), "review-artifacts");
+            if (existsSync(artifactDirectory) && lstatSync(artifactDirectory).isSymbolicLink()) {
+                throw new Error(`Review artifact directory must not be a symlink: ${artifactDirectory}`);
+            }
+            const availabilityPrune = pruneExpiredAvailabilitySuppressions(loadReviewAvailability(projectRoot));
+            if (availabilityPrune.pruned.length > 0) {
+                saveReviewAvailability(projectRoot, availabilityPrune.state);
+            }
+            const availability = availabilityPrune.state;
+            const providerQueue = selectGateProviders({
+                availability,
+                ...(explicitProvider ? { explicitProvider } : {}),
+            });
+            const usedReviewers = new Set([
+                ...attempts
+                    .filter((attempt) => !isRetryableGateAttempt(attempt))
+                    .map((attempt) => attempt.reviewer)
+                    .filter((value) => Boolean(value)),
+                ...suppressedReviewers(availability),
+            ]);
+            // Prepare opencode-go multi-account failover only when opencode is
+            // actually queued (avoids a needless secret fetch otherwise). Resolves
+            // Doppler accounts, materializes the freshest non-cooled account's
+            // isolated auth store, and hands the loop its XDG_DATA_HOME. Degrades to
+            // undefined (today's global-auth behavior) when unprovisioned.
+            const opencodeFailover = providerQueue.includes("opencode")
+                ? createOpencodeFailoverController({
+                    projectRoot,
+                    resolveAccounts: dependencies.resolveOpencodeAccounts ?? resolveOpencodeAccountsGracefully,
+                    prepareCredential: dependencies.prepareOpencodeCredential ?? prepareOpencodeCredentialDefault,
+                })
+                : undefined;
+            try {
+                reviewAttempts: for (const provider of providerQueue) {
+                    const maxAttempts = provider === "claude" ||
+                        provider === "codex" ||
+                        provider === "grok" ||
+                        (provider === explicitProvider && input.model)
+                        ? 1
+                        : OPENCODE_FAMILY_ORDER.length;
+                    for (let index = 0; index < maxAttempts && !approvalGate.satisfied; index += 1) {
+                        if (dependencies.signal?.aborted)
+                            break reviewAttempts;
+                        const opencodeAuthDataDir = provider === "opencode" ? opencodeFailover?.authDataDir() : undefined;
+                        const providerResult = enforceReviewPublicationOutput(await (dependencies.invokeProvider ?? invokeProvider)({
+                            provider,
                             projectRoot,
-                            blueprintPath: location.path,
-                            gateId,
+                            prompt,
+                            effort,
+                            ...(provider === explicitProvider && input.model ? { model: input.model } : {}),
+                            excludedReviewers: usedReviewers,
+                            targetSha,
+                            ...(dependencies.signal ? { signal: dependencies.signal } : {}),
+                            ...(opencodeAuthDataDir ? { authDataDir: opencodeAuthDataDir } : {}),
+                        }, dependencies.runReviewExecution, dependencies.runCatalogCommand, createCheckoutForAttempt, ensureSharedCheckout));
+                        if (providerResult.reviewer !== "opencode")
+                            usedReviewers.add(providerResult.reviewer);
+                        const providerStage = gateAttemptStage(providerResult.stage ?? "review");
+                        let attemptOrdinal = nextGateAttemptOrdinal(attempts, provider, providerResult.model, providerStage);
+                        let artifactRelative;
+                        let artifactAbsolute;
+                        let rev;
+                        while (true) {
+                            artifactRelative = reviewArtifactRelativePath({
+                                projectRoot,
+                                blueprintPath: location.path,
+                                gateId,
+                                provider,
+                                reviewer: providerResult.reviewer,
+                                stage: providerStage,
+                                ordinal: attemptOrdinal,
+                            });
+                            artifactAbsolute = safeArtifactPath(location.path, artifactRelative);
+                            rev = reviewGateEventId({
+                                gateId,
+                                provider,
+                                model: providerResult.model,
+                                stage: providerStage,
+                                ordinal: attemptOrdinal,
+                            });
+                            if (!existsSync(artifactAbsolute) &&
+                                !gateArtifactPaths.has(artifactRelative) &&
+                                !gateEventIds.has(rev)) {
+                                break;
+                            }
+                            attemptOrdinal += 1;
+                        }
+                        const persistedOrdinal = providerStage === "approval-gate" && attemptOrdinal === 1
+                            ? undefined
+                            : attemptOrdinal;
+                        const attempt = {
+                            provider,
+                            model: providerResult.model,
+                            effort,
+                            reviewer: providerResult.reviewer,
+                            promptHash,
+                            ...(persistedOrdinal === undefined ? {} : { ordinal: persistedOrdinal }),
+                            stage: providerStage,
+                            status: providerResult.status,
+                            verdict: providerResult.verdict,
+                            terminalClassification: providerResult.terminalClassification,
+                            ...(providerResult.failureCode ? { failureCode: providerResult.failureCode } : {}),
+                            ...(providerResult.providerErrorDetail
+                                ? { providerErrorDetail: providerResult.providerErrorDetail }
+                                : {}),
+                            ...(providerResult.limitWindow ? { limitWindow: providerResult.limitWindow } : {}),
+                            ...(providerResult.retryAfterMs === undefined
+                                ? {}
+                                : { retryAfterMs: providerResult.retryAfterMs }),
+                            artifact: artifactRelative,
+                        };
+                        attempts = dedupeGateAttempts([...attempts, attempt]);
+                        recordReviewAvailability(projectRoot, {
                             provider,
                             reviewer: providerResult.reviewer,
+                            model: providerResult.model,
+                            effort,
                             stage: providerStage,
-                            ordinal: attemptOrdinal,
+                            terminalClassification: providerResult.terminalClassification,
+                            ...(providerResult.failureCode ? { failureCode: providerResult.failureCode } : {}),
+                            ...(providerResult.limitWindow ? { limitWindow: providerResult.limitWindow } : {}),
+                            ...(providerResult.retryAfterMs === undefined
+                                ? {}
+                                : { retryAfterMs: providerResult.retryAfterMs }),
                         });
-                        artifactAbsolute = safeArtifactPath(location.path, artifactRelative);
-                        rev = reviewGateEventId({
+                        const artifactContent = Buffer.from(`${verificationArtifactSection(verification)}${providerResult.output}`, "utf8");
+                        const event = {
+                            schemaVersion: 2,
+                            id: rev,
+                            purpose,
+                            blueprintSlug: stableSlug,
+                            subjectScheme: subject.scheme,
+                            subjectDigest: subject.digest,
+                            reviewedCommit: targetSha,
                             gateId,
+                            promptHash,
+                            reviewer: providerResult.reviewer,
                             provider,
                             model: providerResult.model,
+                            effort,
                             stage: providerStage,
-                            ordinal: attemptOrdinal,
+                            ...(persistedOrdinal === undefined ? {} : { attemptOrdinal: persistedOrdinal }),
+                            status: providerResult.status,
+                            verdict: providerResult.verdict,
+                            terminalClassification: providerResult.terminalClassification,
+                            ...(providerResult.failureCode ? { failureCode: providerResult.failureCode } : {}),
+                            ...(providerResult.limitWindow ? { limitWindow: providerResult.limitWindow } : {}),
+                            ...(providerResult.retryAfterMs === undefined
+                                ? {}
+                                : { retryAfterMs: providerResult.retryAfterMs }),
+                            timestamp: new Date().toISOString(),
+                            artifactPath: artifactRelative,
+                            artifactSha256: createHash("sha256").update(artifactContent).digest("hex"),
+                        };
+                        appendReviewEvent({
+                            ledgerPath: path.join(path.dirname(location.path), "review-events.jsonl"),
+                            event,
+                            artifact: { path: artifactAbsolute, content: artifactContent },
                         });
-                        if (!existsSync(artifactAbsolute) &&
-                            !gateArtifactPaths.has(artifactRelative) &&
-                            !gateEventIds.has(rev)) {
+                        gateEventIds.add(rev);
+                        gateArtifactPaths.add(artifactRelative);
+                        publicationProgress = { artifact: true, ledger: true, frontmatter: false };
+                        approvalGate = currentApprovalGate();
+                        const interimStatus = providerResult.verdict === "reject"
+                            ? "rejected"
+                            : approvalGate.satisfied
+                                ? "recorded-untracked"
+                                : "needs-review";
+                        persistGateState(projectRoot, makeResult(approvalGate, interimStatus));
+                        if (providerResult.verdict === "reject") {
+                            return makeResult(approvalGate, "rejected");
+                        }
+                        if (providerResult.failureCode === "review-worktree-contaminated" ||
+                            providerResult.failureCode === "review-isolation-failure") {
+                            break reviewAttempts;
+                        }
+                        if (dependencies.signal?.aborted)
+                            break reviewAttempts;
+                        if (provider === "opencode" &&
+                            opencodeFailover &&
+                            providerResult.terminalClassification === "provider-limit-reached" &&
+                            providerResult.failureCode === "opencode-go-usage-limit") {
+                            const outcome = await opencodeFailover.onUsageLimit({
+                                effort,
+                                stage: providerStage,
+                                ...(providerResult.limitWindow
+                                    ? { limitWindow: providerResult.limitWindow }
+                                    : {}),
+                                ...(providerResult.retryAfterMs === undefined
+                                    ? {}
+                                    : { retryAfterMs: providerResult.retryAfterMs }),
+                            });
+                            if (outcome === "retry") {
+                                // The family failed only because its ACCOUNT was capped. Make it
+                                // eligible again and retry under the next account without
+                                // consuming a family-rotation slot.
+                                usedReviewers.delete(providerResult.reviewer);
+                                index -= 1;
+                                continue;
+                            }
                             break;
                         }
-                        attemptOrdinal += 1;
-                    }
-                    const persistedOrdinal = providerStage === "approval-gate" && attemptOrdinal === 1
-                        ? undefined
-                        : attemptOrdinal;
-                    const attempt = {
-                        provider,
-                        model: providerResult.model,
-                        effort,
-                        reviewer: providerResult.reviewer,
-                        promptHash,
-                        ...(persistedOrdinal === undefined ? {} : { ordinal: persistedOrdinal }),
-                        stage: providerStage,
-                        status: providerResult.status,
-                        verdict: providerResult.verdict,
-                        terminalClassification: providerResult.terminalClassification,
-                        ...(providerResult.failureCode ? { failureCode: providerResult.failureCode } : {}),
-                        ...(providerResult.limitWindow ? { limitWindow: providerResult.limitWindow } : {}),
-                        ...(providerResult.retryAfterMs === undefined
-                            ? {}
-                            : { retryAfterMs: providerResult.retryAfterMs }),
-                        artifact: artifactRelative,
-                    };
-                    attempts = dedupeGateAttempts([...attempts, attempt]);
-                    recordReviewAvailability(projectRoot, {
-                        provider,
-                        reviewer: providerResult.reviewer,
-                        model: providerResult.model,
-                        effort,
-                        stage: providerStage,
-                        terminalClassification: providerResult.terminalClassification,
-                        ...(providerResult.failureCode ? { failureCode: providerResult.failureCode } : {}),
-                        ...(providerResult.limitWindow ? { limitWindow: providerResult.limitWindow } : {}),
-                        ...(providerResult.retryAfterMs === undefined
-                            ? {}
-                            : { retryAfterMs: providerResult.retryAfterMs }),
-                    });
-                    const artifactContent = Buffer.from(providerResult.output, "utf8");
-                    const event = {
-                        schemaVersion: 2,
-                        id: rev,
-                        purpose,
-                        blueprintSlug: stableSlug,
-                        subjectScheme: subject.scheme,
-                        subjectDigest: subject.digest,
-                        reviewedCommit: targetSha,
-                        gateId,
-                        promptHash,
-                        reviewer: providerResult.reviewer,
-                        provider,
-                        model: providerResult.model,
-                        effort,
-                        stage: providerStage,
-                        ...(persistedOrdinal === undefined ? {} : { attemptOrdinal: persistedOrdinal }),
-                        status: providerResult.status,
-                        verdict: providerResult.verdict,
-                        terminalClassification: providerResult.terminalClassification,
-                        ...(providerResult.failureCode ? { failureCode: providerResult.failureCode } : {}),
-                        ...(providerResult.limitWindow ? { limitWindow: providerResult.limitWindow } : {}),
-                        ...(providerResult.retryAfterMs === undefined
-                            ? {}
-                            : { retryAfterMs: providerResult.retryAfterMs }),
-                        timestamp: new Date().toISOString(),
-                        artifactPath: artifactRelative,
-                        artifactSha256: createHash("sha256").update(artifactContent).digest("hex"),
-                    };
-                    appendReviewEvent({
-                        ledgerPath: path.join(path.dirname(location.path), "review-events.jsonl"),
-                        event,
-                        artifact: { path: artifactAbsolute, content: artifactContent },
-                    });
-                    gateEventIds.add(rev);
-                    gateArtifactPaths.add(artifactRelative);
-                    publicationProgress = { artifact: true, ledger: true, frontmatter: false };
-                    approvalGate = currentApprovalGate();
-                    const interimStatus = providerResult.verdict === "reject"
-                        ? "rejected"
-                        : approvalGate.satisfied
-                            ? "recorded-untracked"
-                            : "needs-review";
-                    persistGateState(projectRoot, makeResult(approvalGate, interimStatus));
-                    if (providerResult.verdict === "reject") {
-                        return makeResult(approvalGate, "rejected");
-                    }
-                    if (providerResult.failureCode === "review-worktree-contaminated" ||
-                        providerResult.failureCode === "review-isolation-failure") {
-                        break reviewAttempts;
-                    }
-                    if (dependencies.signal?.aborted)
-                        break reviewAttempts;
-                    if (providerResult.terminalClassification === "provider-limit-reached" &&
-                        (provider !== "opencode" || isProviderWideOpenCodeGateResult(providerResult))) {
-                        break;
+                        if (providerResult.terminalClassification === "provider-limit-reached" &&
+                            (provider !== "opencode" || isProviderWideOpenCodeGateResult(providerResult))) {
+                            break;
+                        }
+                        if ((provider === "claude" || provider === "codex") &&
+                            providerResult.status === "complete")
+                            break;
+                        if (provider === "opencode" && providerResult.reviewer === "opencode")
+                            break;
                     }
-                    if ((provider === "claude" || provider === "codex") &&
-                        providerResult.status === "complete")
-                        break;
-                    if (provider === "opencode" && providerResult.reviewer === "opencode")
-                        break;
                 }
             }
+            finally {
+                cleanupSharedCheckout();
+            }
+            const status = approvalGate.satisfied
+                ? "recorded-untracked"
+                : "needs-review";
+            const result = makeResult(approvalGate, status);
+            assertReviewRefUnchanged(projectRoot, input.target ?? "HEAD", targetSha);
+            persistGateState(projectRoot, result);
+            return result;
         }
-        finally {
-            sharedCheckout?.cleanup();
+        catch (error) {
+            cleanupSharedCheckout();
+            throw error;
         }
-        const status = approvalGate.satisfied
-            ? "recorded-untracked"
-            : "needs-review";
-        const result = makeResult(approvalGate, status);
-        assertReviewRefUnchanged(projectRoot, input.target ?? "HEAD", targetSha);
-        persistGateState(projectRoot, result);
-        return result;
     }, projectRoot).catch((error) => {
         if (isStateLockHeldError(error)) {
             throw new Error(`Review gate ${gateId} is already active for this worktree. Wait for the owner to finish, then retry with --resume ${gateId}; the lock acquisition bound was not increased.`, { cause: error });
@@ -2243,6 +2744,8 @@ export function registerReviewCommand(cli, deps = {}) {
         .option("--effort <effort>", "Review effort (medium|high)")
         .option("--resume <gate-id>", "Resume a persisted review gate")
         .option("--reviewer <name>", "Reviewer id for `review log`")
+        .option("--reason <text>", "Maintainer reason for `review override`")
+        .option("--confirm", "Confirm a `review override` (required)")
         .option("--target-kind <kind>", "blueprint | pull-request")
         .option("--target-id <id>", "Target slug / PR number / stable review target id")
         .option("--artifact <path>", "Committed review transcript/artifact path relative to blueprint (required for promotion-counted approvals)")
@@ -2290,6 +2793,7 @@ export function registerReviewCommand(cli, deps = {}) {
                         ? undefined
                         : reviewGateNonConvergenceHint(slug, {
                             gateId: result.gateId,
+                            status: result.status,
                             ...(latestFailure?.failureCode
                                 ? { failureCode: latestFailure.failureCode }
                                 : {}),
@@ -2300,6 +2804,9 @@ export function registerReviewCommand(cli, deps = {}) {
                             `${result.status}: ${result.message}`,
                             `gate: ${result.gateId}`,
                             `state: ${result.statePath}`,
+                            ...(latestFailure?.providerErrorDetail
+                                ? [`provider error: ${latestFailure.providerErrorDetail}`]
+                                : []),
                             ...(hint ? [hint] : []),
                         ].join("\n"));
                     return;
@@ -2318,6 +2825,16 @@ export function registerReviewCommand(cli, deps = {}) {
                     : `Logged review ${entry.id} -> ${entry.blueprintSlug}`);
                 return;
             }
+            case "override": {
+                const slug = args[0];
+                if (!slug)
+                    throw new Error("Usage: wp review override <blueprint-slug> --reason <text> --confirm [--purpose plan|delivery] [--target <git-ref>]");
+                const entry = await runReviewOverride(projectRoot, slug, options);
+                console.log(options.json
+                    ? JSON.stringify(entry, null, 2)
+                    : `Recorded maintainer override ${entry.id} -> ${entry.blueprintSlug}`);
+                return;
+            }
             case "read": {
                 const slug = args[0];
                 if (!slug)
@@ -2359,7 +2876,7 @@ export function registerReviewCommand(cli, deps = {}) {
                 }
             }
             default:
-                throw new Error("Unknown review subcommand. Use one of: gate, run, log, read, scoreboard, availability, doctor");
+                throw new Error("Unknown review subcommand. Use one of: gate, run, log, override, read, scoreboard, availability, doctor");
         }
     });
 }