@webpresso/agent-kit 3.1.28 → 3.2.0

package/dist/esm/output-transforms/audit.d.ts

@@ -0,0 +1,23 @@
+import type { TransformContext, TransformResult } from "./index.js";
+/**
+ * `wp audit <kind>` writes the full `formatRepoAuditReport` output (title +
+ * one bullet per violation) into its CLI log. Every audit kind normalizes to
+ * the shared `"audit"` tool name (see `normalizeToolName`), so without a
+ * dedicated transform that output fell through to `genericTransform`, whose
+ * error/fail keyword heuristic drops any violation bullet that doesn't
+ * literally contain "error"/"fail"/"✗"/"✘" — silently discarding most
+ * violation detail even when the full report is a handful of short lines.
+ *
+ * This transform recognizes the bullet-list shape directly so violation text
+ * survives regardless of wording, then defers to the same size-based
+ * clip/elision policy every other transform uses (`createTransformResult` /
+ * `clipRawOutput`'s existing byte threshold) to decide whether the (now
+ * correctly extracted) violation list is short enough to print inline or
+ * long enough to still defer to `wp logs audit`.
+ *
+ * Audit output that isn't shaped like a violation-bullet report (for example
+ * raw subprocess output from `mutation`/`bundle-budget`) has no matching
+ * bullet lines, so this falls back to the previous generic keyword-based
+ * behavior unchanged.
+ */
+export declare function auditTransform(rawOutput: string | undefined, context: TransformContext): TransformResult;

package/dist/esm/output-transforms/audit.js

@@ -0,0 +1,47 @@
+import { createTransformResult } from "./metadata.js";
+import { genericTransform } from "./generic.js";
+// `formatRepoAuditReport` (src/audit/repo-guardrails.ts) always renders one
+// violation per line as `- <location><metadata><message><fixability>`. That
+// bullet marker is the one structural signal every repo-audit report shares,
+// regardless of which audit kind produced it or whether the violation text
+// happens to contain the words "error"/"fail" that the generic fallback
+// keys off of.
+const VIOLATION_LINE_RE = /^-\s+(.+)$/u;
+/**
+ * `wp audit <kind>` writes the full `formatRepoAuditReport` output (title +
+ * one bullet per violation) into its CLI log. Every audit kind normalizes to
+ * the shared `"audit"` tool name (see `normalizeToolName`), so without a
+ * dedicated transform that output fell through to `genericTransform`, whose
+ * error/fail keyword heuristic drops any violation bullet that doesn't
+ * literally contain "error"/"fail"/"✗"/"✘" — silently discarding most
+ * violation detail even when the full report is a handful of short lines.
+ *
+ * This transform recognizes the bullet-list shape directly so violation text
+ * survives regardless of wording, then defers to the same size-based
+ * clip/elision policy every other transform uses (`createTransformResult` /
+ * `clipRawOutput`'s existing byte threshold) to decide whether the (now
+ * correctly extracted) violation list is short enough to print inline or
+ * long enough to still defer to `wp logs audit`.
+ *
+ * Audit output that isn't shaped like a violation-bullet report (for example
+ * raw subprocess output from `mutation`/`bundle-budget`) has no matching
+ * bullet lines, so this falls back to the previous generic keyword-based
+ * behavior unchanged.
+ */
+export function auditTransform(rawOutput, context) {
+    if (!rawOutput)
+        return {};
+    const failures = extractViolationBullets(rawOutput);
+    if (failures.length === 0)
+        return genericTransform(rawOutput, context);
+    return createTransformResult(rawOutput, failures.map((failure) => failure.message).join("\n"), context, { tier: 1, failures });
+}
+function extractViolationBullets(rawOutput) {
+    const failures = [];
+    for (const line of rawOutput.split(/\r?\n/u)) {
+        const message = VIOLATION_LINE_RE.exec(line)?.[1]?.trim();
+        if (message)
+            failures.push({ message });
+    }
+    return failures;
+}

package/dist/esm/output-transforms/index.js

@@ -1,3 +1,4 @@
+import { auditTransform } from "./audit.js";
 import { genericTransform } from "./generic.js";
 import { oxlintTransform } from "./oxlint.js";
 import { tscTransform } from "./tsc.js";
