@webpresso/agent-kit 3.2.0 → 3.3.1

package/dist/esm/cli/commands/agent-launch.js

@@ -12,6 +12,7 @@ import { loadOpencodeAccountAvailability, pruneExpiredOpencodeAccountSuppression
 import { selectActiveOpencodeAccount } from "#review/opencode-account.js";
 import { materializeOpencodeGoAuth } from "#review/opencode-auth.js";
 import { describeOpencodeRotate, OPENCODE_ROTATE_FLAG, rotateActiveOpencodeAccount, } from "#cli/commands/opencode-rotate.js";
+import { OPENCODE_SKIP_PROBE_ENV, resolveHealthyOpencodeAccount, } from "#cli/commands/opencode-probe.js";
 export const AGENT_LAUNCH_COMMANDS = DASH_PROVIDERS;
 export const DEFAULT_AGENT_SECRET_PROFILE = "preview";
 export const AGENT_SECRET_PROFILE_ENV = "WP_AGENT_SECRET_PROFILE";
@@ -89,21 +90,26 @@ function ensureCodexSkillSurface(cwd, env = process.env) {
     }
 }
 /**
- * Choose the active opencode-go account and materialize its key into the
- * global opencode `auth.json` before the TUI launches.
+ * Choose the active opencode-go account, verify it against the real provider,
+ * and materialize its key into the global opencode `auth.json` before the TUI
+ * launches.
+ *
+ * A launch-time health probe (`resolveHealthyOpencodeAccount`) spawns a bounded
+ * `opencode run` against the candidate's isolated credential store; a detected
+ * usage limit cools that account with the provider's real reset window and the
+ * next account is probed instead. So a plain relaunch now *does* rotate past an
+ * exhausted account, and `wp opencode --wp-rotate` is only needed to force a
+ * swap off an account that is still answering.
  *
  * Honest limitation: interactive opencode is a long-lived TUI — the account is
- * chosen once at launch and a mid-session dollar-cap is NOT auto-swapped. A
- * plain relaunch does NOT rotate either: nothing on this path records a
- * cooldown, so an exhausted account stays "first non-suppressed" and gets
- * re-picked every time. Run `wp opencode --wp-rotate` to cool the current
- * account and launch on the next one. Only the review gate does automatic
- * in-flight failover, because only it can observe the usage-limit response.
+ * chosen once at launch, so a cap hit *mid-session* is still NOT auto-swapped.
+ * Only the review gate does in-flight failover, because only it observes every
+ * provider response for the life of the run.
  *
- * Never throws: a Doppler outage or materialize failure must not block the
- * TUI from launching, so every failure is logged and swallowed.
+ * Never throws: a Doppler outage, a failed probe, or a materialize failure must
+ * not block the TUI from launching, so every failure is logged and swallowed.
  */
