@webpresso/agent-kit 3.3.0 → 3.3.2

package/dist/esm/ci/release-progress.js

@@ -0,0 +1,139 @@
+/**
+ * Classify a GitHub Actions Release run into operator-facing progress phases.
+ *
+ * After Version Packages merge, agents must not sit on silent `npm view` polls:
+ * merge, native matrix, and npm publish are separate states. This pure helper
+ * maps job list snapshots (from `gh run view --json jobs`) into those states.
+ */
+const NATIVE_JOB_PREFIX = "Session memory native";
+function isNativeJob(name) {
+    return name.startsWith(NATIVE_JOB_PREFIX);
+}
+function isFailure(conclusion) {
+    return conclusion === "failure" || conclusion === "cancelled" || conclusion === "timed_out";
+}
+function isSuccess(conclusion) {
+    return conclusion === "success" || conclusion === "skipped";
+}
+/**
+ * Classify release workflow jobs into a single progress phase for agent/ops reporting.
+ */
+export function classifyReleaseRunProgress(jobs) {
+    const nativeJobs = jobs.filter((job) => isNativeJob(job.name));
+    const detect = jobs.find((job) => job.name === "Detect publishable versions");
+    const release = jobs.find((job) => job.name === "Release");
+    const nativeDone = nativeJobs.filter((job) => job.status === "completed" && isSuccess(job.conclusion)).length;
+    const nativeFailed = nativeJobs.filter((job) => job.status === "completed" && isFailure(job.conclusion)).length;
+    const nativeInProgress = nativeJobs.filter((job) => job.status === "in_progress").length;
+    const native = {
+        done: nativeDone,
+        total: nativeJobs.length,
+        failed: nativeFailed,
+        inProgress: nativeInProgress,
+    };
+    const publishRunning = release?.status === "in_progress";
+    const publishDone = release?.status === "completed" && isSuccess(release.conclusion);
+    const publishFailed = release?.status === "completed" && isFailure(release.conclusion);
+    if (nativeFailed > 0 || publishFailed) {
+        return {
+            phase: "failed",
+            detail: nativeFailed > 0
+                ? `Native matrix failed (${nativeFailed} cell(s))`
+                : `Release/publish job failed (${release?.conclusion ?? "unknown"})`,
+            native,
+            publishRunning,
+            publishDone,
+            publishFailed,
+        };
+    }
+    if (publishDone) {
+        return {
+            phase: "done",
+            detail: "Release job completed successfully (check npm for version)",
+            native,
+            publishRunning,
+            publishDone,
+            publishFailed,
+        };
+    }
+    if (publishRunning || (native.total > 0 && nativeDone === native.total && release)) {
+        return {
+            phase: "publish",
+            detail: publishRunning
+                ? "Native matrix complete; Release/publish job in progress"
+                : "Native matrix complete; waiting for Release job",
+            native,
+            publishRunning,
+            publishDone,
+            publishFailed,
+        };
+    }
+    if (native.total > 0 && (nativeInProgress > 0 || nativeDone < native.total)) {
+        return {
+            phase: "native-matrix",
+            detail: `Building session-memory natives ${nativeDone}/${native.total} complete` +
+                (nativeInProgress > 0 ? ` (${nativeInProgress} in progress)` : ""),
+            native,
+            publishRunning,
+            publishDone,
+            publishFailed,
+        };
+    }
+    if (detect && detect.status !== "completed") {
+        return {
+            phase: "detect",
+            detail: "Detecting whether this run will publish",
+            native,
+            publishRunning,
+            publishDone,
+            publishFailed,
+        };
+    }
+    return {
+        phase: "detect",
+        detail: "Release run starting",
+        native,
+        publishRunning,
+        publishDone,
+        publishFailed,
+    };
+}
+/** Format one line for agent/ops logs (merge vs matrix vs publish). */
+export function formatReleaseProgressLine(progress) {
+    return `release-progress phase=${progress.phase} native=${progress.native.done}/${progress.native.total} ${progress.detail}`;
+}
+/**
+ * Parse `gh run view <id> --json jobs` (or full run object with `jobs`) into snapshots.
+ * Production CLI and tests share this path so classification is never reimplemented.
+ */
+export function jobsFromGhRunViewJson(payload) {
+    if (payload == null || typeof payload !== "object") {
+        throw new Error("gh run view JSON must be an object with a jobs array");
+    }
+    const record = payload;
+    const jobsRaw = Array.isArray(payload)
+        ? payload
+        : Array.isArray(record.jobs)
+            ? record.jobs
+            : null;
+    if (!jobsRaw) {
+        throw new Error("gh run view JSON must include a jobs array");
+    }
+    return jobsRaw.map((entry, index) => {
+        if (entry == null || typeof entry !== "object") {
+            throw new Error(`jobs[${index}] must be an object`);
+        }
+        const job = entry;
+        const name = typeof job.name === "string" ? job.name : "";
+        const status = typeof job.status === "string" ? job.status : "";
+        if (!name || !status) {
+            throw new Error(`jobs[${index}] requires string name and status`);
+        }
+        const conclusion = job.conclusion === null || job.conclusion === undefined
+            ? null
+            : typeof job.conclusion === "string"
+                ? job.conclusion
+                : null;
+        return { name, status, conclusion };
+    });
+}

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

