@webpresso/agent-kit 3.1.30 → 3.2.0

package/dist/esm/review/execution/output-policy.js

@@ -23,6 +23,18 @@ export function applyReviewOutputPolicy(value, consumedBytes = 0) {
     }
     return { ok: true, value: sanitized, bytes, totalBytes: consumedBytes + bytes };
 }
+export const REVIEW_ERROR_DETAIL_MAX_CHARS = 400;
+// Bounds and redacts a provider's raw diagnostic text (a JSON envelope's
+// error.message field, or a raw stderr line) before it is retained anywhere.
+// This feeds only the ephemeral gate state file and CLI stdout -- never the
+// durable, git-committed review ledger -- but the same secret redaction that
+// already applies to terminal/progress "result" text applies here too.
+export function sanitizeProviderErrorDetail(value) {
+    const sanitized = sanitizeReviewOutput(value).replace(/\s+/gu, " ").trim();
+    return sanitized.length > REVIEW_ERROR_DETAIL_MAX_CHARS
+        ? `${sanitized.slice(0, REVIEW_ERROR_DETAIL_MAX_CHARS)}…`
+        : sanitized;
+}
 export function canonicalizeProviderFailureCode(value) {
     if (typeof value !== "string")
         return "provider-error";

package/dist/esm/review/execution/review-checkout.js

@@ -1,8 +1,8 @@
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { lstatSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
+import { lstatSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, rmSync, symlinkSync, unlinkSync, writeFileSync, } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 function git(cwd, args, input) {
     return execFileSync("git", [...args], {
         cwd,
@@ -60,12 +60,69 @@ function worktreeFingerprint(cwd) {
     }
     return hash.digest("hex");
 }
-function status(cwd) {
+// Path segments that mark gitignored content as NON-source: derived build
+// outputs a Promotion Gate command (`./bin/wp typecheck`/`test`/etc.)
+// regenerates while self-hosting this repo (`dist/`, `.tshy/`) and the
+// reconstructed dependency tree (`node_modules`, already separately allowlisted
+// via `ignoredPaths` when symlinked — kept here too for depth-safety, e.g. a
+// nested per-workspace-package `node_modules`). A gitignored (`!!`) path whose
+// ANY segment is one of these — at any workspace depth (e.g. `packages/x/dist`,
+// `.tshy/build.log`) — is exempt from the contamination check. Confirmed
+// empirically that the gate commands emit gitignored output exclusively under
+// these roots.
+//
+// SCOPE (deliberate, documented): this verifier enforces the review TARGET's
+// *source* integrity, not its build artifacts. It does not flag writes under a
+// derived/dependency root, because such output can reach neither the caller
+// nor the reviewed source (the checkout is a disposable tmpdir). Everything
+// else stays strict: a tracked mutation (` M `/` D `), a new untracked source
+// file (`?? `), and any NON-derived gitignored write (e.g. a stray `.env`) all
+// still surface.
+const NON_SOURCE_IGNORED_SEGMENTS = new Set(["dist", ".tshy", "node_modules"]);
+function isNonSourceIgnoredPath(relativePath) {
+    return relativePath.split("/").some((segment) => NON_SOURCE_IGNORED_SEGMENTS.has(segment));
+}
+// This repo self-hosts: a Promotion Gate command's first `./bin/wp` invocation
+// triggers wp's own bootstrap build, which runs tshy and then
+// `./bin/wp format --file package.json` — an IDEMPOTENT normalization (e.g.
+// adding a missing trailing newline). Re-running it a second time produces
+// byte-identical output modulo trailing whitespace, so it is not a source
+// mutation. Exempt ONLY that exact shape: a plain, unstaged content
+// modification (` M `) of a file literally named `package.json` whose
+// tracked-vs-working-tree bytes differ solely in trailing whitespace. Any
+// other package.json change (dependency/script/field edits, staged changes,
+// adds, deletes) still fails closed — this check never inspects JSON
+// semantics, only trailing-whitespace-normalized byte equality.
+function isNormalizedPackageJsonModification(cwd, line) {
+    if (!line.startsWith(" M "))
+        return false;
+    const relativePath = line.slice(3);
+    if (basename(relativePath) !== "package.json")
+        return false;
+    try {
+        const working = readFileSync(join(cwd, relativePath), "utf8");
+        const tracked = git(cwd, ["show", `HEAD:${relativePath}`]);
+        return working.replace(/\s+$/u, "") === tracked.replace(/\s+$/u, "");
+    }
+    catch {
+        return false;
+    }
+}
+function status(cwd, ignoredPaths = new Set()) {
     const output = git(cwd, ["status", "--porcelain=v1", "--untracked-files=all", "--ignored"]);
     return output
         .split(/\r?\n/u)
-        .map((line) => line.trimEnd())
-        .filter((line) => line.length > 0);
+        .filter((line) => line.length > 0)
+        .filter((line) => {
+        const relativePath = line.slice(3).replace(/\/$/u, "");
+        if (ignoredPaths.has(relativePath))
+            return false;
+        if (line.startsWith("!!") && isNonSourceIgnoredPath(relativePath))
+            return false;
+        if (isNormalizedPackageJsonModification(cwd, line))
+            return false;
+        return true;
+    });
 }
 function neutralizeSymlinks(directory) {
     for (const entry of readdirSync(directory, { withFileTypes: true })) {
@@ -111,6 +168,7 @@ export function createReviewTargetCheckout(repositoryRoot, targetSha) {
         git(cwd, ["update-ref", "HEAD", baselineHead]);
         if (status(cwd).length > 0)
             throw new Error("review target checkout was not clean at start");
+        const injectedPaths = projectCallerDependencies(repositoryRoot, cwd);
         let cleaned = false;
         return {
             cwd,
@@ -119,7 +177,7 @@ export function createReviewTargetCheckout(repositoryRoot, targetSha) {
             },
             changes: () => {
                 try {
-                    const changes = [...status(cwd)];
+                    const changes = [...status(cwd, injectedPaths)];
                     if (git(cwd, ["rev-parse", "HEAD"]).trim() !== baselineHead) {
                         changes.push("review checkout HEAD changed");
                     }
@@ -145,3 +203,26 @@ export function createReviewTargetCheckout(repositoryRoot, targetSha) {
         throw error;
     }
 }
+function projectCallerDependencies(repositoryRoot, checkoutRoot) {
+    const projected = new Set();
+    const dependencyPath = "node_modules";
+    const callerPath = join(repositoryRoot, dependencyPath);
+    const targetPath = join(checkoutRoot, dependencyPath);
+    try {
+        lstatSync(callerPath);
+    }
+    catch {
+        return projected;
+    }
+    try {
+        lstatSync(targetPath);
+        return projected;
+    }
+    catch {
+        // Missing in the target archive means the caller dependency cache may be
+        // projected for local tooling without overwriting target-owned files.
+    }
+    symlinkSync(callerPath, targetPath, "dir");
+    projected.add(dependencyPath);
+    return projected;
+}

package/dist/esm/review/execution/supervisor.js

@@ -107,6 +107,7 @@ export async function superviseReviewExecution(input, adapter, deps = {}) {
     });
     let status = null;
     let failureCode;
+    let providerErrorDetail;
     let limitWindow;
     let retryAfterMs;
     let result;
@@ -191,6 +192,7 @@ export async function superviseReviewExecution(input, adapter, deps = {}) {
         failureCode = code;
         limitWindow = metadata.limitWindow;
         retryAfterMs = metadata.retryAfterMs;
+        providerErrorDetail = metadata.providerErrorDetail;
         requestTermination();
         finalize();
     };
@@ -249,6 +251,7 @@ export async function superviseReviewExecution(input, adapter, deps = {}) {
             fail("provider-failure", canonicalizeProviderFailureCode(event.code), {
                 ...(event.limitWindow === undefined ? {} : { limitWindow: event.limitWindow }),
                 ...(event.retryAfterMs === undefined ? {} : { retryAfterMs: event.retryAfterMs }),
+                ...(event.message === undefined ? {} : { providerErrorDetail: event.message }),
             });
             return;
         }
@@ -324,6 +327,7 @@ export async function superviseReviewExecution(input, adapter, deps = {}) {
             fail("provider-failure", canonicalizeProviderFailureCode(event.code), {
                 ...(event.limitWindow === undefined ? {} : { limitWindow: event.limitWindow }),
                 ...(event.retryAfterMs === undefined ? {} : { retryAfterMs: event.retryAfterMs }),
+                ...(event.message === undefined ? {} : { providerErrorDetail: event.message }),
             });
         }
     };
@@ -425,6 +429,7 @@ export async function superviseReviewExecution(input, adapter, deps = {}) {
             markerMatched,
             ...(result === undefined ? {} : { result }),
             ...(terminalFailureCode === undefined ? {} : { failureCode: terminalFailureCode }),
+            ...(providerErrorDetail === undefined ? {} : { providerErrorDetail }),
             ...(limitWindow === undefined ? {} : { limitWindow }),
             ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
             summaryPath: artifacts.summaryPath,

package/dist/esm/review/execution/types.d.ts

@@ -19,6 +19,12 @@ export interface ReviewRunInput {
     readonly cwd?: string;
     readonly registryRoot?: string;
     readonly signal?: AbortSignal;
+    /**
+     * Isolated opencode auth store directory for this spawn. When set, the
+     * opencode adapter injects it as `XDG_DATA_HOME` so the child reads a
+     * per-account `auth.json` instead of the user's global credential store.
+     */
+    readonly authDataDir?: string;
 }
 export interface ReviewInvocation {
     readonly command: string;
@@ -41,6 +47,7 @@ export type ReviewAdapterEvent = {
 } | {
     readonly kind: "failure";
     readonly code: string;
+    readonly message?: string;
     readonly limitWindow?: ReviewLimitWindow;
     readonly retryAfterMs?: number;
 } | {
@@ -70,6 +77,7 @@ export interface ReviewRunSummary {
     readonly markerMatched: boolean | null;
     readonly result?: string;
     readonly failureCode?: string;
+    readonly providerErrorDetail?: string;
     readonly limitWindow?: ReviewLimitWindow;
     readonly retryAfterMs?: number;
     readonly summaryPath: string;

package/dist/esm/review/opencode-account.d.ts

@@ -0,0 +1,24 @@
+import { type OpencodeAccountAvailabilityState } from "./availability.js";
+export interface OpencodeAccount {
+    readonly id: string;
+    readonly secretName: string;
+    readonly key: string;
+}
+export interface OpencodeAccountSelection {
+    readonly account: OpencodeAccount;
+    readonly cooled: boolean;
+    readonly waitMs?: number;
+}
+/**
+ * Discover opencode-go accounts from Doppler-sourced secrets shaped
+ * `OPENCODE_GO_KEY_<ID>`. Sorted by id ascending, de-duplicated by id.
+ */
+export declare function resolveOpencodeAccounts(secrets: Readonly<Record<string, string>>): readonly OpencodeAccount[];
+export declare function opencodeAccountCanonicalId(id: string): string;
+export declare function opencodeAccountDataDir(id: string, stateRoot?: string): string;
+/**
+ * Select the account to use for the next opencode-go invocation. Callers must
+ * prune expired suppressions in `state` before calling this (via
+ * `pruneExpiredOpencodeAccountSuppressions`).
+ */
+export declare function selectActiveOpencodeAccount(accounts: readonly OpencodeAccount[], state: OpencodeAccountAvailabilityState, nowMs?: number): OpencodeAccountSelection | undefined;

package/dist/esm/review/opencode-account.js

@@ -0,0 +1,68 @@
+import path from "node:path";
+import { getStateRoot } from "#paths/state-root.js";
+import { isOpencodeAccountSuppressed, } from "./availability.js";
+const OPENCODE_GO_KEY_PATTERN = /^OPENCODE_GO_KEY_([A-Za-z0-9]+)$/;
+/**
+ * Discover opencode-go accounts from Doppler-sourced secrets shaped
+ * `OPENCODE_GO_KEY_<ID>`. Sorted by id ascending, de-duplicated by id.
+ */
+export function resolveOpencodeAccounts(secrets) {
+    const byId = new Map();
+    for (const [secretName, key] of Object.entries(secrets)) {
+        if (!key || key.trim().length === 0)
+            continue;
+        const match = OPENCODE_GO_KEY_PATTERN.exec(secretName);
+        if (!match?.[1])
+            continue;
+        const id = match[1].toLowerCase();
+        if (!byId.has(id))
+            byId.set(id, { id, secretName, key });
+    }
+    return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+export function opencodeAccountCanonicalId(id) {
+    return `opencode-go:${id}`;
+}
+export function opencodeAccountDataDir(id, stateRoot) {
+    return path.join(stateRoot ?? getStateRoot(), "opencode-accounts", id);
+}
+function suppressionExpiryMs(state, canonicalId) {
+    const record = state.accounts[canonicalId];
+    if (record === undefined || record.lastFailureAt === undefined)
+        return undefined;
+    const failureAt = Date.parse(record.lastFailureAt);
+    if (!Number.isFinite(failureAt))
+        return undefined;
+    return failureAt + (record.retryAfterMs ?? 0);
+}
+function pickSoonestExpiring(accounts, state, nowMs) {
+    const withExpiry = accounts.map((account) => ({
+        account,
+        expiresAt: suppressionExpiryMs(state, opencodeAccountCanonicalId(account.id)) ??
+            Number.POSITIVE_INFINITY,
+    }));
+    // `accounts` is non-empty whenever this is called, so a no-initial-value
+    // reduce is safe and keeps the accumulator type undefined-free.
+    const soonest = withExpiry.reduce((min, candidate) => candidate.expiresAt < min.expiresAt ? candidate : min);
+    const waitMs = Number.isFinite(soonest.expiresAt)
+        ? Math.max(0, soonest.expiresAt - nowMs)
+        : undefined;
+    return {
+        account: soonest.account,
+        cooled: true,
+        ...(waitMs === undefined ? {} : { waitMs }),
+    };
+}
+/**
+ * Select the account to use for the next opencode-go invocation. Callers must
+ * prune expired suppressions in `state` before calling this (via
+ * `pruneExpiredOpencodeAccountSuppressions`).
+ */
+export function selectActiveOpencodeAccount(accounts, state, nowMs = Date.now()) {
+    if (accounts.length === 0)
+        return undefined;
+    const available = accounts.find((account) => !isOpencodeAccountSuppressed(state, opencodeAccountCanonicalId(account.id)));
+    if (available)
+        return { account: available, cooled: false };
+    return pickSoonestExpiring(accounts, state, nowMs);
+}

package/dist/esm/review/opencode-auth.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Resolve opencode's `auth.json` path from an XDG-style data-home env var.
+ *
+ * Mirrors the resolver in `src/cli/commands/dash/opencode-db.ts`
+ * (`opencodeDatabasePath`), but targets `opencode/auth.json` instead of
+ * `opencode/opencode.db`.
+ */
+export declare function opencodeAuthPath(env?: Readonly<Record<string, string | undefined>>, home?: string): string;
+export interface MaterializeOpencodeGoAuthOptions {
+    readonly dataDir?: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly home?: string;
+}
+export interface MaterializeOpencodeGoAuthResult {
+    readonly path: string;
+    readonly wrote: boolean;
+}
+/**
+ * Read the `opencode-go` API key currently on disk, or `undefined` when the
+ * store is missing, corrupt, or holds no `opencode-go` entry.
+ *
+ * Callers use this to identify which account is currently materialized by
+ * matching the value against their own resolved account list — that keeps the
+ * "which account is active" question answerable without persisting extra state.
+ * Never throws.
+ */
+export declare function readOpencodeGoKey(options?: MaterializeOpencodeGoAuthOptions): string | undefined;
+/**
+ * Merge an `opencode-go` API-key entry into opencode's `auth.json`, preserving
+ * every other provider entry already on disk. Never throws on a missing,
+ * unreadable, or corrupt existing file — that state is treated as `{}`.
+ */
+export declare function materializeOpencodeGoAuth(key: string, options?: MaterializeOpencodeGoAuthOptions): MaterializeOpencodeGoAuthResult;

package/dist/esm/review/opencode-auth.js

@@ -0,0 +1,79 @@
+import { mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { writeJsonFileAtomic } from "#shared-utils/write-json-file.js";
+/**
+ * Resolve opencode's `auth.json` path from an XDG-style data-home env var.
+ *
+ * Mirrors the resolver in `src/cli/commands/dash/opencode-db.ts`
+ * (`opencodeDatabasePath`), but targets `opencode/auth.json` instead of
+ * `opencode/opencode.db`.
+ */
+export function opencodeAuthPath(env = process.env, home = homedir()) {
+    const dataHome = env["XDG_DATA_HOME"]?.trim() || join(home, ".local", "share");
+    return join(dataHome, "opencode", "auth.json");
+}
+function resolveAuthPath(options) {
+    if (options.dataDir !== undefined) {
+        return join(options.dataDir, "opencode", "auth.json");
+    }
+    return opencodeAuthPath(options.env, options.home);
+}
+function readExistingAuth(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+function isSameOpencodeGoEntry(entry, key) {
+    if (entry === null || typeof entry !== "object")
+        return false;
+    const candidate = entry;
+    return candidate["type"] === "api" && candidate["key"] === key;
+}
+/**
+ * Read the `opencode-go` API key currently on disk, or `undefined` when the
+ * store is missing, corrupt, or holds no `opencode-go` entry.
+ *
+ * Callers use this to identify which account is currently materialized by
+ * matching the value against their own resolved account list — that keeps the
+ * "which account is active" question answerable without persisting extra state.
+ * Never throws.
+ */
+export function readOpencodeGoKey(options = {}) {
+    const entry = readExistingAuth(resolveAuthPath(options))["opencode-go"];
+    if (entry === null || typeof entry !== "object")
+        return undefined;
+    const candidate = entry;
+    return typeof candidate["key"] === "string" ? candidate["key"] : undefined;
+}
+/**
+ * Merge an `opencode-go` API-key entry into opencode's `auth.json`, preserving
+ * every other provider entry already on disk. Never throws on a missing,
+ * unreadable, or corrupt existing file — that state is treated as `{}`.
+ */
+export function materializeOpencodeGoAuth(key, options = {}) {
+    const path = resolveAuthPath(options);
+    const existing = readExistingAuth(path);
+    if (isSameOpencodeGoEntry(existing["opencode-go"], key)) {
+        return { path, wrote: false };
+    }
+    const entry = { type: "api", key };
+    const next = { ...existing, "opencode-go": entry };
+    mkdirSync(dirname(path), { recursive: true });
+    writeJsonFileAtomic(path, next, { writeFileOptions: { mode: 0o600 } });
+    return { path, wrote: true };
+}

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

@@ -12,7 +12,19 @@ interface TreeEntry {
     readonly path: Buffer;
 }
 export declare function resolveReviewCommit(cwd: string, ref: string): string;
+/**
+ * Repo-relative paths with uncommitted changes (staged, unstaged, or
+ * untracked) that are NOT review evidence (reviews.md / review-events.jsonl /
+ * review-artifacts/*.md — see isReviewEvidenceRelativePath). A `wp-git-tree-v1`
+ * subject digest is computed purely from the committed tree at a ref, so any
+ * non-evidence path here means the working tree diverges from what that
+ * digest — and any approval bound to it — actually covers. Review evidence is
+ * excluded because the gate's own artifact/ledger writes routinely leave the
+ * tree dirty between reruns without representing unreviewed content.
+ */
+export declare function findUnreviewedWorkingTreeChanges(cwd: string): readonly string[];
 declare function isExcludedReviewEnvelope(entry: TreeEntry, blueprintRoot: Buffer): boolean;
+export declare function isReviewEvidenceRelativePath(value: string): boolean;
 declare function isReviewEvidencePath(entry: TreeEntry): boolean;
 declare function updateField(hash: Hash, value: Buffer | string): void;
 export declare function createDeliverySubjectAtRef(cwd: string, ref: string, blueprintSlug: string, blueprintPath?: string): ReviewSubject;

package/dist/esm/review/subject.js

@@ -39,6 +39,43 @@ export function resolveReviewCommit(cwd, ref) {
     }
     return commit;
 }
+/**
+ * Repo-relative paths with uncommitted changes (staged, unstaged, or
+ * untracked) that are NOT review evidence (reviews.md / review-events.jsonl /
+ * review-artifacts/*.md — see isReviewEvidenceRelativePath). A `wp-git-tree-v1`
+ * subject digest is computed purely from the committed tree at a ref, so any
+ * non-evidence path here means the working tree diverges from what that
+ * digest — and any approval bound to it — actually covers. Review evidence is
+ * excluded because the gate's own artifact/ledger writes routinely leave the
+ * tree dirty between reruns without representing unreviewed content.
+ */
+export function findUnreviewedWorkingTreeChanges(cwd) {
+    const output = gitBuffer(cwd, [
+        "status",
+        "--porcelain=v1",
+        "--untracked-files=all",
+        "--ignored=no",
+        "-z",
+    ]).toString("utf8");
+    const records = output.split("\0").filter((record) => record.length > 0);
+    const paths = new Set();
+    for (let index = 0; index < records.length; index += 1) {
+        const record = records[index];
+        const statusCode = record.slice(0, 2);
+        paths.add(record.slice(3));
+        if (/[RC]/u.test(statusCode)) {
+            // Rename/copy porcelain records are followed by the original path.
+            const originalPath = records[index + 1];
+            if (originalPath !== undefined) {
+                paths.add(originalPath);
+                index += 1;
+            }
+        }
+    }
+    return [...paths]
+        .filter((relativePath) => !isReviewEvidenceRelativePath(relativePath))
+        .toSorted();
+}
 function parseTree(cwd, commit) {
     const output = gitBuffer(cwd, ["ls-tree", "-r", "-z", "--full-tree", commit]);
     const entries = [];
@@ -74,31 +111,40 @@ function parseTree(cwd, commit) {
         throw new Error("Truncated git ls-tree output.");
     return entries.sort((left, right) => Buffer.compare(left.path, right.path));
 }
-function findBlueprintRoot(entries, blueprintSlug, blueprintPath) {
+function isRegularBlob(entry) {
+    return entry.type === "blob" && /^100(?:644|755)$/u.test(entry.mode.toString("ascii"));
+}
+function findBlueprintDocument(entries, blueprintSlug, blueprintPath) {
     if (blueprintPath) {
         const normalized = blueprintPath.replaceAll("\\", "/");
         const target = Buffer.from(normalized, "utf8");
-        const matches = entries.filter((entry) => entry.path.equals(target));
-        if (matches.length === 1 && normalized.endsWith("/_overview.md")) {
-            return target.subarray(0, target.length - Buffer.byteLength("_overview.md"));
+        const matches = entries.filter((entry) => entry.path.equals(target) && isRegularBlob(entry));
+        if (matches.length === 1 && normalized.endsWith(".md")) {
+            return matches[0];
         }
     }
-    const suffix = Buffer.from(`/${blueprintSlug}/_overview.md`, "utf8");
+    const folderSuffix = `/${blueprintSlug}/_overview.md`;
+    const flatSuffix = `/${blueprintSlug}.md`;
     const matches = entries.filter((entry) => {
         const normalized = entry.path.toString("utf8");
-        const segments = normalized.split("/");
-        return (segments[0] === "blueprints" &&
-            BLUEPRINT_STATUSES.has(segments[1] ?? "") &&
-            entry.path.subarray(-suffix.length).equals(suffix));
+        const suffix = normalized.endsWith(folderSuffix)
+            ? folderSuffix
+            : normalized.endsWith(flatSuffix)
+                ? flatSuffix
+                : undefined;
+        const lifecycle = suffix ? normalized.slice(0, -suffix.length).split("/").at(-1) : undefined;
+        return isRegularBlob(entry) && BLUEPRINT_STATUSES.has(lifecycle ?? "");
     });
     if (matches.length !== 1) {
         throw new Error(`Expected one tracked blueprint ${blueprintSlug} at target commit, found ${matches.length}.`);
     }
-    const overview = matches[0].path;
-    return overview.subarray(0, overview.length - Buffer.byteLength("_overview.md"));
+    return matches[0];
 }
-function isRegularBlob(entry) {
-    return entry.type === "blob" && /^100(?:644|755)$/u.test(entry.mode.toString("ascii"));
+function blueprintEvidenceRoot(documentPath) {
+    const value = documentPath.toString("utf8");
+    if (!value.endsWith("/_overview.md"))
+        return null;
+    return documentPath.subarray(0, documentPath.length - Buffer.byteLength("_overview.md"));
 }
 function isExcludedReviewEnvelope(entry, blueprintRoot) {
     if (!isRegularBlob(entry) ||
@@ -114,10 +160,10 @@ function isExcludedReviewEnvelope(entry, blueprintRoot) {
     const artifactName = relative.slice(prefix.length);
     return artifactName.length > 3 && !artifactName.includes("/") && artifactName.endsWith(".md");
 }
-function isReviewEvidencePath(entry) {
-    if (!isRegularBlob(entry))
-        return false;
-    const value = entry.path.toString("utf8");
+// String-based counterpart of isReviewEvidencePath, shared with callers that
+// only have a repo-relative path (no TreeEntry) — currently the working-tree
+// divergence check in findUnreviewedWorkingTreeChanges below.
+export function isReviewEvidenceRelativePath(value) {
     if (!/^blueprints\/(?:[^/]+\/)*[^/]+\//u.test(value))
         return false;
     if (/(?:^|\/)reviews\.md$/u.test(value) || /(?:^|\/)review-events\.jsonl$/u.test(value)) {
@@ -125,6 +171,11 @@ function isReviewEvidencePath(entry) {
     }
     return /(?:^|\/)review-artifacts\/[^/]+\.md$/u.test(value);
 }
+function isReviewEvidencePath(entry) {
+    if (!isRegularBlob(entry))
+        return false;
+    return isReviewEvidenceRelativePath(entry.path.toString("utf8"));
+}
 function loadBlobContents(cwd, entries) {
     const blobs = entries.filter((entry) => entry.type === "blob");
     if (blobs.length === 0)
@@ -195,11 +246,13 @@ function readTreeAtRef(cwd, ref) {
 }
 export function createDeliverySubjectAtRef(cwd, ref, blueprintSlug, blueprintPath) {
     const { commit, objectFormat, entries: allEntries } = readTreeAtRef(cwd, ref);
-    const blueprintRoot = findBlueprintRoot(allEntries, blueprintSlug, blueprintPath);
+    const document = findBlueprintDocument(allEntries, blueprintSlug, blueprintPath);
+    const blueprintRoot = blueprintEvidenceRoot(document.path);
     // Exclude review evidence for the owning blueprint AND for every other blueprint
     // (the same global exclusion source snapshots use): recording evidence under an
     // unrelated blueprint must not invalidate an otherwise-identical delivery review.
-    const entries = allEntries.filter((entry) => !isExcludedReviewEnvelope(entry, blueprintRoot) && !isReviewEvidencePath(entry));
+    const entries = allEntries.filter((entry) => (blueprintRoot === null || !isExcludedReviewEnvelope(entry, blueprintRoot)) &&
+        !isReviewEvidencePath(entry));
     return {
         scheme: "wp-git-tree-v1",
         digest: hashTreeEntries(cwd, entries, objectFormat, DELIVERY_DOMAIN),
@@ -413,9 +466,8 @@ export function legacyNormalizePlanSubjectContent(content) {
 function planSubjectAtRef(cwd, ref, blueprintSlug, normalize, blueprintPath) {
     const commit = resolveReviewCommit(cwd, ref);
     const entries = parseTree(cwd, commit);
-    const blueprintRoot = findBlueprintRoot(entries, blueprintSlug, blueprintPath);
-    const overviewPath = Buffer.concat([blueprintRoot, Buffer.from("_overview.md", "ascii")]);
-    const overview = entries.find((entry) => entry.path.equals(overviewPath));
+    const overview = findBlueprintDocument(entries, blueprintSlug, blueprintPath);
+    const overviewPath = overview.path;
     if (!overview || overview.type !== "blob") {
         throw new Error("Tracked blueprint overview is not a blob.");
     }

package/dist/esm/runtime/opencode-account-materializer.d.ts

@@ -0,0 +1,34 @@
+import { type OpencodeAccount } from "#review/opencode-account.js";
+import { resolveRuntimeEnvironment } from "./executor.js";
+export type OpencodeAccountsResolution = {
+    readonly ok: true;
+    readonly accounts: readonly OpencodeAccount[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export interface ResolveOpencodeAccountsGracefullyInput {
+    readonly cwd: string;
+    /**
+     * Secret profile to resolve through — REQUIRED, never optional.
+     *
+     * Without it `resolveRuntimeEnvironment` passes no environment selector and
+     * the secret manager falls back to its own ambient, path-keyed config
+     * (Doppler's per-directory scopes, Infisical's discovered `.infisical.json`).
+     * That resolves only in a checkout that happens to sit under the scoped path,
+     * so discovery silently yields zero accounts in every managed worktree, CI
+     * clone, and fresh checkout — a failure mode that is invisible because callers
+     * degrade gracefully. Keeping this required makes that class of bug a compile
+     * error instead of a silent runtime degradation. Callers pass
+     * `resolveAgentSecretProfile(env)`.
+     */
+    readonly secretProfile: string;
+    readonly resolveRuntimeEnvironment?: typeof resolveRuntimeEnvironment;
+}
+/**
+ * Resolve `OPENCODE_GO_KEY_*` secrets into accounts without ever throwing.
+ * On any resolution failure (missing profile, secret-manager error, empty
+ * result), returns a failure reason derived only from the error's own
+ * message/type — never from a secret value.
+ */
+export declare function resolveOpencodeAccountsGracefully(input: ResolveOpencodeAccountsGracefullyInput): OpencodeAccountsResolution;

package/dist/esm/runtime/opencode-account-materializer.js

@@ -0,0 +1,33 @@
+import { resolveOpencodeAccounts } from "#review/opencode-account.js";
+import { resolveRuntimeEnvironment } from "./executor.js";
+function describeError(error) {
+    if (error instanceof Error)
+        return `${error.name}: ${error.message}`;
+    return typeof error === "string" ? error : "unknown error";
+}
+/**
+ * Resolve `OPENCODE_GO_KEY_*` secrets into accounts without ever throwing.
+ * On any resolution failure (missing profile, secret-manager error, empty
+ * result), returns a failure reason derived only from the error's own
+ * message/type — never from a secret value.
+ */
+export function resolveOpencodeAccountsGracefully(input) {
+    const resolveEnv = input.resolveRuntimeEnvironment ?? resolveRuntimeEnvironment;
+    let secrets;
+    try {
+        secrets = resolveEnv({
+            cwd: input.cwd,
+            profile: "secrets-only",
+            secretProfile: input.secretProfile,
+            environment: input.secretProfile,
+        });
+    }
+    catch (error) {
+        return { ok: false, reason: describeError(error) };
+    }
+    const accounts = resolveOpencodeAccounts(secrets);
+    if (accounts.length === 0) {
+        return { ok: false, reason: "no OPENCODE_GO_KEY_* secrets found" };
+    }
+    return { ok: true, accounts };
+}