@@ -8,6 +9,7 @@ const builtInTransforms = new Map([
     ["lint-oxlint", oxlintTransform],
     ["typecheck", tscTransform],
     ["test", vitestTransform],
+    ["audit", auditTransform],
 ]);
 const transforms = new Map(builtInTransforms);
 export function registerTransform(toolName, transform) {

package/dist/esm/paths/state-root.js

@@ -247,6 +247,9 @@ export async function getSurfacePathAsync(name, scope, cwd = resolveCwd()) {
 export async function withLock(scope, fn, cwd) {
     const lockTarget = await getSurfacePathAsync(".lock", scope, cwd);
     mkdirSync(dirname(lockTarget), { recursive: true });
+    // Keep retries short so lock-contention probes (review gate contender tests)
+    // still fail closed in a few seconds. Dual-writer create loops retry at the
+    // call site when they need longer budgets under CI load.
     const release = await lockfile.lock(lockTarget, {
         realpath: false,
         retries: { retries: 5, minTimeout: 50, maxTimeout: 500, factor: 2 },

package/dist/esm/review/authority.js

@@ -9,7 +9,7 @@ import { createHash } from "node:crypto";
 import { existsSync, lstatSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { evaluateReviewEvents, parseReviewEventLog } from "./events.js";
-import { createDeliverySubjectAtRef, createPlanSubjectAtRef, resolveReviewCommit, } from "./subject.js";
+import { createDeliverySubjectAtRef, createLegacyPlanSubjectAtRef, createPlanSubjectAtRef, resolveReviewCommit, } from "./subject.js";
 const GIT_TIMEOUT_MS = 5_000;
 const GIT_MAX_BUFFER_BYTES = 128 * 1024 * 1024;
 const REGULAR_MODE_PATTERN = /^100(?:644|755)$/u;
@@ -60,7 +60,7 @@ function assertStableSlug(slug) {
 }
 function locateBlueprint(entries, stableSlug) {
     assertStableSlug(stableSlug);
-    const suffixPattern = new RegExp(`(?:^|/)${LIFECYCLE_SEGMENTS}/${stableSlug.replaceAll("/", "\\/")}/_overview\\.md$`, "u");
+    const suffixPattern = new RegExp(`(?:^|/)${LIFECYCLE_SEGMENTS}/${stableSlug.replaceAll("/", "\\/")}(?:/_overview\\.md|\\.md)$`, "u");
     const matches = entries.filter((entry) => suffixPattern.test(entry.path) &&
         REGULAR_MODE_PATTERN.test(entry.mode) &&
         entry.type === "blob");
@@ -69,6 +69,9 @@ function locateBlueprint(entries, stableSlug) {
     }
     return matches[0];
 }
+function ledgerDirectoryForBlueprintPath(blueprintPath) {
+    return blueprintPath.endsWith("/_overview.md") ? path.posix.dirname(blueprintPath) : null;
+}
 function readBlob(cwd, entry) {
     if (!REGULAR_MODE_PATTERN.test(entry.mode) || entry.type !== "blob") {
         throw new Error(`Review authority path is not a regular blob: ${entry.path}`);
@@ -115,23 +118,40 @@ export function readReviewAuthorityAtRef(cwd, ref, stableSlug, purpose) {
     const commit = resolveReviewCommit(cwd, ref);
     const entries = parseRefTree(cwd, commit);
     const overview = locateBlueprint(entries, stableSlug);
-    const blueprintDirectory = path.posix.dirname(overview.path);
-    const ledgerPath = path.posix.join(blueprintDirectory, "review-events.jsonl");
-    const ledger = entries.find((entry) => entry.path === ledgerPath);
+    const blueprintDirectory = ledgerDirectoryForBlueprintPath(overview.path);
+    const ledgerPath = blueprintDirectory === null ? null : path.posix.join(blueprintDirectory, "review-events.jsonl");
+    const ledger = ledgerPath === null ? undefined : entries.find((entry) => entry.path === ledgerPath);
     const events = ledger ? parseReviewEventLog(readBlob(cwd, ledger).toString("utf8")) : [];
     if (events.some((event) => event.blueprintSlug !== stableSlug)) {
         throw new Error(`Review event ledger contains an event for a different blueprint: ${ledgerPath}`);
     }
-    const { compromisedIds, issues } = markCompromisedArtifactEvents(cwd, entries, blueprintDirectory, events);
+    const { compromisedIds, issues } = blueprintDirectory === null
+        ? { compromisedIds: new Set(), issues: [] }
+        : markCompromisedArtifactEvents(cwd, entries, blueprintDirectory, events);
     const subject = purpose === "plan"
         ? createPlanSubjectAtRef(cwd, commit, stableSlug, overview.path)
         : createDeliverySubjectAtRef(cwd, commit, stableSlug, overview.path);
-    const evaluation = evaluateReviewEvents(events, {
+    let evaluation = evaluateReviewEvents(events, {
         purpose,
         blueprintSlug: stableSlug,
         subjectScheme: subject.scheme,
         subjectDigest: subject.digest,
     }, compromisedIds);
+    if (purpose === "plan" && evaluation.approvals.length === 0) {
+        // Digest-compatibility fallback: events recorded before the lifecycle
+        // stripped-key extension bound their subjectDigest to the legacy
+        // normalization. Accept those for the same tracked content; new events
+        // always record the current digest (see legacyNormalizePlanSubjectContent).
+        const legacySubject = createLegacyPlanSubjectAtRef(cwd, commit, stableSlug, overview.path);
+        if (legacySubject.digest !== subject.digest) {
+            evaluation = evaluateReviewEvents(events, {
+                purpose,
+                blueprintSlug: stableSlug,
+                subjectScheme: legacySubject.scheme,
+                subjectDigest: legacySubject.digest,
+            }, compromisedIds);
+        }
+    }
     return {
         commit,
         blueprintPath: overview.path,
@@ -145,6 +165,9 @@ export function readReviewAuthorityAtRef(cwd, ref, stableSlug, purpose) {
     };
 }
 export function readWorkingReviewEvents(blueprintPath, stableSlug) {
+    if (path.basename(blueprintPath) !== "_overview.md") {
+        return { events: [], compromisedIds: new Set(), issues: [] };
+    }
     const ledgerPath = path.join(path.dirname(blueprintPath), "review-events.jsonl");
     if (!existsSync(ledgerPath))
         return { events: [], compromisedIds: new Set(), issues: [] };

package/dist/esm/review/availability.d.ts

@@ -49,3 +49,25 @@ export declare function pruneExpiredAvailabilitySuppressions(state: ReviewAvaila
     state: ReviewAvailabilityState;
     pruned: string[];
 };
+export declare const OPENCODE_ACCOUNT_AVAILABILITY_SCHEMA_VERSION = 1;
+export interface OpencodeAccountAvailabilityState {
+    readonly schemaVersion: 1;
+    readonly updatedAt: string;
+    readonly accounts: Record<string, ReviewAvailabilityRecord>;
+}
+export interface OpencodeAccountAvailabilityEvent {
+    readonly limitWindow?: ReviewLimitWindow;
+    readonly retryAfterMs?: number;
+    readonly failureCode?: string;
+    readonly terminalClassification?: string;
+    readonly at?: string;
+}
+export declare function opencodeAccountAvailabilityPath(): string;
+export declare function loadOpencodeAccountAvailability(): OpencodeAccountAvailabilityState;
+export declare function isOpencodeAccountSuppressed(state: OpencodeAccountAvailabilityState, canonicalId: string): boolean;
+export declare function recordOpencodeAccountAvailability(canonicalId: string, event: OpencodeAccountAvailabilityEvent): OpencodeAccountAvailabilityState;
+export declare function recordOpencodeAccountAvailabilityWithLock(canonicalId: string, event: OpencodeAccountAvailabilityEvent): Promise<OpencodeAccountAvailabilityState>;
+export declare function pruneExpiredOpencodeAccountSuppressions(state: OpencodeAccountAvailabilityState, nowMs?: number): {
+    state: OpencodeAccountAvailabilityState;
+    pruned: string[];
+};

package/dist/esm/review/availability.js

@@ -1,13 +1,9 @@
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import path from "node:path";
-import { NotInGitRepoError, withLock } from "#paths/state-root.js";
+import { getStateRoot, NotInGitRepoError, withLock } from "#paths/state-root.js";
 import { writeJsonFileAtomic } from "#shared-utils/write-json-file.js";
 export const REVIEW_AVAILABILITY_SCHEMA_VERSION = 1;
-const FAILURE_CLASSIFICATIONS = new Set([
-    "provider-limit-reached",
-    "provider-unavailable",
-    "provider-failed",
-]);
+const FAILURE_CLASSIFICATIONS = new Set(["provider-limit-reached", "provider-unavailable"]);
 const SUCCESS_CLASSIFICATIONS = new Set([
     "complete",
     "approved",
@@ -117,14 +113,15 @@ export function saveReviewAvailability(projectRoot, state) {
 function shouldSuppress(event) {
     return FAILURE_CLASSIFICATIONS.has(event.terminalClassification);
 }
+function suppressedRecordStillApplies(record) {
+    return (record.terminalClassification !== undefined &&
+        FAILURE_CLASSIFICATIONS.has(record.terminalClassification));
+}
 function isAvailabilitySuccess(event) {
     return SUCCESS_CLASSIFICATIONS.has(event.terminalClassification);
 }
 function isProviderWideOpenCodeFailure(event) {
-    return (event.provider === "opencode" &&
-        (event.failureCode === "opencode-go-usage-limit" ||
-            event.reviewer === undefined ||
-            event.reviewer === "opencode"));
+    return (event.provider === "opencode" && (event.reviewer === undefined || event.reviewer === "opencode"));
 }
 function nextRecord(previous, event, input) {
     const at = event.at ?? new Date().toISOString();
@@ -155,6 +152,15 @@ function nextRecord(previous, event, input) {
     const success = isAvailabilitySuccess(event);
     if (!input.suppress) {
         const preserveSuppression = !success && previous?.suppressed === true;
+        if (preserveSuppression) {
+            return {
+                ...previous,
+                ...(event.model ? { lastModel: event.model } : {}),
+                ...(event.effort ? { lastEffort: event.effort } : {}),
+                ...(event.stage ? { lastStage: event.stage } : {}),
+                suppressed: true,
+            };
+        }
         return {
             ...common,
             ...(success
@@ -241,22 +247,35 @@ export function suppressedReviewers(state) {
         .filter((record) => record.suppressed)
         .map((record) => record.canonicalId));
 }
-export function pruneExpiredAvailabilitySuppressions(state, nowMs = Date.now()) {
-    const pruned = [];
-    const pruneMap = (records) => Object.fromEntries(Object.entries(records).map(([key, record]) => {
-        if (record.suppressed &&
-            record.retryAfterMs !== undefined &&
-            record.lastFailureAt !== undefined) {
-            const failureAt = Date.parse(record.lastFailureAt);
-            if (Number.isFinite(failureAt) && failureAt + record.retryAfterMs <= nowMs) {
-                pruned.push(key);
-                return [key, { ...record, suppressed: false }];
-            }
+/**
+ * Shared expiry predicate for a suppressed availability record: applies to
+ * both the reviewer/provider store and the opencode-go account store below.
+ * A record clears when its terminal classification is no longer a failure
+ * classification, or when its retry window has elapsed.
+ */
+function suppressionExpired(record, nowMs) {
+    if (!record.suppressed)
+        return false;
+    if (!suppressedRecordStillApplies(record))
+        return true;
+    if (record.retryAfterMs === undefined || record.lastFailureAt === undefined)
+        return false;
+    const failureAt = Date.parse(record.lastFailureAt);
+    return Number.isFinite(failureAt) && failureAt + record.retryAfterMs <= nowMs;
+}
+function pruneRecordMap(records, nowMs, pruned) {
+    return Object.fromEntries(Object.entries(records).map(([key, record]) => {
+        if (suppressionExpired(record, nowMs)) {
+            pruned.push(key);
+            return [key, { ...record, suppressed: false }];
         }
         return [key, record];
     }));
-    const providers = pruneMap(state.providers);
-    const reviewers = pruneMap(state.reviewers);
+}
+export function pruneExpiredAvailabilitySuppressions(state, nowMs = Date.now()) {
+    const pruned = [];
+    const providers = pruneRecordMap(state.providers, nowMs, pruned);
+    const reviewers = pruneRecordMap(state.reviewers, nowMs, pruned);
     if (pruned.length === 0)
         return { state, pruned };
     return {
@@ -269,3 +288,84 @@ export function pruneExpiredAvailabilitySuppressions(state, nowMs = Date.now())
         pruned,
     };
 }
+// --- opencode-go multi-account cooldown store (user-scoped, cross-repo) ---
+export const OPENCODE_ACCOUNT_AVAILABILITY_SCHEMA_VERSION = 1;
+export function opencodeAccountAvailabilityPath() {
+    return path.join(getStateRoot(), "opencode-account-availability.json");
+}
+function emptyOpencodeAccountAvailability(now = new Date().toISOString()) {
+    return {
+        schemaVersion: OPENCODE_ACCOUNT_AVAILABILITY_SCHEMA_VERSION,
+        updatedAt: now,
+        accounts: {},
+    };
+}
+export function loadOpencodeAccountAvailability() {
+    const file = opencodeAccountAvailabilityPath();
+    if (!existsSync(file))
+        return emptyOpencodeAccountAvailability();
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (!isRecord(parsed) ||
+            parsed.schemaVersion !== OPENCODE_ACCOUNT_AVAILABILITY_SCHEMA_VERSION) {
+            return emptyOpencodeAccountAvailability();
+        }
+        return {
+            schemaVersion: OPENCODE_ACCOUNT_AVAILABILITY_SCHEMA_VERSION,
+            updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : new Date().toISOString(),
+            accounts: normalizeRecordMap(parsed.accounts),
+        };
+    }
+    catch {
+        return emptyOpencodeAccountAvailability();
+    }
+}
+function saveOpencodeAccountAvailability(state) {
+    const file = opencodeAccountAvailabilityPath();
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeJsonFileAtomic(file, state);
+}
+export function isOpencodeAccountSuppressed(state, canonicalId) {
+    return state.accounts[canonicalId]?.suppressed === true;
+}
+export function recordOpencodeAccountAvailability(canonicalId, event) {
+    const at = event.at ?? new Date().toISOString();
+    const current = loadOpencodeAccountAvailability();
+    const accounts = { ...current.accounts };
+    accounts[canonicalId] = {
+        canonicalId,
+        provider: "opencode",
+        terminalClassification: event.terminalClassification ?? "provider-limit-reached",
+        ...(event.failureCode ? { failureCode: event.failureCode } : {}),
+        ...(event.limitWindow ? { limitWindow: event.limitWindow } : {}),
+        ...(event.retryAfterMs === undefined ? {} : { retryAfterMs: event.retryAfterMs }),
+        lastFailureAt: at,
+        suppressed: true,
+        suppressionScope: "provider",
+        suppressedAt: at,
+    };
+    const next = {
+        schemaVersion: OPENCODE_ACCOUNT_AVAILABILITY_SCHEMA_VERSION,
+        updatedAt: at,
+        accounts,
+    };
+    saveOpencodeAccountAvailability(next);
+    return next;
+}
+export function recordOpencodeAccountAvailabilityWithLock(canonicalId, event) {
+    return withLock("user", () => recordOpencodeAccountAvailability(canonicalId, event));
+}
+export function pruneExpiredOpencodeAccountSuppressions(state, nowMs = Date.now()) {
+    const pruned = [];
+    const accounts = pruneRecordMap(state.accounts, nowMs, pruned);
+    if (pruned.length === 0)
+        return { state, pruned };
+    return {
+        state: {
+            ...state,
+            updatedAt: new Date(nowMs).toISOString(),
+            accounts,
+        },
+        pruned,
+    };
+}

package/dist/esm/review/delivery-verifier.d.ts

@@ -0,0 +1,27 @@
+import { executeAllowedWpCommand } from "#trust/command-runner.js";
+import type { ReviewTargetCheckout } from "#review/execution/review-checkout.js";
+export interface ReviewGateVerificationCommand {
+    readonly command: string;
+    readonly outcome: "passed" | "failed" | "timed-out" | "deferred";
+    readonly durationMs: number;
+    readonly exitCode: number | null;
+    readonly signal?: string;
+}
+export interface ReviewGateVerification {
+    readonly status: "passed" | "failed";
+    readonly commands: readonly ReviewGateVerificationCommand[];
+    readonly failureCode?: string;
+    readonly logPath?: string;
+}
+export interface VerifyDeliveryGatesInput {
+    readonly purpose: "plan" | "delivery";
+    readonly blueprintContent: string;
+    readonly projectRoot: string;
+    readonly gateId: string;
+    readonly checkout: ReviewTargetCheckout;
+    readonly signal?: AbortSignal;
+    readonly executeCommand?: typeof executeAllowedWpCommand;
+}
+export declare function verifyDeliveryPromotionGates(input: VerifyDeliveryGatesInput): ReviewGateVerification | undefined;
+export declare function verificationPromptSummary(verification: ReviewGateVerification | undefined): string | undefined;
+export declare function verificationArtifactSection(verification: ReviewGateVerification | undefined): string;

package/dist/esm/review/delivery-verifier.js

@@ -0,0 +1,115 @@
+import path from "node:path";
+import { executeAllowedWpCommand, relativeCommandLogPath, } from "#trust/command-runner.js";
+import { parseTrustDossier } from "#trust/dossier.js";
+import { parseAllowedWpCommand } from "#trust/gates.js";
+export function verifyDeliveryPromotionGates(input) {
+    if (input.purpose !== "delivery")
+        return undefined;
+    const parsed = parseTrustDossier(input.blueprintContent);
+    if (parsed.violations.length > 0) {
+        if (parsed.violations.length === 1 &&
+            parsed.violations[0]?.section === "Trust Dossier" &&
+            parsed.violations[0]?.message === "missing Trust Dossier section") {
+            return undefined;
+        }
+        return {
+            status: "failed",
+            commands: [],
+            failureCode: "malformed-trust-dossier",
+        };
+    }
+    const gates = parsed.dossier?.gates ?? [];
+    if (gates.length === 0)
+        return undefined;
+    const commands = [];
+    const executeCommand = input.executeCommand ?? executeAllowedWpCommand;
+    const logRoot = path.join(input.projectRoot, ".webpresso", "logs", "delivery-verification", input.gateId);
+    for (const gate of gates) {
+        if (input.signal?.aborted) {
+            return {
+                status: "failed",
+                commands,
+                failureCode: "verification-cancelled",
+            };
+        }
+        if (isApprovalDependentLifecycleGate(gate.command)) {
+            commands.push({
+                command: gate.command,
+                outcome: "deferred",
+                durationMs: 0,
+                exitCode: null,
+            });
+            continue;
+        }
+        const result = executeCommand({
+            command: gate.command,
+            executionRoot: input.checkout.cwd,
+            logRoot,
+            env: { CI: "1", NO_COLOR: "1", WP_FORCE_SOURCE: "1" },
+        });
+        commands.push(publicCommandResult(result));
+        if (result.outcome !== "passed") {
+            return {
+                status: "failed",
+                commands,
+                failureCode: result.failureCode ?? "verification-command-failed",
+                logPath: relativeCommandLogPath(input.projectRoot, result.logPath),
+            };
+        }
+        const changes = input.checkout.changes();
+        if (changes.length > 0) {
+            return {
+                status: "failed",
+                commands,
+                failureCode: "verification-worktree-contaminated",
+                logPath: relativeCommandLogPath(input.projectRoot, result.logPath),
+            };
+        }
+    }
+    return {
+        status: "passed",
+        commands,
+    };
+}
+export function verificationPromptSummary(verification) {
+    if (!verification)
+        return undefined;
+    if (verification.status !== "passed")
+        return undefined;
+    return [
+        "Host verification before outside review: passed.",
+        ...verification.commands.map((command, index) => `${index + 1}. ${command.command}: ${command.outcome === "deferred" ? "deferred until review publication" : "passed"}`),
+    ].join("\n");
+}
+function isApprovalDependentLifecycleGate(command) {
+    try {
+        const [, subcommand, kind] = parseAllowedWpCommand(command);
+        return subcommand === "audit" && kind === "blueprint-lifecycle";
+    }
+    catch {
+        return false;
+    }
+}
+export function verificationArtifactSection(verification) {
+    if (!verification)
+        return "";
+    const lines = [
+        "## Host Verification",
+        "",
+        `Status: ${verification.status}`,
+        ...verification.commands.map((command, index) => `${index + 1}. ${command.command} -> ${command.outcome} (${command.durationMs}ms, exit ${command.exitCode ?? "null"})`),
+        ...(verification.failureCode ? [`Failure code: ${verification.failureCode}`] : []),
+        ...(verification.logPath ? [`Log: ${verification.logPath}`] : []),
+        "",
+    ];
+    return `${lines.join("\n")}\n`;
+}
+function publicCommandResult(result) {
+    return {
+        command: result.command,
+        outcome: result.outcome,
+        durationMs: result.durationMs,
+        exitCode: result.exitCode,
+        ...(result.signal ? { signal: result.signal } : {}),
+    };
+}

package/dist/esm/review/events.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+export declare const MAINTAINER_OVERRIDE_REVIEWER = "maintainer-override";
 export declare const reviewEventSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<2>;
     id: z.ZodString;
@@ -16,12 +17,12 @@ export declare const reviewEventSchema: z.ZodObject<{
     gateId: z.ZodString;
     promptHash: z.ZodString;
     reviewer: z.ZodString;
-    provider: z.ZodEnum<{
+    provider: z.ZodOptional<z.ZodEnum<{
         claude: "claude";
         codex: "codex";
         grok: "grok";
         opencode: "opencode";
-    }>;
+    }>>;
     model: z.ZodOptional<z.ZodString>;
     effort: z.ZodOptional<z.ZodEnum<{
         high: "high";

package/dist/esm/review/events.js

@@ -9,6 +9,14 @@ const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
 const COMMIT_PATTERN = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u;
 const BLUEPRINT_SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*$/u;
 const ARTIFACT_PATH_PATTERN = /^review-artifacts\/[a-zA-Z0-9._-]+\.md$/u;
+// The honest, auditable escape hatch reviewer id. A maintainer override is a
+// HUMAN adjudication (not a machine backend), recorded only by `wp review
+// override` after a real strong-reviewer rejection of the same subject. It
+// satisfies the promotion gate DISTINCTLY (never folded into a strong or
+// OpenCode-Go approval). Defined here — the lowest review-core module — so both
+// the ledger read-time policy below and the lifecycle approval gate share one
+// source of truth without an import cycle.
+export const MAINTAINER_OVERRIDE_REVIEWER = "maintainer-override";
 export const reviewEventSchema = z
     .object({
     schemaVersion: z.literal(2),
@@ -21,7 +29,10 @@ export const reviewEventSchema = z
     gateId: z.string().min(1).max(120),
     promptHash: z.string().regex(SHA256_PATTERN),
     reviewer: z.string().min(1).max(120),
-    provider: z.enum(["claude", "codex", "opencode", "grok"]),
+    // Optional: present for machine-backend reviews (always set by `wp review
+    // gate`/`log`); absent for a human maintainer-override, which has no AI
+    // backend. Descriptive metadata only — no policy keys off `provider`.
+    provider: z.enum(["claude", "codex", "opencode", "grok"]).optional(),
     model: z.string().min(1).max(240).optional(),
     effort: z.enum(["medium", "high"]).optional(),
     stage: z.string().min(1).max(120),
@@ -81,7 +92,7 @@ function orderedEvent(event) {
         gateId: event.gateId,
         promptHash: event.promptHash,
         reviewer: event.reviewer,
-        provider: event.provider,
+        ...(event.provider ? { provider: event.provider } : {}),
         ...(event.model ? { model: event.model } : {}),
         ...(event.effort ? { effort: event.effort } : {}),
         stage: event.stage,
@@ -164,10 +175,19 @@ function isManualMarker(value) {
     // dodge the policy while real gate ids (content hashes) can never collide.
     return value.trim().toLowerCase() === "manual";
 }
+// Reviewers whose manual-stage approvals are legitimate governance decisions,
+// not disguised machine approvals: a plain `human` review and a
+// `maintainer-override` (a maintainer's hand-recorded adjudication). Both are
+// human authority by construction, so a manual marker on their events is
+// expected rather than a policy dodge.
+const HUMAN_LIKE_REVIEWERS = new Set(["human", MAINTAINER_OVERRIDE_REVIEWER]);
+function isHumanLikeReviewer(reviewer) {
+    return HUMAN_LIKE_REVIEWERS.has(canonicalReviewer(reviewer));
+}
 function isManualMachineApproval(event) {
     return (isPolicyApprovalVerdict(event.verdict) &&
         (isManualMarker(event.gateId) || isManualMarker(event.stage)) &&
-        canonicalReviewer(event.reviewer) !== "human");
+        !isHumanLikeReviewer(event.reviewer));
 }
 // `compromisedIds` marks events whose artifact evidence failed integrity
 // verification. They still PARTICIPATE in reviewer supersession — a later