@webpresso/agent-kit 3.1.30 → 3.3.0

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

@@ -1,25 +1,48 @@
 import { buildRoadmapModel, planStatusSchema } from "#local";
+export const BLUEPRINT_SUBCOMMANDS = [
+    { name: "list", usage: ["list [status]"] },
+    {
+        name: "new",
+        usage: ["new <goal> --complexity <XS|S|M|L|XL> [--type <blueprint|parent-roadmap>]"],
+    },
+    { name: "show", usage: ["show <slug>"] },
+    {
+        name: "exec",
+        usage: [
+            "exec <slug>",
+            "exec status <slug>",
+            "exec resume <slug>",
+            "exec stop <slug>",
+            "exec logs <slug>",
+        ],
+    },
+    { name: "start", usage: ["start <slug>"] },
+    { name: "park", usage: ["park <slug>"] },
+    {
+        name: "task",
+        usage: [
+            "task start <slug> <taskId>",
+            "task block <slug> <taskId> --reason <text>",
+            "task unblock <slug> <taskId>",
+            "task complete <slug> <taskId>",
+        ],
+    },
+    { name: "finalize", usage: ["finalize <slug>"] },
+    { name: "promote", usage: ["promote <slug> <planned|in-progress|completed|parked>"] },
+    { name: "audit", usage: ["audit [--staged|--all] [--strict]"] },
+    { name: "move", usage: ["move <slug> <status> --force-recovery"] },
+    { name: "canonicalize", usage: ["canonicalize <slug>"] },
+    { name: "control", usage: ["control <status|resume|stop> <slug>"] },
+    { name: "logs", usage: ["logs <slug>"] },
+    { name: "db", usage: ["db <verb> [...args]"] },
+    { name: "export", usage: ["export --format spec-kit <slug>"] },
+    { name: "trust-dossier", usage: ["trust-dossier"] },
+];
 const BLUEPRINT_HELP = [
     "Blueprint management",
     "",
     "Commands:",
-    "  list [status]",
-    "  new <goal> --complexity <XS|S|M|L|XL> [--type <blueprint|parent-roadmap>]",
-    "  show <slug>",
-    "  exec <slug>",
-    "  exec status <slug>",
-    "  exec resume <slug>",
-    "  exec stop <slug>",
-    "  exec logs <slug>",
-    "  start <slug>",
-    "  park <slug>",
-    "  task start <slug> <taskId>",
-    "  task block <slug> <taskId> --reason <text>",
-    "  task unblock <slug> <taskId>",
-    "  task complete <slug> <taskId>",
-    "  finalize <slug>",
-    "  audit [--staged|--all] [--strict]",
-    "  move <slug> <status> --force-recovery",
+    ...BLUEPRINT_SUBCOMMANDS.flatMap((spec) => spec.usage.map((line) => `  ${line}`)),
 ].join("\n");
 export function formatTaskLine(task) {
     const checkbox = task.status === "done" || task.status === "dropped" ? "x" : " ";
@@ -28,6 +51,14 @@ export function formatTaskLine(task) {
 export function getBlueprintHelpText() {
     return BLUEPRINT_HELP;
 }
+/**
+ * Subcommand names in registry order, for the unknown-subcommand error
+ * message. Kept as a function (rather than exporting a derived constant)
+ * so the source of truth stays singular: `BLUEPRINT_SUBCOMMANDS`.
+ */
+export function getBlueprintSubcommandNames() {
+    return BLUEPRINT_SUBCOMMANDS.map((spec) => spec.name);
+}
 export function summarizeBlueprintInventory(summaries) {
     const byStatus = Object.fromEntries(planStatusSchema.options.toSorted().map((status) => [status, 0]));
     const byType = {

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

@@ -73,6 +73,12 @@ export interface BlueprintLifecycleMutationResult {
     status: string;
     taskId?: string;
 }
+export interface BlueprintCanonicalizeResult {
+    from: string;
+    to: string;
+    moved: boolean;
+    message: string;
+}
 export interface CreateBlueprintResult extends CreatedBlueprint {
     message: string;
     /** True when draft was auto-routed off a primary-like checkout (H-009 DX). */
@@ -123,6 +129,7 @@ export declare function exportBlueprint(slug: string, format: string, options?:
 export declare function advanceBlueprintTask(slug: string, taskId: string, toStatus: string, options?: BlueprintMoveOptions): Promise<AdvanceTaskResult>;
 export declare function promoteBlueprintToState(slug: string, toState: string, options?: BlueprintMoveOptions): Promise<PromoteBlueprintResult>;
 export declare function finalizeBlueprintBySlug(slug: string, options?: BlueprintMoveOptions): Promise<PromoteBlueprintResult>;
+export declare function canonicalizeBlueprintBySlug(slug: string, options?: BlueprintMoveOptions): Promise<BlueprintCanonicalizeResult>;
 export declare function registerBlueprintRouter(cli: CAC): void;
 export declare function _setBlueprintExecCommandExistsForTests(probe: ((command: string) => boolean) | null): void;
 export declare function _setBlueprintExecStarterForTests(starter: ((slug: string, options: BlueprintMoveOptions) => Promise<BlueprintLifecycleMutationResult>) | null): void;

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

@@ -10,6 +10,7 @@ import { resolveCurrentManagedWorktreeContext } from "#worktrees/current.js";
 import { canonicalizeWorktreePath, WORKTREE_PROBE_TIMEOUT_MS } from "#worktrees/identity.js";
 import { resolveBlueprintRoot } from "#utils/blueprint-root";
 import { getBlueprintDocumentPaths } from "#utils/document-paths.js";
+import { canonicalizeBlueprint } from "#lifecycle/canonicalize.js";
 import { applyBlueprintLifecycleToFile, BlueprintCreationService, BlueprintService, complexitySchema, relativeBlueprintSlug, parseBlueprint, planStatusSchema, runBlueprintAudit, resolveBlueprintFile, serializeBlueprint, validateAllTasksDone, } from "#local";
 import { resolvePackageAssetPreferred } from "#utils/package-assets";
 import { resolveDraftAuthoringRoot } from "#worktrees/draft-authoring-root.js";
@@ -512,9 +513,19 @@ export async function finalizeBlueprintBySlug(slug, options = {}) {
     const projectRoot = resolveProjectRoot(options.projectRoot);
     return finalizeBlueprintMutation(projectRoot, slug);
 }
+export async function canonicalizeBlueprintBySlug(slug, options = {}) {
+    const projectRoot = resolveProjectRoot(options.projectRoot);
+    const result = await canonicalizeBlueprint(projectRoot, slug);
+    return {
+        ...result,
+        message: result.moved
+            ? `Canonicalized blueprint ${slug}: ${result.from} -> ${result.to}`
+            : `Blueprint ${slug} is already canonical: ${result.to}`,
+    };
+}
 export function registerBlueprintRouter(cli) {
     cli
-        .command("blueprint [subcommand] [...args]", "Manage blueprints. Use: wp blueprint <action> --help for action-specific options (new, list, show, audit, exec, move, finalize, start, task)")
+        .command("blueprint [subcommand] [...args]", "Manage blueprints. Use: wp blueprint <action> --help for action-specific options (new, list, show, audit, exec, move, finalize, start, task, trust-dossier)")
         .option("--json", "Print JSON output")
         .option("--no-tui", "Use plain terminal output")
         .option("--complexity <complexity>", "Blueprint complexity (XS|S|M|L|XL)")
@@ -535,6 +546,7 @@ export function registerBlueprintRouter(cli) {
             await executeBlueprintSubcommand(subcommand, args, options, {
                 advanceBlueprintTask,
                 auditBlueprints,
+                canonicalizeBlueprintBySlug,
                 createBlueprint,
                 controlBlueprintExec,
                 executeBlueprint,

package/dist/esm/cli/commands/ci-preflight.d.ts

@@ -31,9 +31,20 @@ export interface CiPreflightDeps {
     readonly cwd?: string;
     readonly resolveRepoRoot?: (cwd: string) => string | null;
     readonly hasNodeModules?: (repoRoot: string) => boolean;
-    readonly runCheck?: (check: CiPreflightCheck, repoRoot: string) => number;
+    readonly runCheck?: (check: CiPreflightCheck, repoRoot: string) => number | Promise<number>;
     readonly stdout?: Pick<typeof process.stdout, "write">;
     readonly stderr?: Pick<typeof process.stderr, "write">;
 }
-export declare function runCiPreflight(deps?: CiPreflightDeps): number;
+/**
+ * Re-invoke the same `wp` runtime that is currently executing so each check
+ * runs the real verb (faithful CI parity) rather than a reimplemented copy of
+ * its affected-resolution logic. Prefers the repo-local `bin/wp` launcher when
+ * present so the exact source/compiled selection and NODE_PATH wiring apply;
+ * falls back to the running runtime for consumer repos with a global `wp`.
+ */
+export declare function resolveWpLauncher(repoRoot: string): {
+    readonly command: string;
+    readonly prefixArgs: readonly string[];
+};
+export declare function runCiPreflight(deps?: CiPreflightDeps): Promise<number>;
 export declare function registerCiPreflightCommand(cli: CAC): void;

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) {
@@ -57,7 +78,10 @@ function reproduceLine(check) {
  * present so the exact source/compiled selection and NODE_PATH wiring apply;
  * falls back to the running runtime for consumer repos with a global `wp`.
  */
-function resolveWpLauncher(repoRoot) {
+// Exported so `src/mcp/tools/ci-preflight.ts` can re-invoke the exact same
+// `wp` launcher when it substitutes an output-capturing `runCheck` for the
+// default `stdio: "inherit"` spawn — do not duplicate this resolution logic.
+export function resolveWpLauncher(repoRoot) {
     const localLauncher = path.join(repoRoot, "bin", process.platform === "win32" ? "wp.cmd" : "wp");
     if (existsSync(localLauncher))
         return { command: localLauncher, prefixArgs: [] };
@@ -82,7 +106,7 @@ function defaultRunCheck(check, repoRoot) {
     }
     return typeof result.status === "number" ? result.status : 1;
 }
-export function runCiPreflight(deps = {}) {
+export async function runCiPreflight(deps = {}) {
     const cwd = deps.cwd ?? process.cwd();
     const stdout = deps.stdout ?? process.stdout;
     const stderr = deps.stderr ?? process.stderr;
@@ -100,7 +124,7 @@ export function runCiPreflight(deps = {}) {
     }
     for (const check of CI_PREFLIGHT_CHECKS) {
         stdout.write(`\nwp ci-preflight: running ${check.label} (${reproduceLine(check)})\n`);
-        const exitCode = runCheck(check, repoRoot);
+        const exitCode = await runCheck(check, repoRoot);
         if (exitCode !== 0) {
             const normalizedExit = exitCode === 0 ? 1 : exitCode;
             stderr.write(`\nwp ci-preflight: ${check.label} failed (exit ${normalizedExit}).\n` +

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

@@ -247,22 +247,10 @@ export async function runCompile(options) {
                 message: `wp compile: rulesync exited with code ${exitCode}`,
             };
         }
-        // Step 4: Emit plugin manifests in parallel
-        const skillNames = Object.keys(assets.skills);
-        const commandNames = Object.keys(assets.commands);
-        const pkgVersion = readPackageVersion(cwd);
-        const manifestOpts = {
-            agentDir,
-            outDir: cwd,
-            version: pkgVersion,
-            skills: skillNames,
-            commands: commandNames,
-        };
-        await Promise.all([
-            import("#compiler/manifests/claude").then((m) => m.emitManifest(manifestOpts)),
-            import("#compiler/manifests/codex").then((m) => m.emitManifest(manifestOpts)),
-        ]);
-        // Step 5: Run mergeAgentsMd to produce AGENTS.md at repo root
+        // Step 4: Run mergeAgentsMd to produce AGENTS.md at repo root
+        // (Plugin manifests are hand-maintained SSOT under packages/*-plugin/;
+        // wp compile no longer emits them — golden tests + version stamping own
+        // that surface.)
         const agentsLayers = collectAgentsLayers(agentDir);
         if (agentsLayers.length > 0) {
             const { mergeAgentsMd } = await import("#compiler/memory/merger");
@@ -278,11 +266,9 @@ export async function runCompile(options) {
                 writeFileSync(join(cwd, "AGENTS.md"), mergeResult.content);
             }
         }
-        // Step 6: Write .compile-manifest.json with content-hash sentinels
+        // Step 5: Write .compile-manifest.json with content-hash sentinels
         const outputHashes = {
             "AGENTS.md": hashFile(join(cwd, "AGENTS.md")),
-            "packages/claude-plugin/.claude-plugin/plugin.json": hashFile(join(cwd, "packages", "claude-plugin", ".claude-plugin", "plugin.json")),
-            "packages/codex-plugin/.codex-plugin/plugin.json": hashFile(join(cwd, "packages", "codex-plugin", ".codex-plugin", "plugin.json")),
         };
         const compileManifest = {
             version: COMPILE_MANIFEST_VERSION,
@@ -303,18 +289,6 @@ export async function runCompile(options) {
         cleanup();
     }
 }
-function readPackageVersion(cwd) {
-    const pkgPath = join(cwd, "package.json");
-    if (!existsSync(pkgPath))
-        return "0.0.0";
-    try {
-        const parsed = JSON.parse(readFileSync(pkgPath, "utf-8"));
-        return typeof parsed.version === "string" ? parsed.version : "0.0.0";
-    }
-    catch {
-        return "0.0.0";
-    }
-}
 function collectAgentsLayers(agentDir) {
     const agentsDir = join(agentDir, "agents");
     if (!existsSync(agentsDir))

package/dist/esm/cli/commands/dash/delivery-status.d.ts

@@ -56,3 +56,4 @@ export type DeliveryStatusOptions = {
  * prior values and expose a retryable adapter warning.
  */
 export declare function collectDeliveryStatus(options?: DeliveryStatusOptions): Promise<DeliveryStatus>;
+export declare function blueprintDocumentPath(cwd: string, state: string, slug: string): string | null;

package/dist/esm/cli/commands/dash/delivery-status.js

@@ -107,14 +107,21 @@ function checkState(value) {
         return "pending";
     return states.length > 0 ? "passing" : "unknown";
 }
+export function blueprintDocumentPath(cwd, state, slug) {
+    const folder = join(cwd, "blueprints", state, slug, "_overview.md");
+    if (existsSync(folder))
+        return folder;
+    const flat = join(cwd, "blueprints", state, `${slug}.md`);
+    return existsSync(flat) ? flat : null;
+}
 function readBlueprintDelivery(cwd) {
     const branch = run("git", ["branch", "--show-current"], cwd);
     if (!branch?.startsWith("bp/"))
         return null;
     const slug = branch.slice(3);
     for (const state of ["in-progress", "planned", "draft", "completed", "parked", "archived"]) {
-        const path = join(cwd, "blueprints", state, slug, "_overview.md");
-        if (!existsSync(path))
+        const path = blueprintDocumentPath(cwd, state, slug);
+        if (!path)
             continue;
         const raw = readFileSync(path, "utf8");
         return {
@@ -129,8 +136,8 @@ function readVerificationDelivery(cwd) {
     const blueprint = readBlueprintDelivery(cwd);
     if (!blueprint)
         return null;
-    const path = join(cwd, "blueprints", blueprint.state, blueprint.slug, "_overview.md");
-    if (!existsSync(path))
+    const path = blueprintDocumentPath(cwd, blueprint.state, blueprint.slug);
+    if (!path)
         return null;
     const raw = readFileSync(path, "utf8");
     const evidenceCount = (raw.match(/^\*\*Verification:\*\*/gmu) ?? []).length;

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

@@ -1,4 +1,5 @@
 import { auditBlueprintLifecycleSql } from "#audit/blueprint-lifecycle-sql";
+import { auditCiGuardrailsWiring } from "#audit/ci-guardrails-wiring";
 import { readConfig } from "#cli/commands/init/config";
 import { auditCatalogDrift, auditDocsFrontmatter, formatRepoAuditReport, } from "#audit/repo-guardrails";
 import { countWorktreeLifecycleScripts } from "#worktrees/lifecycle-scripts.js";
@@ -7,6 +8,9 @@ const REMEDIATIONS = {
     "Catalog drift — single package (no workspace file)": "none needed",
     "Docs frontmatter": "wp audit docs-frontmatter --fix",
     "Blueprint lifecycle": "wp audit blueprint-lifecycle",
+    // Name the missing invocation explicitly so an operator sees which CI step to
+    // restore, not just a generic "drifted" signal.
+    "CI guardrails wiring": "restore the `wp audit guardrails` CI step (run `wp setup`)",
 };
 export async function runDoctor(options = {}) {
     try {
@@ -17,6 +21,7 @@ export async function runDoctor(options = {}) {
                 docsRoot: options.docsRoot,
                 fix: options.fix,
             }),
+            auditCiGuardrailsWiring(root),
             await auditBlueprintLifecycleSql(root, { includeRuntimePlans: options.runtimePlans }),
         ];
         let failed = false;

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

@@ -1,4 +1,9 @@
 import type { CAC } from "cac";
+/**
+ * Registered GUARD_* codes emitted by the hook-command fail-closed path.
+ * Consumed by the guard-outcome registry-completeness test.
+ */
+export declare const HOOK_FALLBACK_GUARD_CODES: readonly ["GUARD_PRETOOL_FAILURE"];
 declare const HOOK_NAMES: readonly ["pretool-guard", "post-tool", "stop-qa", "stop-ultragoal", "guard-switch", "sessionstart-routing", "precompact-snapshot", "permission-request", "test-quality-check"];
 export type HookName = (typeof HOOK_NAMES)[number];
 export declare function isHookName(value: string): value is HookName;

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

@@ -2,8 +2,16 @@ import { performance } from "node:perf_hooks";
 import { reportHookDegradation, takeHookDegradation, } from "#hooks/errors/index.js";
 import { recordHookInvocation, summarizeHookText, takeRememberedHookStdin, } from "#hooks/logs/store.js";
 import { createSyntheticProcessExit, isSyntheticProcessExit, } from "#hooks/shared/synthetic-process-exit.js";
-import { writeHookOutput } from "#hooks/shared/hook-bootstrap";
+import { writeGuardStderr, writeHookOutput } from "#hooks/shared/hook-bootstrap";
+import { formatGuardReason } from "#hooks/shared/guard-outcome.js";
 import { buildDenyEnvelope } from "#hooks/shared/types.js";
+/**
+ * Registered GUARD_* codes emitted by the hook-command fail-closed path.
+ * Consumed by the guard-outcome registry-completeness test.
+ */
+export const HOOK_FALLBACK_GUARD_CODES = [
+    "GUARD_PRETOOL_FAILURE",
+];
 import { resolveHookProjectDirFromText } from "#hooks/shared/project-dir.js";
 import { createManagedHookExecutionContext, } from "#hooks/shared/session-memory-deadline.js";
 const HOOK_NAMES = [
@@ -101,13 +109,9 @@ function exitCodeFrom(value) {
 }
 function writePretoolDeny(reason) {
     writeHookOutput(`${JSON.stringify(buildDenyEnvelope({ reason }))}\n`);
-    // Best-effort stderr reason for Claude/Codex exit-2 UX (may be suppressed in some runners).
-    try {
-        process.stderr.write(`${reason}\n`);
-    }
-    catch {
-        // ignore
-    }
+    // Deliver to the REAL stderr too: Claude reads stderr on an exit-2 PreToolUse
+    // deny, and it is suppressed for decorative output.
+    writeGuardStderr(`${reason}\n`);
 }
 function emitFallback(name, error) {
     const metadata = HOOK_METADATA[name];
@@ -121,7 +125,9 @@ function emitFallback(name, error) {
         detail,
     });
     if (metadata.fallback === "fail-closed-deny") {
-        writePretoolDeny(`webpresso pretool guard failed: ${detail}`);
+        // Coded fail-closed denial so the host still sees a stable GUARD_ code even
+        // when the guard handler itself threw.
+        writePretoolDeny(formatGuardReason("GUARD_PRETOOL_FAILURE", `webpresso pretool guard failed: ${detail}`));
         // Exit 2 so Grok (and exit-code runners) treat fail-closed as an explicit deny.
         return 2;
     }

package/dist/esm/cli/commands/init/config.js

@@ -4,7 +4,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, normalize } from "node:path";
-import { REQUIRED_CORE_CAPABILITIES } from "./host-visibility.js";
+import { AGENT_HOSTS, REQUIRED_CORE_CAPABILITIES } from "./host-visibility.js";
 export const CONFIG_VERSION = "1";
 export const CONFIG_FILENAME = ".webpressorc.json";
 export const LEGACY_CONFIG_FILENAME = ".agent-kitrc.json";
@@ -136,7 +136,7 @@ function parseConfigFile(path) {
             }
             : undefined;
         const selectedHosts = Array.isArray(hosts?.selected)
-            ? hosts.selected.filter((s) => ["codex", "claude", "opencode"].includes(String(s)))
+            ? hosts.selected.filter((s) => AGENT_HOSTS.includes(String(s)))
             : [];
         const requiredCapabilities = Array.isArray(hosts?.requiredCapabilities)
             ? hosts.requiredCapabilities.filter((s) => typeof s === "string")

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

@@ -0,0 +1,88 @@
+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;
+/**
+ * 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;
+/**
+ * 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
+ *
+ * Never lead with bare hook "passed" lines for timeout/interrupt paths.
+ */
+export declare function classifyCommitFailure(result: {
+    readonly timedOut: boolean;
+    readonly signal: NodeJS.Signals | null;
+    readonly stderr: string;
+    readonly stdout: string;
+}, timeoutMs: 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;
+    readonly ok: boolean;
+    readonly commit?: string;
+    readonly allowlist: readonly string[];
+    readonly unexpectedPaths?: readonly string[];
+    readonly missingPaths?: readonly string[];
+    readonly error?: string;
+}
+export interface AuthorCommitOptions {
+    readonly repoRoot: string;
+    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;
+    readonly reason: string;
+}
+export declare function collectAppliedConvergeUnits(repoRoot: string, candidates: readonly AppliedConvergenceCandidate[]): ConvergeUnit[];
+export declare function authorConvergenceCommit(options: AuthorCommitOptions): AuthorCommitResult;