@webpresso/agent-kit 3.1.30 → 3.3.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-probe.d.ts

@@ -0,0 +1,107 @@
+import { type OpencodeAccountAvailabilityEvent } from "#review/availability.js";
+import type { ReviewLimitWindow } from "#review/execution/types.js";
+import { type OpencodeAccount, type OpencodeAccountSelection } from "#review/opencode-account.js";
+/** Set to `1`/`true` to launch without probing account health at all. */
+export declare const OPENCODE_SKIP_PROBE_ENV = "WP_OPENCODE_SKIP_PROBE";
+/**
+ * Wall-clock bound for a single account probe.
+ *
+ * Measured live on 2026-07-24 against three real OpenCode Go accounts
+ * (`opencode` 1.18.4, model `opencode-go/deepseek-v4-flash`, trivial prompt):
+ *
+ * | run | capped `a`      | capped `o`      | healthy `z`                |
+ * | --- | --------------- | --------------- | -------------------------- |
+ * | repo cwd, default tools | 6.0s to first limit line | ~10s | 50.9s to completion |
+ * | temp cwd, default tools | 11.6s | 20.7s | 28.2s to first assistant text |
+ * | temp cwd, no-tools agent | 13.9s | 11.8s | 18.6s to first assistant text |
+ *
+ * `opencode --version` alone costs ~5.7s on the same machine, so roughly a third
+ * of the floor is binary startup and cannot be optimised away here. The probe
+ * therefore runs in a fresh temp cwd (a repo cwd made opencode snapshot the
+ * worktree, which alone cost ~23s) with a no-tools agent (which shrinks the
+ * system prompt and saved a further ~10s).
+ *
+ * 45s is ~2.4x the slowest observed healthy completion (18.6s) and ~2.2x the
+ * slowest observed limit detection (20.7s). The headroom covers a cold provider
+ * catalog fetch on a slow network; it is not a workaround for a slow probe.
+ * Hitting it is not a failure to be silenced by raising the bound — it degrades
+ * to `inconclusive` and the launch proceeds on the already-selected account.
+ *
+ * A capped account is detected by *streaming* the output rather than waiting for
+ * exit: opencode retries a usage-limit stream error and does not exit on it, so
+ * a blocking `spawnSync` sat at the full 60s bound in every measured run even
+ * though the limit was already on stderr after ~6s.
+ */
+export declare const OPENCODE_PROBE_TIMEOUT_MS = 45000;
+/**
+ * How long a successful probe is trusted before the account is probed again.
+ *
+ * A probe costs 12-28s (see `OPENCODE_PROBE_TIMEOUT_MS`), so probing a healthy
+ * account on every launch would make `wp opencode` permanently ~19s slower. A
+ * *capped* account never needs a re-probe — its cooldown record already
+ * suppresses it for the real reset window — so only the healthy verdict is
+ * memoised.
+ *
+ * Measured end to end on 2026-07-24 with three real accounts (two capped):
+ * a cold launch that rotated twice took 40.6s; the immediately following launch
+ * took 476ms, because the two capped accounts were suppressed by their recorded
+ * windows and the healthy one was covered by this marker.
+ */
+export declare const OPENCODE_PROBE_HEALTHY_TTL_MS: number;
+export type OpencodeProbeResult = 
+/** The account answered, so it has budget. */
+{
+    readonly kind: "healthy";
+}
+/** The provider reported a usage limit; `retryAfterMs` is already defaulted. */
+ | {
+    readonly kind: "limited";
+    readonly limitWindow: ReviewLimitWindow;
+    readonly retryAfterMs: number;
+    readonly windowParsed: boolean;
+}
+/** Nothing could be concluded; the caller must launch on this account anyway. */
+ | {
+    readonly kind: "inconclusive";
+    readonly reason: string;
+};
+export interface OpencodeProbeRunnerInput {
+    readonly dataDir: string;
+    readonly timeoutMs: number;
+}
+export type OpencodeProbeRunner = (input: OpencodeProbeRunnerInput) => Promise<OpencodeProbeResult>;
+export declare function isOpencodeProbeEnabled(env?: NodeJS.ProcessEnv): boolean;
+export interface ProbeOpencodeAccountDeps {
+    readonly run?: OpencodeProbeRunner;
+    readonly materialize?: (key: string, dataDir: string) => void;
+    readonly now?: () => number;
+    readonly timeoutMs?: number;
+    readonly healthyTtlMs?: number;
+}
+/**
+ * Probe one account's OpenCode Go credential, memoising a healthy verdict.
+ *
+ * Never throws: every failure path resolves to `inconclusive` so a credential
+ * check can never stop the TUI from opening.
+ */
+export declare function probeOpencodeAccount(account: OpencodeAccount, deps?: ProbeOpencodeAccountDeps): Promise<OpencodeProbeResult>;
+export interface OpencodeProbeRotationDeps {
+    readonly probe?: (account: OpencodeAccount) => Promise<OpencodeProbeResult>;
+    readonly recordCooldown?: (canonicalId: string, event: OpencodeAccountAvailabilityEvent) => Promise<unknown>;
+    readonly selectFrom?: (accounts: readonly OpencodeAccount[], excludedIds: ReadonlySet<string>) => OpencodeAccountSelection | undefined;
+    readonly env?: NodeJS.ProcessEnv;
+}
+export interface OpencodeProbeRotation {
+    readonly selection: OpencodeAccountSelection;
+    /** Human-readable lines describing what the probe did, in print order. */
+    readonly lines: readonly string[];
+}
+/**
+ * Probe the selected account and rotate past capped ones, bounded by the number
+ * of configured accounts.
+ *
+ * Returns the account to launch on plus the lines to print. Never throws and
+ * never returns nothing: an inconclusive probe keeps the incoming selection, so
+ * the worst case is exactly today's behaviour plus one log line.
+ */
+export declare function resolveHealthyOpencodeAccount(accounts: readonly OpencodeAccount[], initial: OpencodeAccountSelection, deps?: OpencodeProbeRotationDeps): Promise<OpencodeProbeRotation>;

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