@@ -5,7 +5,7 @@
  * Lazy-loads subcommand modules based on the first argv to keep startup
  * cheap. Modeled on apps/cli-wp/src/cli.ts.
  */
-declare const SUPPORTED_COMMANDS: readonly ["blueprint", "browser", "dash", "dash-helper-start", "dash-helper-complete", "claude", "codex", "grok", "opencode", "yolo", "config", "secrets", "roadmap", "status", "review", "sync", "audit", "qa", "ultragoal", "compile", "rule", "skill", "skills", "docs", "setup", "init", "dev", "deploy", "preview", "cleanup", "migrate", "doctor", "err", "test", "e2e", "ci", "ci-preflight", "public:readiness", "typecheck", "lint", "format", "rust-check", "logs", "session-id", "session-info", "session", "tech-debt", "pr", "fleet", "worktree", "mcp", "hook", "hooks", "self-install-guard", "optional-tool-refresh", "gain", "bench", "install", "add", "remove", "update", "exec", "run"];
+declare const SUPPORTED_COMMANDS: readonly ["blueprint", "browser", "dash", "dash-helper-start", "dash-helper-complete", "claude", "codex", "grok", "opencode", "yolo", "config", "secrets", "roadmap", "status", "review", "sync", "audit", "qa", "ultragoal", "compile", "rule", "skill", "skills", "docs", "setup", "init", "dev", "deploy", "preview", "cleanup", "migrate", "doctor", "err", "test", "e2e", "ci", "ci-preflight", "release-progress", "public:readiness", "typecheck", "lint", "format", "rust-check", "logs", "session-id", "session-info", "session", "tech-debt", "pr", "fleet", "worktree", "mcp", "hook", "hooks", "self-install-guard", "optional-tool-refresh", "gain", "bench", "install", "add", "remove", "update", "exec", "run"];
 export type SupportedCommand = (typeof SUPPORTED_COMMANDS)[number];
 type RootHelpEntry = {
     readonly command: string;

package/dist/esm/cli/cli.js

@@ -55,6 +55,7 @@ const SUPPORTED_COMMANDS = [
     "e2e",
     "ci",
     "ci-preflight",
+    "release-progress",
     "public:readiness",
     "typecheck",
     "lint",
@@ -118,6 +119,10 @@ const ROOT_HELP_CORE_ENTRIES = [
         command: "ci-preflight",
         description: "Run the locally-runnable required CI checks fail-fast (the pre-push gate)",
     },
+    {
+        command: "release-progress",
+        description: "Report Release workflow phase (detect / native-matrix / publish) instead of silent npm view waits",
+    },
     {
         command: "public:readiness",
         description: "Run the public package readiness gate through the portable wp surface",
@@ -375,6 +380,10 @@ const COMMAND_REGISTRARS = {
         const { registerCiPreflightCommand } = await import("./commands/ci-preflight.js");
         registerCiPreflightCommand(cli);
     },
+    "release-progress": async (cli) => {
+        const { registerReleaseProgressCommand } = await import("./commands/release-progress.js");
+        registerReleaseProgressCommand(cli);
+    },
     "public:readiness": async (cli) => {
         const { registerPublicReadinessCommand } = await import("./commands/public-readiness.js");
         registerPublicReadinessCommand(cli);

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/mutations.js

@@ -17,7 +17,7 @@ import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { parseBlueprint } from "#core/parser";
-import { escapeRegex } from "#utils/string";
+import { buildTaskHeaderRegexForId } from "#markdown/task-heading";
 import { openDb } from "#db/connection.js";
 import { resolveBlueprintProjectionDbPath, withMarkdownWriteLock } from "#db/paths.js";
 import { getBlueprintDocumentPaths } from "#utils/document-paths.js";
@@ -209,8 +209,7 @@ function upsertCompletedAt(content, isoDate) {
  * Returns { lineIndex, currentStatus } or null if not found.
  */
 function findTaskStatusLine(lines, taskId) {
-    const escapedId = escapeRegex(taskId);
-    const taskPattern = new RegExp(`^####\\s+(?:\\[[^\\]]+\\]\\s+)?Task\\s+${escapedId}[:\\s]`);
+    const taskPattern = buildTaskHeaderRegexForId(taskId);
     let inBlock = false;
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i] ?? "";

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/init/convergence-apply.d.ts

@@ -12,6 +12,16 @@ export declare const GIT_PROBE_TIMEOUT_MS = 15000;
  * 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)
@@ -38,21 +48,34 @@ 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.
  *
- * - `timedOut` (spawnSync ETIMEDOUT) → budget timeout diagnosis
- * - non-null `signal` without timedOut → interrupt diagnosis (names the signal)
- * - otherwise → hook/git stderr when present, else a generic preserved-index message
+ * 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 timeout/interrupt paths.
+ * 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;
-}, timeoutMs: number): 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