@webpresso/agent-kit 3.1.30 → 3.2.0

package/dist/esm/cli/commands/init/untracked-collision.d.ts

@@ -0,0 +1,14 @@
+import type { ConvergeUnit } from "./convergence.js";
+export type CollisionResolution = "none" | "tracked" | "removed-identical" | "removed-owned";
+export interface CollisionResult {
+    readonly ok: boolean;
+    readonly resolution?: CollisionResolution;
+    readonly error?: string;
+}
+export interface ResolveCollisionOptions {
+    readonly unit: ConvergeUnit;
+    readonly desiredContent: string | Uint8Array;
+    /** Compatibility input only. Unknown content remains protected when true. */
+    readonly force?: boolean;
+}
+export declare function resolveUntrackedCollision(options: ResolveCollisionOptions): CollisionResult;

package/dist/esm/cli/commands/init/untracked-collision.js

@@ -0,0 +1,42 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, readFileSync, rmSync } from "node:fs";
+const GIT_TIMEOUT_MS = 15_000;
+const OWNERSHIP_MARKER = /^\uFEFF?[ \t]*(?:#|\/\/|\/\*|<!--|")?[ \t]*(?:>>> managed by webpresso\b|Generated by webpresso\b)/iu;
+function git(repoRoot, args) {
+    const result = spawnSync("git", [...args], {
+        cwd: repoRoot,
+        encoding: "utf8",
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer: 1024 * 1024,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { ok: result.status === 0 && !result.error };
+}
+export function resolveUntrackedCollision(options) {
+    const { unit } = options;
+    if (!existsSync(unit.targetPath))
+        return { ok: true, resolution: "none" };
+    if (git(unit.repoRoot, ["ls-files", "--error-unmatch", "--", unit.gitPath]).ok) {
+        return { ok: true, resolution: "tracked" };
+    }
+    if (!lstatSync(unit.targetPath).isFile()) {
+        return {
+            ok: false,
+            error: `Untracked collision at ${unit.gitPath} is not a regular file; move it aside and rerun wp setup.`,
+        };
+    }
+    const current = readFileSync(unit.targetPath);
+    if (current.equals(Buffer.from(options.desiredContent))) {
+        rmSync(unit.targetPath);
+        return { ok: true, resolution: "removed-identical" };
+    }
+    if (OWNERSHIP_MARKER.test(current.toString("utf8"))) {
+        rmSync(unit.targetPath);
+        return { ok: true, resolution: "removed-owned" };
+    }
+    return {
+        ok: false,
+        error: `Unknown untracked content blocks ${unit.gitPath}; it was preserved${options.force ? " despite --force" : ""}. ` +
+            "Move or commit the file, then rerun wp setup.",
+    };
+}

package/dist/esm/cli/commands/opencode-rotate.d.ts

@@ -0,0 +1,49 @@
+import { resolveOpencodeAccountsGracefully } from "#runtime/opencode-account-materializer.js";
+/** The `--wp-rotate` flag, namespaced like `--wp-permission-mode`. */
+export declare const OPENCODE_ROTATE_FLAG = "--wp-rotate";
+export type OpencodeRotateOutcome = 
+/** The previously-active account was cooled and a different one is now active. */
+{
+    readonly kind: "rotated";
+    readonly cooledAccountId: string;
+    readonly activeAccountId: string;
+    readonly activeIsCooled: boolean;
+    readonly waitMs?: number;
+}
+/** The on-disk key matched no known account, so nothing was cooled. */
+ | {
+    readonly kind: "reselected";
+    readonly activeAccountId: string;
+    readonly activeIsCooled: boolean;
+}
+/** Fewer than two accounts are provisioned — there is nowhere to rotate to. */
+ | {
+    readonly kind: "single-account";
+}
+/** Secrets could not be resolved; the caller must still launch normally. */
+ | {
+    readonly kind: "unavailable";
+    readonly reason: string;
+};
+export interface OpencodeRotateDeps {
+    readonly resolveOpencodeAccounts?: typeof resolveOpencodeAccountsGracefully;
+    readonly readActiveKey?: () => string | undefined;
+    readonly materializeGlobalOpencodeAuth?: (key: string) => void;
+    readonly recordCooldown?: (canonicalId: string) => Promise<unknown>;
+}
+/**
+ * Cool the currently-materialized opencode-go account and materialize the next
+ * usable one into the global `auth.json`.
+ *
+ * The active account is identified by reading the global store back and matching
+ * its key against the resolved accounts — `wp` wrote that value itself, so this
+ * stays correct without persisting a separate "last launched" record. When the
+ * key matches nothing (a hand-edited store, or a fresh machine), the rotation
+ * degrades to a plain reselect and cools nothing, because cooling an account we
+ * cannot identify would suppress the wrong one.
+ *
+ * Never throws: the caller launches the TUI regardless of the outcome.
+ */
+export declare function rotateActiveOpencodeAccount(cwd: string, secretProfile: string, deps?: OpencodeRotateDeps): Promise<OpencodeRotateOutcome>;
+/** Human-readable lines describing a rotation outcome, in print order. */
+export declare function describeOpencodeRotate(outcome: OpencodeRotateOutcome): readonly string[];

package/dist/esm/cli/commands/opencode-rotate.js

@@ -0,0 +1,135 @@
+import { loadOpencodeAccountAvailability, pruneExpiredOpencodeAccountSuppressions, recordOpencodeAccountAvailabilityWithLock, } from "#review/availability.js";
+import { opencodeAccountCanonicalId, selectActiveOpencodeAccount, } from "#review/opencode-account.js";
+import { materializeOpencodeGoAuth, readOpencodeGoKey } from "#review/opencode-auth.js";
+import { resolveOpencodeAccountsGracefully } from "#runtime/opencode-account-materializer.js";
+/** The `--wp-rotate` flag, namespaced like `--wp-permission-mode`. */
+export const OPENCODE_ROTATE_FLAG = "--wp-rotate";
+/**
+ * A manual rotation has no provider response to parse a reset window from, so it
+ * assumes the shortest real OpenCode Go window (5 hours). Recording no window at
+ * all would leave the record permanently suppressed — `suppressionExpired` only
+ * clears a record that carries `retryAfterMs` — so every rotated account would
+ * be cooled forever and selection would degrade to "first account" again. A
+ * too-short guess is self-correcting: the account is retried, and if it is still
+ * capped the gate (or the next rotation) simply cools it again.
+ */
+const MANUAL_ROTATION_COOLDOWN_MS = 5 * 60 * 60 * 1_000;
+function coolActiveAccount(canonicalId, deps) {
+    if (deps.recordCooldown)
+        return deps.recordCooldown(canonicalId);
+    // Same event shape the review gate records on an in-flight usage limit, so
+    // both writers produce identical, mutually-readable cooldown records.
+    return recordOpencodeAccountAvailabilityWithLock(canonicalId, {
+        failureCode: "opencode-go-usage-limit",
+        terminalClassification: "provider-limit-reached",
+        limitWindow: "unknown",
+        retryAfterMs: MANUAL_ROTATION_COOLDOWN_MS,
+    });
+}
+/**
+ * Pick the account to make active next.
+ *
+ * `excludeId` is the account we just cooled. It is filtered out here rather
+ * than relied upon coming back suppressed from the store: that keeps rotation
+ * correct even if the cooldown write is slow, contended, or fails outright, and
+ * removes a read-after-write dependency from the hot path.
+ */
+function selectNextAccount(accounts, excludeId) {
+    const pruned = pruneExpiredOpencodeAccountSuppressions(loadOpencodeAccountAvailability());
+    const candidates = excludeId === undefined ? accounts : accounts.filter((account) => account.id !== excludeId);
+    // Callers guarantee at least one candidate: rotation needs >= 2 accounts, and
+    // the no-exclude path is only reached with a non-empty list.
+    const pool = candidates.length > 0 ? candidates : accounts;
+    const selection = selectActiveOpencodeAccount(pool, pruned.state);
+    return selection ?? { account: pool[0], cooled: false };
+}
+/**
+ * Cool the currently-materialized opencode-go account and materialize the next
+ * usable one into the global `auth.json`.
+ *
+ * The active account is identified by reading the global store back and matching
+ * its key against the resolved accounts — `wp` wrote that value itself, so this
+ * stays correct without persisting a separate "last launched" record. When the
+ * key matches nothing (a hand-edited store, or a fresh machine), the rotation
+ * degrades to a plain reselect and cools nothing, because cooling an account we
+ * cannot identify would suppress the wrong one.
+ *
+ * Never throws: the caller launches the TUI regardless of the outcome.
+ */
+export async function rotateActiveOpencodeAccount(cwd, secretProfile, deps = {}) {
+    try {
+        return await rotateOrThrow(cwd, secretProfile, deps);
+    }
+    catch (error) {
+        // The cooldown write takes the user-scope lock the review gate also holds
+        // (contention rejects after a few short retries) and the auth write can fail
+        // with EACCES/ENOSPC. Neither may abort the launch, so both degrade to the
+        // same "carry on and launch" outcome the sibling select path uses.
+        return { kind: "unavailable", reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function rotateOrThrow(cwd, secretProfile, deps) {
+    const resolution = (deps.resolveOpencodeAccounts ?? resolveOpencodeAccountsGracefully)({
+        cwd,
+        secretProfile,
+    });
+    if (!resolution.ok)
+        return { kind: "unavailable", reason: resolution.reason };
+    const accounts = resolution.accounts;
+    if (accounts.length < 2)
+        return { kind: "single-account" };
+    const activeKey = (deps.readActiveKey ?? (() => readOpencodeGoKey()))();
+    const current = accounts.find((account) => account.key === activeKey);
+    const materialize = deps.materializeGlobalOpencodeAuth ?? ((key) => void materializeOpencodeGoAuth(key));
+    if (!current) {
+        const next = selectNextAccount(accounts);
+        materialize(next.account.key);
+        return { kind: "reselected", activeAccountId: next.account.id, activeIsCooled: next.cooled };
+    }
+    await coolActiveAccount(opencodeAccountCanonicalId(current.id), deps);
+    const next = selectNextAccount(accounts, current.id);
+    materialize(next.account.key);
+    return {
+        kind: "rotated",
+        cooledAccountId: current.id,
+        activeAccountId: next.account.id,
+        activeIsCooled: next.cooled,
+        ...(next.waitMs === undefined ? {} : { waitMs: next.waitMs }),
+    };
+}
+function formatWait(waitMs) {
+    if (waitMs === undefined)
+        return "";
+    const hours = waitMs / 3_600_000;
+    if (hours >= 24)
+        return ` (resets in ~${Math.ceil(hours / 24)}d)`;
+    if (hours >= 1)
+        return ` (resets in ~${Math.ceil(hours)}h)`;
+    return ` (resets in ~${Math.max(1, Math.ceil(waitMs / 60_000))}m)`;
+}
+/** Human-readable lines describing a rotation outcome, in print order. */
+export function describeOpencodeRotate(outcome) {
+    switch (outcome.kind) {
+        case "unavailable":
+            return [`wp opencode: could not resolve OpenCode Go accounts (${outcome.reason}).`];
+        case "single-account":
+            return [
+                "wp opencode: only one OpenCode Go account is configured; nothing to rotate to. Add OPENCODE_GO_KEY_<ID> secrets to enable rotation.",
+            ];
+        case "reselected":
+            return [
+                "wp opencode: the active key matches no configured account, so nothing was cooled.",
+                `wp opencode: now active -> opencode-go:${outcome.activeAccountId}`,
+            ];
+        case "rotated": {
+            const lines = [
+                `wp opencode: cooled opencode-go:${outcome.cooledAccountId} (usage limit)`,
+                `wp opencode: now active -> opencode-go:${outcome.activeAccountId}`,
+            ];
+            if (outcome.activeIsCooled) {
+                lines.push(`wp opencode: every account is within its cooldown; using the soonest-expiring one${formatWait(outcome.waitMs)}. Run again after it resets, or add another OPENCODE_GO_KEY_<ID>.`);
+            }
+            return lines;
+        }
+    }
+}

package/dist/esm/cli/commands/public-readiness.d.ts

@@ -0,0 +1,11 @@
+import type { CAC } from "cac";
+export declare const PUBLIC_READINESS_COMMAND_HELP: string;
+export interface PublicReadinessDeps {
+    readonly cwd?: string;
+    readonly resolveRepoRoot?: (cwd: string) => string | null;
+    readonly hasReadinessScript?: (repoRoot: string) => boolean;
+    readonly run?: (repoRoot: string) => number;
+    readonly stderr?: Pick<typeof process.stderr, "write">;
+}
+export declare function runPublicReadiness(deps?: PublicReadinessDeps): number;
+export declare function registerPublicReadinessCommand(cli: CAC): void;

package/dist/esm/cli/commands/public-readiness.js

@@ -0,0 +1,42 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { getGitTopLevel } from "#git/changed-files";
+export const PUBLIC_READINESS_COMMAND_HELP = [
+    "Run the public package readiness gate.",
+    "",
+    "Delegates to scripts/public-readiness.ts, preserving that script as the",
+    "single owner of package and repository visibility readiness checks.",
+    "",
+    "Examples:",
+    "  wp public:readiness",
+].join("\n");
+function defaultRunPublicReadiness(repoRoot) {
+    const result = spawnSync("bun", ["scripts/public-readiness.ts"], {
+        cwd: repoRoot,
+        stdio: "inherit",
+        env: process.env,
+    });
+    if (result.error) {
+        process.stderr.write(`${result.error.message}\n`);
+        return 1;
+    }
+    return typeof result.status === "number" ? result.status : 1;
+}
+export function runPublicReadiness(deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const stderr = deps.stderr ?? process.stderr;
+    const resolveRepoRoot = deps.resolveRepoRoot ?? ((current) => getGitTopLevel(current));
+    const hasReadinessScript = deps.hasReadinessScript ??
+        ((repoRoot) => existsSync(path.join(repoRoot, "scripts", "public-readiness.ts")));
+    const run = deps.run ?? defaultRunPublicReadiness;
+    const repoRoot = resolveRepoRoot(cwd) ?? cwd;
+    if (!hasReadinessScript(repoRoot)) {
+        stderr.write(`wp public:readiness: scripts/public-readiness.ts is missing at ${repoRoot}.\n`);
+        return 1;
+    }
+    return run(repoRoot);
+}
+export function registerPublicReadinessCommand(cli) {
+    cli.command("public:readiness", PUBLIC_READINESS_COMMAND_HELP).action(() => runPublicReadiness());
+}

package/dist/esm/cli/commands/review.d.ts

@@ -2,8 +2,11 @@ import type { CAC } from "cac";
 import { runReviewExecution, type ReviewEffort, type ReviewLimitWindow, type ReviewProvider, type ReviewRunSummary, type ReviewStage } from "#review/execution/index.js";
 import { createReviewTargetCheckout, type ReviewTargetCheckout } from "#review/execution/review-checkout.js";
 import { type ReviewProcessRecord } from "#review/execution/process-registry.js";
+import { type OpencodeAccount } from "#review/opencode-account.js";
+import { resolveOpencodeAccountsGracefully } from "#runtime/opencode-account-materializer.js";
 import { evaluateApprovalGate } from "#lifecycle/audit";
 import { type ReviewEvent } from "#review/events.js";
+import { type ReviewGateVerification } from "#review/delivery-verifier.js";
 import { runCommand } from "#mcp/tools/_shared/run-command.js";
 export type ReviewVerdict = "approve" | "approve-with-nits" | "reject" | "no-verdict";
 export type ReviewStatus = "complete" | "timed-out" | "incomplete" | "unavailable" | "failed";
@@ -77,6 +80,8 @@ export interface ReviewCommandOptions {
     artifactRoot?: string;
     idleSeconds?: string;
     maxProgressEvents?: string;
+    reason?: string;
+    confirm?: boolean;
 }
 interface ReviewGateAttempt {
     readonly provider: ReviewProvider;
@@ -90,6 +95,7 @@ interface ReviewGateAttempt {
     readonly verdict: ReviewVerdict;
     readonly terminalClassification: string;
     readonly failureCode?: string;
+    readonly providerErrorDetail?: string;
     readonly limitWindow?: ReviewLimitWindow;
     readonly retryAfterMs?: number;
     readonly artifact?: string;
@@ -105,7 +111,7 @@ interface ReviewGateResult {
     readonly targetSha: string;
     readonly baseSha: string;
     readonly promptHash: string;
-    readonly status: "approved" | "needs-review" | "rejected" | "recorded-untracked";
+    readonly status: "approved" | "needs-review" | "rejected" | "scope-exhausted" | "recorded-untracked" | "verification-failed";
     readonly approvalGate: ReturnType<typeof evaluateApprovalGate>;
     readonly statePath: string;
     readonly attempts: readonly ReviewGateAttempt[];
@@ -123,6 +129,7 @@ interface ReviewGateResult {
         readonly rev?: string;
     }[];
     readonly issues?: readonly string[];
+    readonly verification?: ReviewGateVerification;
     readonly message: string;
 }
 interface ReviewLedger {
@@ -164,6 +171,22 @@ export declare function runReviewRunCommand(projectRoot: string, options: Review
 export declare function readReviewLedger(projectRoot: string, slug: string): Promise<ReviewLedger>;
 export declare function logReviewEntry(projectRoot: string, slug: string, input: ReviewCommandOptions): Promise<ReviewEntry>;
 export declare function logReviewEvent(projectRoot: string, slug: string, input: ReviewCommandOptions): Promise<ReviewEvent>;
+/**
+ * `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 declare function runReviewOverride(projectRoot: string, slug: string, input: ReviewCommandOptions): Promise<ReviewEvent>;
 export declare function classifyProviderOutput(output: string): Pick<ReviewGateAttempt, "status" | "verdict" | "terminalClassification">;
 export declare function reviewerFamily(model: string): ReviewReviewerId;
 type GateProviderResultStage = ReviewStage | "approval-gate";
@@ -176,18 +199,26 @@ export declare function invokeProvider(input: {
     readonly provider: ReviewProvider;
     readonly targetSha: string;
     readonly signal?: AbortSignal;
-}, executeReview?: typeof runReviewExecution, runCatalogCommand?: typeof runCommand, createTargetCheckout?: typeof createReviewTargetCheckout, existingCheckout?: ReviewTargetCheckout): Promise<{
+    readonly authDataDir?: string;
+}, executeReview?: typeof runReviewExecution, runCatalogCommand?: typeof runCommand, createTargetCheckout?: typeof createReviewTargetCheckout, getSharedCheckout?: () => ReviewTargetCheckout | undefined): Promise<{
     output: string;
     model: string;
     reviewer: string;
     stage?: GateProviderResultStage;
-} & Pick<ReviewGateAttempt, "status" | "verdict" | "terminalClassification" | "failureCode" | "limitWindow" | "retryAfterMs">>;
+} & Pick<ReviewGateAttempt, "status" | "verdict" | "terminalClassification" | "failureCode" | "providerErrorDetail" | "limitWindow" | "retryAfterMs">>;
 export interface ReviewGateDependencies {
     readonly createTargetCheckout?: typeof createReviewTargetCheckout;
     readonly invokeProvider?: typeof invokeProvider;
     readonly runCatalogCommand?: typeof runCommand;
     readonly runReviewExecution?: typeof runReviewExecution;
     readonly signal?: AbortSignal;
+    /** Test seam: resolve opencode-go accounts from the secret provider. */
+    readonly resolveOpencodeAccounts?: typeof resolveOpencodeAccountsGracefully;
+    /**
+     * Test seam: materialize an account's isolated auth store and return the
+     * `XDG_DATA_HOME` directory to inject for that account's spawns.
+     */
+    readonly prepareOpencodeCredential?: (account: OpencodeAccount) => string;
 }
 /**
  * Sanctioned fallback when `wp review gate` does not reach "approved" — points
@@ -198,6 +229,7 @@ export interface ReviewGateDependencies {
 export declare function reviewGateNonConvergenceHint(slug: string, context?: {
     readonly gateId?: string;
     readonly failureCode?: string;
+    readonly status?: ReviewGateResult["status"];
 }): string;
 export declare function runReviewGate(projectRoot: string, slug: string, input: ReviewCommandOptions, dependencies?: ReviewGateDependencies): Promise<ReviewGateResult>;
 export declare function buildReviewScoreboard(entries: readonly ReviewEntry[]): readonly ReviewScoreboardRow[];