-function selectAndMaterializeOpencodeAccount(cwd, deps, secretProfile) {
+async function selectAndMaterializeOpencodeAccount(cwd, deps, secretProfile, env) {
     try {
         const resolution = (deps.resolveOpencodeAccounts ?? resolveOpencodeAccountsGracefully)({
             cwd,
@@ -112,11 +118,15 @@ function selectAndMaterializeOpencodeAccount(cwd, deps, secretProfile) {
         if (!resolution.ok)
             return;
         const pruned = pruneExpiredOpencodeAccountSuppressions(loadOpencodeAccountAvailability());
-        const selection = selectActiveOpencodeAccount(resolution.accounts, pruned.state);
-        if (!selection)
+        const initial = selectActiveOpencodeAccount(resolution.accounts, pruned.state);
+        if (!initial)
             return;
+        const probed = await (deps.resolveHealthyOpencodeAccount ?? resolveHealthyOpencodeAccount)(resolution.accounts, initial, { env });
+        for (const line of probed.lines)
+            console.error(line);
+        const selection = probed.selection;
         (deps.materializeGlobalOpencodeAuth ?? ((key) => materializeOpencodeGoAuth(key)))(selection.account.key);
-        if (selection.cooled) {
+        if (selection.cooled && probed.lines.length === 0) {
             console.error(`wp opencode: all OpenCode Go accounts are within their usage cooldown; launching on the soonest-expiring account (${selection.account.id}).`);
         }
     }
@@ -130,10 +140,11 @@ function selectAndMaterializeOpencodeAccount(cwd, deps, secretProfile) {
  * forward to the binary. `--wp-rotate` is consumed here and must never reach
  * opencode, which would treat it as a prompt.
  */
-async function prepareOpencodeLaunch(cwd, args, secretsConfig, deps, secretProfile) {
+async function prepareOpencodeLaunch(cwd, args, secretsConfig, deps, secretProfile, env) {
     if (!args.includes(OPENCODE_ROTATE_FLAG)) {
-        if (secretsConfig !== null)
-            selectAndMaterializeOpencodeAccount(cwd, deps, secretProfile);
+        if (secretsConfig !== null) {
+            await selectAndMaterializeOpencodeAccount(cwd, deps, secretProfile, env);
+        }
         return args;
     }
     const outcome = await rotateActiveOpencodeAccount(cwd, secretProfile, deps);
@@ -144,7 +155,7 @@ async function prepareOpencodeLaunch(cwd, args, secretsConfig, deps, secretProfi
     // rotation could not run, fall through to that selection so the launch still
     // gets the best account it can rather than whatever the store happens to hold.
     if (outcome.kind === "unavailable" && secretsConfig !== null) {
-        selectAndMaterializeOpencodeAccount(cwd, deps, secretProfile);
+        await selectAndMaterializeOpencodeAccount(cwd, deps, secretProfile, env);
     }
     return args.filter((arg) => arg !== OPENCODE_ROTATE_FLAG);
 }
@@ -166,7 +177,7 @@ export async function runAgentLaunchCommand(command, args = [], options = {}, de
     // worktree, CI clone, and fresh checkout.
     const secretProfile = resolveAgentSecretProfile(options.env ?? process.env);
     const launchArgs = command === "opencode"
-        ? await prepareOpencodeLaunch(cwd, args, secretsConfig, deps, secretProfile)
+        ? await prepareOpencodeLaunch(cwd, args, secretsConfig, deps, secretProfile, options.env ?? process.env)
         : args;
     const runtimeOptions = buildAgentRuntimeCommandOptions({
         command,
@@ -184,7 +195,7 @@ export async function runAgentLaunchCommand(command, args = [], options = {}, de
 }
 export function registerAgentLaunchCommand(cli, command) {
     const rotateHint = command === "opencode"
-        ? ` (pass \`${OPENCODE_ROTATE_FLAG}\` to cool the current OpenCode Go account and launch on the next one)`
+        ? ` (the selected OpenCode Go account is health-probed first and a capped one is rotated past automatically; pass \`${OPENCODE_ROTATE_FLAG}\` to force a rotation, or set \`${OPENCODE_SKIP_PROBE_ENV}=1\` to skip the probe)`
         : "";
     cli
         .command(`${command} [...args]`, `Launch ${command} with provider-backed agent secrets and safe-by-default permissions (run \`wp yolo on\` for persistent full-auto)${rotateHint}`)

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

@@ -146,6 +146,10 @@ export const REPO_AUDIT_REGISTRY = {
     "legacy-workflow-identity": async (root) => (await import("#audit/legacy-workflow-identity")).auditLegacyWorkflowIdentity(root),
     rules: async (root) => runContentAudit(root, "rule"),
     skills: async (root) => runContentAudit(root, "skill"),
+    "changeset-required": async (root, options) => (await import("#audit/changeset-required")).auditChangesetRequired(root, {
+        baseRef: options.baseRef ?? options.base,
+        changedFiles: options.affectedFiles,
+    }),
 };
 async function runContentAudit(root, kind) {
     const { auditContent } = await import("../../content/audit.js");

package/dist/esm/cli/commands/blueprint/abandon.d.ts

@@ -0,0 +1,21 @@
+export interface AbandonBlueprintOptions {
+    readonly projectRoot?: string;
+    readonly confirm?: boolean;
+    /** Injected for tests. */
+    readonly resolveOwnerPath?: (repoRoot: string, slug: string) => string;
+    readonly readPorcelainZ?: (cwd: string) => string;
+    readonly hasCommittedDraft?: (cwd: string, slug: string) => boolean;
+    readonly isPrimaryCheckout?: (ownerPath: string, repoRoot: string) => boolean;
+}
+export interface AbandonBlueprintResult {
+    readonly slug: string;
+    readonly ownerPath: string;
+    readonly preview: boolean;
+    readonly message: string;
+    readonly paths: readonly string[];
+}
+/**
+ * Abandon an uncommitted draft scaffold so merge-cleanup can proceed.
+ * Without --confirm: print preview and throw (exit non-zero at CLI).
+ */
+export declare function abandonBlueprint(rawSlug: string, options?: AbandonBlueprintOptions): Promise<AbandonBlueprintResult>;

package/dist/esm/cli/commands/blueprint/abandon.js

@@ -0,0 +1,178 @@
+import { existsSync, lstatSync, rmSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { spawnSync } from "node:child_process";
+import { isValidBlueprintSlug, relativeBlueprintSlug } from "#lifecycle/local.js";
+import { resolveProjectRoot } from "#mcp/tools/_shared/project-root.js";
+import { classifyOwnerDirt, draftScaffoldPrefix, formatBoundedPaths, } from "#worktrees/owner-dirt.js";
+import { resolveOwnerWorktreePath } from "#worktrees/location.js";
+function gitStdout(cwd, args) {
+    const result = spawnSync("git", [...args], { cwd, encoding: "utf8" });
+    if (result.status !== 0) {
+        const err = String(result.stderr ?? result.stdout ?? "git failed").trim();
+        throw new Error(err || `git ${args.join(" ")} failed`);
+    }
+    return String(result.stdout ?? "");
+}
+function defaultReadPorcelainZ(cwd) {
+    return gitStdout(cwd, [
+        "status",
+        "--porcelain=v1",
+        "--untracked-files=all",
+        "--ignored=no",
+        "-z",
+    ]);
+}
+function defaultHasCommittedDraft(cwd, slug) {
+    const prefix = draftScaffoldPrefix(slug);
+    const mergeBase = spawnSync("git", ["merge-base", "HEAD", "origin/main"], {
+        cwd,
+        encoding: "utf8",
+    });
+    const range = mergeBase.status === 0 && String(mergeBase.stdout ?? "").trim()
+        ? `${String(mergeBase.stdout).trim()}..HEAD`
+        : "HEAD";
+    const log = spawnSync("git", ["log", "--oneline", range, "--", prefix], {
+        cwd,
+        encoding: "utf8",
+    });
+    if (log.status !== 0) {
+        // Fail closed: if history probe fails, do not delete.
+        return true;
+    }
+    return String(log.stdout ?? "").trim().length > 0;
+}
+function assertPathInsideDraftRoot(ownerPath, draftAbs) {
+    const draftRoot = resolve(ownerPath, "blueprints", "draft") + sep;
+    const target = resolve(draftAbs);
+    if (target !== resolve(ownerPath, "blueprints", "draft") && !target.startsWith(draftRoot)) {
+        throw new Error(`Refusing abandon: path escapes blueprints/draft/ (${target}). next: inspect worktree layout`);
+    }
+}
+function isOwnerPathForSlug(path, slug) {
+    const normalized = path.replace(/\\/gu, "/");
+    return (normalized.endsWith(`/blueprints/${slug}/owner`) ||
+        normalized.endsWith(`/blueprints/${slug}/owner/`));
+}
+function resolveOwnerForSlug(repoRoot, slug, resolveOwnerPath) {
+    const cwd = resolve(repoRoot);
+    // Already inside the owner worktree for this slug (typical agent cwd).
+    if (isOwnerPathForSlug(cwd, slug)) {
+        return cwd;
+    }
+    const ownerPath = resolve(resolveOwnerPath(repoRoot, slug));
+    if (ownerPath === cwd) {
+        throw new Error(`Refusing abandon: resolved owner is the primary checkout (${ownerPath}). next: abandon only from a bp/<slug> owner worktree, or remove primary draft manually after review`);
+    }
+    if (!isOwnerPathForSlug(ownerPath, slug)) {
+        throw new Error(`Refusing abandon: worktree ${ownerPath} is not the owner path for ${slug}. next: run from bp/${slug} owner or pass the correct project root`);
+    }
+    return ownerPath;
+}
+/**
+ * Abandon an uncommitted draft scaffold so merge-cleanup can proceed.
+ * Without --confirm: print preview and throw (exit non-zero at CLI).
+ */
+export async function abandonBlueprint(rawSlug, options = {}) {
+    const slug = relativeBlueprintSlug(rawSlug.trim());
+    if (!isValidBlueprintSlug(slug)) {
+        throw new Error(`Refusing abandon: invalid blueprint slug ${JSON.stringify(rawSlug)}. next: use a kebab-case slug like my-feature`);
+    }
+    const projectRoot = options.projectRoot
+        ? resolveProjectRoot({ cwd: options.projectRoot, explicitCwd: options.projectRoot })
+        : resolveProjectRoot();
+    const resolveOwnerPath = options.resolveOwnerPath ?? resolveOwnerWorktreePath;
+    const readPorcelainZ = options.readPorcelainZ ?? defaultReadPorcelainZ;
+    const hasCommittedDraft = options.hasCommittedDraft ?? defaultHasCommittedDraft;
+    const ownerPath = resolveOwnerForSlug(projectRoot, slug, resolveOwnerPath);
+    const draftRel = draftScaffoldPrefix(slug);
+    const draftAbs = join(ownerPath, draftRel);
+    assertPathInsideDraftRoot(ownerPath, draftAbs);
+    if (existsSync(draftAbs)) {
+        const st = lstatSync(draftAbs);
+        if (st.isSymbolicLink()) {
+            // Only remove the link itself when confirmed — never follow.
+            if (options.confirm !== true) {
+                throw new Error([
+                    `Would remove symlink draft scaffold ${draftRel} in ${ownerPath}`,
+                    "Re-run with --confirm to remove the symlink only (not the target).",
+                ].join("\n"));
+            }
+            rmSync(draftAbs, { force: true });
+            const afterLink = classifyOwnerDirt(readPorcelainZ(ownerPath), slug);
+            if (afterLink.kind !== "clean") {
+                throw new Error(`Abandon incomplete; remaining dirt:\n${formatBoundedPaths(afterLink.paths)}\nnext: git status in ${ownerPath}`);
+            }
+            return {
+                slug,
+                ownerPath,
+                preview: false,
+                paths: [draftRel],
+                message: `Abandoned draft symlink scaffold for ${slug}; worktree clean — next: wp worktree merge-cleanup bp/${slug}`,
+            };
+        }
+    }
+    if (hasCommittedDraft(ownerPath, slug)) {
+        throw new Error([
+            `Refusing abandon: commits on this branch touch ${draftRel}.`,
+            "next: land the draft with the PR, or revert those commits (git revert / interactive rebase) — abandon only deletes uncommitted scaffolds",
+        ].join("\n"));
+    }
+    const porcelainZ = readPorcelainZ(ownerPath);
+    const classification = classifyOwnerDirt(porcelainZ, slug);
+    if (classification.kind === "clean" && !existsSync(draftAbs)) {
+        throw new Error(`Nothing to abandon for ${slug}: no draft scaffold dirt. next: wp worktree merge-cleanup bp/${slug}`);
+    }
+    if (classification.kind === "other") {
+        throw new Error([
+            `Refusing abandon: owner has non-scaffold dirt for ${slug}:`,
+            formatBoundedPaths(classification.paths),
+            `next: commit or stash non-scaffold paths in ${ownerPath}, then re-run abandon or merge-cleanup`,
+        ].join("\n"));
+    }
+    // scaffold-only or clean-but-empty-dir leftover with no porcelain (empty dirs invisible)
+    const paths = classification.paths.length > 0 ? classification.paths : existsSync(draftAbs) ? [draftRel] : [];
+    if (options.confirm !== true) {
+        throw new Error([
+            `Would abandon draft scaffold for ${slug} in ${ownerPath}:`,
+            formatBoundedPaths(paths.length > 0 ? paths : [draftRel]),
+            "Re-run with --confirm to delete. next: wp blueprint abandon <slug> --confirm",
+        ].join("\n"));
+    }
+    // Unstage any index entries under the scaffold, then delete the tree.
+    const cached = spawnSync("git", ["rm", "-r", "--cached", "--ignore-unmatch", "--", draftRel], {
+        cwd: ownerPath,
+        encoding: "utf8",
+    });
+    if (cached.status !== 0 && cached.status !== null) {
+        // ignore-unmatch should make this soft; still fail closed on hard errors
+        const err = String(cached.stderr ?? "").trim();
+        if (err && !/did not match/iu.test(err)) {
+            throw new Error(`git rm --cached failed: ${err}. next: git status in ${ownerPath}`);
+        }
+    }
+    if (existsSync(draftAbs)) {
+        assertPathInsideDraftRoot(ownerPath, draftAbs);
+        const st = lstatSync(draftAbs);
+        if (st.isSymbolicLink()) {
+            rmSync(draftAbs, { force: true });
+        }
+        else if (st.isDirectory() || st.isFile()) {
+            rmSync(draftAbs, { recursive: true, force: true });
+        }
+    }
+    const after = classifyOwnerDirt(readPorcelainZ(ownerPath), slug);
+    if (after.kind !== "clean") {
+        throw new Error([
+            `Abandon incomplete; remaining dirt:`,
+            formatBoundedPaths(after.paths),
+            `next: git status in ${ownerPath}`,
+        ].join("\n"));
+    }
+    return {
+        slug,
+        ownerPath,
+        preview: false,
+        paths,
+        message: `Abandoned draft scaffold for ${slug}; worktree clean — next: wp worktree merge-cleanup bp/${slug}`,
+    };
+}

package/dist/esm/cli/commands/blueprint/router-dispatch.js

@@ -6,6 +6,7 @@ import { executeBlueprintDbSubcommand } from "./db-commands.js";
 import { getBlueprintSubcommandNames } from "./router-output.js";
 import { listTemplates, resolveTemplate } from "./template-resolver.js";
 import { TRUST_DOSSIER_SCAFFOLD } from "#trust/scaffold.js";
+import { abandonBlueprint } from "./abandon.js";
 // ---------------------------------------------------------------------------
 // Platform template fetcher (injectable for tests)
 // ---------------------------------------------------------------------------
@@ -261,6 +262,26 @@ export async function executeBlueprintSubcommand(subcommand, args, options, deps
             deps.printBlueprintOutput(options.json ? result : result.message, options.json);
             return;
         }
+        case "abandon": {
+            const slug = args[0];
+            if (!slug) {
+                throw new Error("Usage: wp blueprint abandon <slug> --confirm");
+            }
+            const result = await abandonBlueprint(slug, {
+                projectRoot: options.projectRoot,
+                confirm: options.confirm === true,
+            });
+            deps.printBlueprintOutput(options.json
+                ? {
+                    slug: result.slug,
+                    ownerPath: result.ownerPath,
+                    preview: result.preview,
+                    paths: result.paths,
+                    message: result.message,
+                }
+                : result.message, options.json);
+            return;
+        }
         case "finalize": {
             const slug = args[0];
             if (!slug) {

package/dist/esm/cli/commands/blueprint/router-output.js

@@ -18,6 +18,7 @@ export const BLUEPRINT_SUBCOMMANDS = [
     },
     { name: "start", usage: ["start <slug>"] },
     { name: "park", usage: ["park <slug>"] },
+    { name: "abandon", usage: ["abandon <slug> --confirm"] },
     {
         name: "task",
         usage: [

package/dist/esm/cli/commands/blueprint/router.d.ts

@@ -42,6 +42,8 @@ export interface BlueprintCommandOptions extends BlueprintAuditOptions, Blueprin
     template?: string;
     templatesDir?: string;
     to?: string;
+    /** Required for destructive `blueprint abandon`. */
+    confirm?: boolean;
     "--": string[];
 }
 export type { AdvanceTaskResult, PromoteBlueprintResult };

package/dist/esm/cli/commands/blueprint/router.js

@@ -175,9 +175,11 @@ export async function createBlueprint(goal, options = {}) {
         : probeService;
     // Single full compile lives inside create() on the write root.
     const created = await writeService.create({ complexity, goal, type });
+    const draftHint = "Draft is uncommitted — include blueprints/draft/" +
+        `${created.slug}/ in your first commit, or run: wp blueprint abandon ${created.slug} --confirm before merge-cleanup.`;
     const message = authoring.routed
-        ? `Created ${created.type} draft/${created.slug} (routed from primary-like checkout).`
-        : `Created ${created.type} draft/${created.slug}.`;
+        ? `Created ${created.type} draft/${created.slug} (routed from primary-like checkout).\n${draftHint}`
+        : `Created ${created.type} draft/${created.slug}.\n${draftHint}`;
     return {
         ...created,
         message,
@@ -541,6 +543,7 @@ export function registerBlueprintRouter(cli) {
         .option("--template <name>", "Template name to scaffold new blueprint from (see --list-templates)")
         .option("--list-templates", "List available template names and exit")
         .option("--templates-dir <path>", "Override the templates directory (default: docs/templates/)")
+        .option("--confirm", "Confirm destructive blueprint abandon")
         .action(async (subcommand, args, options) => {
         try {
             await executeBlueprintSubcommand(subcommand, args, options, {

package/dist/esm/cli/commands/ci-preflight.js

@@ -24,9 +24,12 @@ export const CI_PREFLIGHT_COMMAND_HELP = [
     "Runs, in order, stopping at the first failure:",
     "  1. wp format --affected --branch --check",
     "  2. wp audit guardrails --affected --branch",
-    "  3. wp typecheck --affected --branch",
-    "  4. wp lint --affected --branch",
-    "  5. wp test --affected --branch",
+    "  3. wp audit changeset-required --affected --branch",
+    "  4. wp typecheck --affected --branch",
+    "  5. wp typecheck --tests",
+    "  6. wp lint --affected --branch",
+    "  7. wp rust-check --affected --branch",
+    "  8. wp test --affected --branch",
     "",
     "This is what `.husky/pre-push` runs. A normal `git push` (no --no-verify)",
     "must pass it. Network-bound / whole-repo gates (dependency freshness) and",
@@ -42,9 +45,27 @@ export const CI_PREFLIGHT_COMMAND_HELP = [
 export const CI_PREFLIGHT_CHECKS = [
     { label: "format", args: ["format", "--affected", "--branch", "--check"] },
     { label: "guardrails", args: ["audit", "guardrails", "--affected", "--branch"] },
+    // Mirrors the `changeset-missing` blocker `wp_pr_status` computes against a
+    // live PR (`#status/snapshot.js`), scoped to the local branch diff so a
+    // missing changeset surfaces before push instead of after — see
+    // `catalog/agent/rules/ci-cost-local-first.md`. Deliberately excluded from
+    // the `wp audit guardrails` composite (see `changeset-required`'s
+    // `includedInGuardrails: false` in `#audit/registry.js`), so it gets its own
+    // preflight step.
+    { label: "changeset", args: ["audit", "changeset-required", "--affected", "--branch"] },
     { label: "typecheck", args: ["typecheck", "--affected", "--branch"] },
+    // Required test-surface typecheck (tsconfig.test.json). Not branch-scoped:
+    // the tests lane is a single whole-repo tsc project and is the burn-down
+    // gate that keeps test/script types from rotting again.
+    { label: "typecheck-tests", args: ["typecheck", "--tests"] },
     // CI runs lint after typecheck in the Lint & typecheck job; mirror that order.
     { label: "lint", args: ["lint", "--affected", "--branch"] },
+    // TS/JS affectedness (above) says nothing about the Rust crates
+    // (native/session-memory-engine, native/dash-tui, apps/desktop/src-tauri) —
+    // without this stage a Rust-only branch reported every stage above as "no
+    // affected files" and exited green having proven nothing about the Rust
+    // (see `#rust/affected-manifests.js`).
+    { label: "rust", args: ["rust-check", "--affected", "--branch"] },
     { label: "test", args: ["test", "--affected", "--branch"] },
 ];
 function reproduceLine(check) {

package/dist/esm/cli/commands/init/convergence-apply.d.ts

@@ -1,5 +1,87 @@
 import { type ConvergeUnit } from "./convergence.js";
 export { resolveUntrackedCollision } from "./untracked-collision.js";
+/** Bounded timeout for non-hook Git probes (status, add, rev-parse, diff-tree). */
+export declare const GIT_PROBE_TIMEOUT_MS = 15000;
+/**
+ * Default wall for the single hookful `git commit`. Consumer pre-commit chains
+ * (format + audits) routinely exceed the probe budget; Node's spawnSync kills
+ * the child with SIGTERM when `timeout` elapses, which left staged residue and
+ * multi-line partial hook output that looked like success.
+ *
+ * 10 minutes is a durable consumer budget, not infinite hang. Operators can
+ * raise/lower via `WP_SETUP_COMMIT_TIMEOUT_MS` or `AuthorCommitOptions.commitTimeoutMs`.
+ */
+export declare const DEFAULT_GIT_COMMIT_TIMEOUT_MS = 600000;
+/** Max stdout+stderr retained from probe git subprocesses (Node spawnSync maxBuffer). */
+export declare const GIT_MAX_BUFFER: number;
+/**
+ * Max stdout+stderr for the single hookful `git commit`. Quiet hooks cost nothing
+ * (Node does not preallocate); chatty consumer format+audit chains can exceed 1 MiB
+ * and would otherwise die with ENOBUFS+SIGTERM mid-commit.
+ */
+export declare const GIT_COMMIT_MAX_BUFFER: number;
+/** True when spawnSync killed the child for maxBuffer / stdio overflow. */
+export declare function isBufferOverflowErrorCode(code: string | null | undefined): boolean;
+/**
+ * Resolve the hookful-commit timeout. Preference order:
+ * 1. explicit `commitTimeoutMs` option (tests / programmatic callers)
+ * 2. `WP_SETUP_COMMIT_TIMEOUT_MS` env (operator override)
+ * 3. {@link DEFAULT_GIT_COMMIT_TIMEOUT_MS}
+ *
+ * Values must be finite numbers ≥ 0. `0` disables the artificial wall (Node default).
+ */
+export declare function resolveCommitTimeoutMs(options?: {
+    readonly commitTimeoutMs?: number;
+    readonly env?: NodeJS.ProcessEnv;
+}): number;
+/** First-class timeout diagnosis; partial hook stdout/stderr is diagnostic only. */
+export declare function formatCommitTimeoutError(options: {
+    readonly timeoutMs: number;
+    readonly hookOutput?: string;
+}): string;
+/**
+ * First-class interrupt diagnosis for non-timeout signal kills (operator kill,
+ * external SIGTERM/SIGKILL). Must not surface raw hook "passed" lines as the
+ * leading operator message.
+ */
+export declare function formatCommitInterruptError(options: {
+    readonly signal: NodeJS.Signals;
+    readonly hookOutput?: string;
+}): string;
+/**
+ * First-class diagnosis when Node spawnSync kills the child because hook/git
+ * output exceeded maxBuffer (ENOBUFS / ERR_CHILD_PROCESS_STDIO_MAXBUFFER).
+ * Distinct from budget timeout and from external signal kills.
+ */
+export declare function formatCommitBufferError(options: {
+    readonly maxBufferBytes: number;
+    readonly errorCode?: string | null;
+    readonly hookOutput?: string;
+}): string;
+/**
+ * Classify a failed hookful `git commit` result.
+ *
+ * Order (first match wins):
+ * 1. `timedOut` (spawnSync ETIMEDOUT) → budget timeout diagnosis
+ * 2. buffer overflow (ENOBUFS / ERR_CHILD_PROCESS_STDIO_MAXBUFFER) → buffer-limit diagnosis
+ * 3. non-null `signal` → interrupt diagnosis (names the signal)
+ * 4. otherwise → hook/git stderr when present, else spawn errorCode / generic preserved-index
+ *
+ * Never lead with bare hook "passed" lines for first-class failure paths.
+ */
+export declare function classifyCommitFailure(result: {
+    readonly timedOut: boolean;
+    readonly signal: NodeJS.Signals | null;
+    readonly stderr: string;
+    readonly stdout: string;
+    readonly errorCode?: string | null;
+}, timeoutMs: number, maxBufferBytes?: number): string;
+/**
+ * Prefix every line of a setup failure so multi-line timeout diagnoses stay
+ * labeled when printed via console.error (avoids a single `wp setup: ` on the
+ * first line and bare hook "passed" lines after it).
+ */
+export declare function formatWpSetupError(message: string): string;
 export type AuthorCommitStatus = "committed" | "no-change" | "skipped-ci" | "failed" | "rolled-back";
 export interface AuthorCommitResult {
     readonly status: AuthorCommitStatus;
@@ -15,6 +97,11 @@ export interface AuthorCommitOptions {
     readonly appliedUnits: readonly ConvergeUnit[];
     readonly message: string;
     readonly isCi?: boolean;
+    /**
+     * Override wall for the single hookful `git commit` (ms). Prefer this in tests.
+     * `0` disables the artificial timeout. Probe Git calls always stay on the short budget.
+     */
+    readonly commitTimeoutMs?: number;
 }
 export interface AppliedConvergenceCandidate {
     readonly targetPath: string;