@@ -0,0 +1,323 @@
+import { spawn } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { formatOpencodeResetWait, OPENCODE_UNKNOWN_LIMIT_COOLDOWN_MS, } from "#cli/commands/opencode-rotate.js";
+import { loadOpencodeAccountAvailability, pruneExpiredOpencodeAccountSuppressions, recordOpencodeAccountAvailabilityWithLock, } from "#review/availability.js";
+import { opencodeUsageLimit } from "#review/execution/adapters.js";
+import { opencodeAccountCanonicalId, opencodeAccountDataDir, selectActiveOpencodeAccount, } from "#review/opencode-account.js";
+import { materializeOpencodeGoAuth } from "#review/opencode-auth.js";
+/** Set to `1`/`true` to launch without probing account health at all. */
+export const OPENCODE_SKIP_PROBE_ENV = "WP_OPENCODE_SKIP_PROBE";
+/**
+ * Wall-clock bound for a single account probe.
+ *
+ * Measured live on 2026-07-24 against three real OpenCode Go accounts
+ * (`opencode` 1.18.4, model `opencode-go/deepseek-v4-flash`, trivial prompt):
+ *
+ * | run | capped `a`      | capped `o`      | healthy `z`                |
+ * | --- | --------------- | --------------- | -------------------------- |
+ * | repo cwd, default tools | 6.0s to first limit line | ~10s | 50.9s to completion |
+ * | temp cwd, default tools | 11.6s | 20.7s | 28.2s to first assistant text |
+ * | temp cwd, no-tools agent | 13.9s | 11.8s | 18.6s to first assistant text |
+ *
+ * `opencode --version` alone costs ~5.7s on the same machine, so roughly a third
+ * of the floor is binary startup and cannot be optimised away here. The probe
+ * therefore runs in a fresh temp cwd (a repo cwd made opencode snapshot the
+ * worktree, which alone cost ~23s) with a no-tools agent (which shrinks the
+ * system prompt and saved a further ~10s).
+ *
+ * 45s is ~2.4x the slowest observed healthy completion (18.6s) and ~2.2x the
+ * slowest observed limit detection (20.7s). The headroom covers a cold provider
+ * catalog fetch on a slow network; it is not a workaround for a slow probe.
+ * Hitting it is not a failure to be silenced by raising the bound — it degrades
+ * to `inconclusive` and the launch proceeds on the already-selected account.
+ *
+ * A capped account is detected by *streaming* the output rather than waiting for
+ * exit: opencode retries a usage-limit stream error and does not exit on it, so
+ * a blocking `spawnSync` sat at the full 60s bound in every measured run even
+ * though the limit was already on stderr after ~6s.
+ */
+export const OPENCODE_PROBE_TIMEOUT_MS = 45_000;
+/**
+ * How long a successful probe is trusted before the account is probed again.
+ *
+ * A probe costs 12-28s (see `OPENCODE_PROBE_TIMEOUT_MS`), so probing a healthy
+ * account on every launch would make `wp opencode` permanently ~19s slower. A
+ * *capped* account never needs a re-probe — its cooldown record already
+ * suppresses it for the real reset window — so only the healthy verdict is
+ * memoised.
+ *
+ * Measured end to end on 2026-07-24 with three real accounts (two capped):
+ * a cold launch that rotated twice took 40.6s; the immediately following launch
+ * took 476ms, because the two capped accounts were suppressed by their recorded
+ * windows and the healthy one was covered by this marker.
+ */
+export const OPENCODE_PROBE_HEALTHY_TTL_MS = 30 * 60 * 1_000;
+/**
+ * Cheapest OpenCode Go model at the time of writing. The gateway caps by
+ * account, not by model, so any model reveals the cap; this one is picked purely
+ * to minimise probe cost. If the id ever disappears from the catalog the probe
+ * fails as `inconclusive` and the launch proceeds unchanged, which is the same
+ * safe degradation as a spawn failure.
+ */
+const OPENCODE_PROBE_MODEL = "opencode-go/deepseek-v4-flash";
+const OPENCODE_PROBE_AGENT = "wp-health-probe";
+const OPENCODE_PROBE_PROMPT = "hi";
+const OPENCODE_PROBE_PERMISSIONS = { "*": "deny" };
+const OPENCODE_PROBE_CONFIG = JSON.stringify({
+    $schema: "https://opencode.ai/config.json",
+    share: "disabled",
+    permission: OPENCODE_PROBE_PERMISSIONS,
+    agent: {
+        [OPENCODE_PROBE_AGENT]: {
+            description: "Minimal OpenCode Go credential health probe.",
+            mode: "primary",
+            permission: OPENCODE_PROBE_PERMISSIONS,
+            tools: { "*": false },
+        },
+    },
+});
+/** Rolling capture bound: the limit text always arrives in the newest output. */
+const MAX_CAPTURE_BYTES = 64 * 1_024;
+/** A rendered assistant token or a finished step proves the account answered. */
+const HEALTHY_EVENT_PATTERN = /"type"\s*:\s*"(?:text|step_finish)"/u;
+const HEALTH_MARKER_FILE = "wp-probe-health.json";
+export function isOpencodeProbeEnabled(env = process.env) {
+    const raw = env[OPENCODE_SKIP_PROBE_ENV]?.trim().toLowerCase();
+    return raw !== "1" && raw !== "true";
+}
+function healthMarkerPath(dataDir) {
+    return join(dataDir, HEALTH_MARKER_FILE);
+}
+function readHealthMarker(dataDir) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(healthMarkerPath(dataDir), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return undefined;
+    const okAt = parsed["okAt"];
+    return typeof okAt === "number" && Number.isFinite(okAt) ? okAt : undefined;
+}
+function writeHealthMarker(dataDir, atMs) {
+    try {
+        mkdirSync(dataDir, { recursive: true });
+        writeFileSync(healthMarkerPath(dataDir), JSON.stringify({ okAt: atMs }), {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+    }
+    catch {
+        // Best-effort memoisation: a missing marker only costs another probe.
+    }
+}
+function limitedFromEvent(message) {
+    const event = opencodeUsageLimit(message);
+    if (event === null || event.kind !== "failure")
+        return null;
+    const parsed = event.retryAfterMs;
+    return {
+        kind: "limited",
+        limitWindow: event.limitWindow ?? "unknown",
+        retryAfterMs: parsed ?? OPENCODE_UNKNOWN_LIMIT_COOLDOWN_MS,
+        windowParsed: parsed !== undefined,
+    };
+}
+function probeArgs() {
+    return [
+        "run",
+        "--pure",
+        "--print-logs",
+        "--log-level",
+        "ERROR",
+        "--format",
+        "json",
+        "--model",
+        OPENCODE_PROBE_MODEL,
+        "--agent",
+        OPENCODE_PROBE_AGENT,
+        OPENCODE_PROBE_PROMPT,
+    ];
+}
+function classifyChunk(captured) {
+    return (limitedFromEvent(captured) ??
+        (HEALTHY_EVENT_PATTERN.test(captured) ? { kind: "healthy" } : null));
+}
+/**
+ * Spawn a bounded `opencode run` against one account's isolated credential
+ * store and classify the first conclusive thing it says.
+ *
+ * There is no OpenCode Go HTTP endpoint anywhere in this codebase — the review
+ * adapter also reaches the provider only by spawning this binary — so a
+ * subprocess is the only available probe vehicle. Per-account isolation is the
+ * same `XDG_DATA_HOME` trick the review adapter uses, so a probe can never race
+ * a live interactive TUI's global `auth.json`.
+ */
+function spawnOpencodeProbe(input) {
+    return new Promise((resolve) => {
+        let probeCwd;
+        try {
+            probeCwd = mkdtempSync(join(tmpdir(), "wp-opencode-probe-"));
+        }
+        catch (error) {
+            resolve({ kind: "inconclusive", reason: describeError(error) });
+            return;
+        }
+        runProbeChild(probeCwd, input, resolve);
+    });
+}
+function runProbeChild(probeCwd, input, resolve) {
+    const child = spawn("opencode", [...probeArgs()], {
+        cwd: probeCwd,
+        env: {
+            ...process.env,
+            XDG_DATA_HOME: input.dataDir,
+            OPENCODE_CONFIG_CONTENT: OPENCODE_PROBE_CONFIG,
+            OPENCODE_DISABLE_AUTOUPDATE: "true",
+            OPENCODE_DISABLE_PRUNE: "true",
+        },
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    let settled = false;
+    let timer;
+    const finish = (result) => {
+        if (settled)
+            return;
+        settled = true;
+        if (timer)
+            clearTimeout(timer);
+        child.kill("SIGKILL");
+        try {
+            rmSync(probeCwd, { recursive: true, force: true });
+        }
+        catch {
+            // Best-effort temp cleanup; the OS reclaims it either way.
+        }
+        resolve(result);
+    };
+    timer = setTimeout(() => finish({ kind: "inconclusive", reason: `probe timed out after ${input.timeoutMs}ms` }), input.timeoutMs);
+    let captured = "";
+    const onChunk = (chunk) => {
+        captured = (captured + chunk.toString("utf8")).slice(-MAX_CAPTURE_BYTES);
+        const result = classifyChunk(captured);
+        if (result)
+            finish(result);
+    };
+    child.stdout.on("data", onChunk);
+    child.stderr.on("data", onChunk);
+    child.on("error", (error) => finish({ kind: "inconclusive", reason: error.message }));
+    child.on("close", (code) => finish(code === 0
+        ? { kind: "healthy" }
+        : { kind: "inconclusive", reason: `opencode exited with code ${code ?? "signal"}` }));
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Probe one account's OpenCode Go credential, memoising a healthy verdict.
+ *
+ * Never throws: every failure path resolves to `inconclusive` so a credential
+ * check can never stop the TUI from opening.
+ */
+export async function probeOpencodeAccount(account, deps = {}) {
+    const now = (deps.now ?? Date.now)();
+    const dataDir = opencodeAccountDataDir(account.id);
+    const ttl = deps.healthyTtlMs ?? OPENCODE_PROBE_HEALTHY_TTL_MS;
+    const okAt = readHealthMarker(dataDir);
+    if (okAt !== undefined && now - okAt >= 0 && now - okAt < ttl)
+        return { kind: "healthy" };
+    try {
+        (deps.materialize ?? defaultMaterialize)(account.key, dataDir);
+    }
+    catch (error) {
+        return { kind: "inconclusive", reason: describeError(error) };
+    }
+    const result = await (deps.run ?? spawnOpencodeProbe)({
+        dataDir,
+        timeoutMs: deps.timeoutMs ?? OPENCODE_PROBE_TIMEOUT_MS,
+    });
+    if (result.kind === "healthy")
+        writeHealthMarker(dataDir, now);
+    return result;
+}
+function defaultMaterialize(key, dataDir) {
+    materializeOpencodeGoAuth(key, { dataDir });
+}
+/**
+ * Select the account to launch on, excluding `excludedIds`.
+ *
+ * Excluded ids are the accounts this run just cooled. They are filtered here
+ * rather than relied upon coming back suppressed from the store — the same
+ * read-after-write independence `selectNextAccount` in `opencode-rotate.ts`
+ * keeps, so rotation stays correct even when the cooldown write is contended.
+ */
+function defaultSelectFrom(accounts, excludedIds) {
+    const pool = accounts.filter((account) => !excludedIds.has(account.id));
+    if (pool.length === 0)
+        return undefined;
+    const pruned = pruneExpiredOpencodeAccountSuppressions(loadOpencodeAccountAvailability());
+    return selectActiveOpencodeAccount(pool, pruned.state);
+}
+function coolLimitedAccount(accountId, result, deps) {
+    const canonicalId = opencodeAccountCanonicalId(accountId);
+    // Same event shape `--wp-rotate` and the review gate record, so all three
+    // writers produce identical, mutually-readable cooldown records. Unlike a
+    // manual rotation this one carries the provider's REAL reset window.
+    const event = {
+        failureCode: "opencode-go-usage-limit",
+        terminalClassification: "provider-limit-reached",
+        limitWindow: result.limitWindow,
+        retryAfterMs: result.retryAfterMs,
+    };
+    return (deps.recordCooldown ?? recordOpencodeAccountAvailabilityWithLock)(canonicalId, event);
+}
+function allCappedLines(selection) {
+    return [
+        `wp opencode: every OpenCode Go account probed as capped; launching on the soonest-expiring one (${selection.account.id})${formatOpencodeResetWait(selection.waitMs)}. Add another OPENCODE_GO_KEY_<ID> to widen the pool.`,
+    ];
+}
+/**
+ * Probe the selected account and rotate past capped ones, bounded by the number
+ * of configured accounts.
+ *
+ * Returns the account to launch on plus the lines to print. Never throws and
+ * never returns nothing: an inconclusive probe keeps the incoming selection, so
+ * the worst case is exactly today's behaviour plus one log line.
+ */
+export async function resolveHealthyOpencodeAccount(accounts, initial, deps = {}) {
+    if (!isOpencodeProbeEnabled(deps.env ?? process.env))
+        return { selection: initial, lines: [] };
+    // `cooled` means every account is already known-capped: probing cannot find a
+    // better one and would cost a full timeout, so keep the existing behaviour.
+    if (initial.cooled)
+        return { selection: initial, lines: [] };
+    const probe = deps.probe ?? ((account) => probeOpencodeAccount(account));
+    const selectFrom = deps.selectFrom ?? defaultSelectFrom;
+    const excluded = new Set();
+    const lines = [];
+    let current = initial;
+    for (let attempt = 0; attempt < accounts.length; attempt += 1) {
+        const result = await probe(current.account);
+        if (result.kind === "healthy")
+            return { selection: current, lines };
+        if (result.kind === "inconclusive") {
+            lines.push(`wp opencode: health probe for opencode-go:${current.account.id} was inconclusive (${result.reason}); launching on it anyway.`);
+            return { selection: current, lines };
+        }
+        await coolLimitedAccount(current.account.id, result, deps);
+        excluded.add(current.account.id);
+        const next = selectFrom(accounts, excluded);
+        if (!next) {
+            const fallback = selectFrom(accounts, new Set()) ?? current;
+            lines.push(...allCappedLines(fallback));
+            return { selection: fallback, lines };
+        }
+        lines.push(`wp opencode: probe found opencode-go:${current.account.id} capped${formatOpencodeResetWait(result.retryAfterMs)}, rotated to opencode-go:${next.account.id}`);
+        current = next;
+    }
+    return { selection: current, lines };
+}

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

@@ -0,0 +1,72 @@
+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>;
+}
+/**
+ * Cooldown to record when an account is known to be capped but the real reset
+ * window is unknown: it assumes the shortest real OpenCode Go window (5 hours).
+ *
+ * A manual `--wp-rotate` has no provider response at all, so it always lands
+ * here. The launch-time health probe (`#cli/commands/opencode-probe.js`) uses it
+ * only as a fallback, because that path *does* have a provider response and
+ * normally records the true parsed window instead.
+ *
+ * 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 probe/rotation)
+ * simply cools it again.
+ */
+export declare const OPENCODE_UNKNOWN_LIMIT_COOLDOWN_MS: number;
+/**
+ * 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>;
+/**
+ * Render a cooldown remainder as a short ` (resets in ~Xd)` suffix, or the empty
+ * string when the window is unknown. Shared with the launch-time health probe so
+ * rotation and probe output cannot drift apart.
+ */
+export declare function formatOpencodeResetWait(waitMs: number | undefined): string;
+/** Human-readable lines describing a rotation outcome, in print order. */
+export declare function describeOpencodeRotate(outcome: OpencodeRotateOutcome): readonly string[];