@webpresso/agent-kit 3.3.0 → 3.3.1

package/catalog/agent/rules/pre-implementation.md

@@ -320,6 +320,21 @@ checkout target. Local cleanup and primary resync cannot run from GitHub Actions
 do not claim landing complete until this cleanup succeeds or is recorded as a
 blocker with evidence.
 
+**Owner dirt precondition:** the owner worktree must have empty
+`git status --porcelain` before merge-cleanup. If you ran `wp blueprint new` and
+left `blueprints/draft/<slug>/` uncommitted (or staged only), either:
+
+1. **Land the draft** — include `blueprints/draft/<slug>/` (and complete the
+   lifecycle) in the PR, or
+2. **Abandon the scaffold** — `wp blueprint abandon <slug> --confirm` (preview
+   without `--confirm`), then re-run merge-cleanup.
+
+`Blueprint-exempt` is for work that **never created a blueprint**. Do not
+scaffold a draft only to exempt it. For multi-file exempt follow-ups, use a
+**non-`bp/`** worktree prefix (`exempt/<name>` or `chore/<name>`) via
+`wp worktree new` — never `bp/<slug>`, which pre-claims the owner branch and
+collides with `wp blueprint start`.
+
 When the primary checkout has user-owned edits or is still on a topic branch,
 prefer:
 

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/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

package/dist/esm/cli/commands/init/convergence-apply.js

@@ -14,25 +14,44 @@ export const GIT_PROBE_TIMEOUT_MS = 15_000;
  * raise/lower via `WP_SETUP_COMMIT_TIMEOUT_MS` or `AuthorCommitOptions.commitTimeoutMs`.
  */
 export const DEFAULT_GIT_COMMIT_TIMEOUT_MS = 600_000;
-const GIT_MAX_BUFFER = 1024 * 1024;
-function git(repoRoot, args, timeoutMs) {
+/** Max stdout+stderr retained from probe git subprocesses (Node spawnSync maxBuffer). */
+export const GIT_MAX_BUFFER = 1024 * 1024;
+/**
+ * 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 const GIT_COMMIT_MAX_BUFFER = 16 * 1024 * 1024;
+/** Hook output snippet size kept in first-class failure diagnoses (tail, not head). */
+const HOOK_OUTPUT_SNIPPET_CHARS = 800;
+/** spawnSync error codes that mean maxBuffer / stdio overflow killed the child. */
+const BUFFER_OVERFLOW_ERROR_CODES = new Set(["ENOBUFS", "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"]);
+function git(repoRoot, args, timeoutMs, maxBuffer = GIT_MAX_BUFFER) {
     const result = spawnSync("git", [...args], {
         cwd: repoRoot,
         encoding: "utf8",
         // Node: timeout > 0 arms SIGTERM; 0 / omitted means no artificial wall.
         ...(timeoutMs > 0 ? { timeout: timeoutMs } : {}),
-        maxBuffer: GIT_MAX_BUFFER,
+        maxBuffer,
         stdio: ["ignore", "pipe", "pipe"],
     });
-    const timedOut = result.error !== undefined && "code" in result.error && result.error.code === "ETIMEDOUT";
+    const errorCode = result.error !== undefined && "code" in result.error && result.error.code != null
+        ? String(result.error.code)
+        : null;
+    const timedOut = errorCode === "ETIMEDOUT";
     return {
         ok: result.status === 0 && !result.error,
         stdout: (result.stdout ?? "").trim(),
         stderr: (result.stderr ?? "").trim(),
         timedOut,
         signal: result.signal,
+        errorCode,
     };
 }
+/** True when spawnSync killed the child for maxBuffer / stdio overflow. */
+export function isBufferOverflowErrorCode(code) {
+    return typeof code === "string" && BUFFER_OVERFLOW_ERROR_CODES.has(code);
+}
 /**
  * Resolve the hookful-commit timeout. Preference order:
  * 1. explicit `commitTimeoutMs` option (tests / programmatic callers)
@@ -60,7 +79,10 @@ function appendHookOutput(diagnosis, hookOutput) {
     const trimmed = hookOutput?.trim();
     if (!trimmed)
         return diagnosis;
-    const snippet = trimmed.length > 400 ? `${trimmed.slice(0, 400)}…` : trimmed;
+    // Keep the tail: failing audits / last lines at kill time matter more than husky banner.
+    const snippet = trimmed.length > HOOK_OUTPUT_SNIPPET_CHARS
+        ? `…${trimmed.slice(-HOOK_OUTPUT_SNIPPET_CHARS)}`
+        : trimmed;
     return `${diagnosis}\n--- hook output (truncated) ---\n${snippet}`;
 }
 /** First-class timeout diagnosis; partial hook stdout/stderr is diagnostic only. */
@@ -87,24 +109,57 @@ export function formatCommitInterruptError(options) {
         `Partial hook lines such as "format applied" / "audit … passed" are not success.`;
     return appendHookOutput(diagnosis, options.hookOutput);
 }
+/**
+ * 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 function formatCommitBufferError(options) {
+    const code = options.errorCode?.trim() || "ENOBUFS";
+    const diagnosis = `Convergence commit failed because git/hook output exceeded the spawnSync maxBuffer limit ` +
+        `(${options.maxBufferBytes} bytes; Node error ${code}), so no setup commit was authored. ` +
+        `This is a buffer/output-limit failure, not a time budget timeout and not an external kill. ` +
+        `Staged and worktree changes were preserved for remediation. ` +
+        `Reduce hook verbosity, raise the maxBuffer only with measured need, or fix chatty hooks. ` +
+        `Partial hook lines such as "format applied" / "audit … passed" are not success.`;
+    return appendHookOutput(diagnosis, options.hookOutput);
+}
 /**
  * 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 function classifyCommitFailure(result, timeoutMs) {
+export function classifyCommitFailure(result, timeoutMs, maxBufferBytes = GIT_COMMIT_MAX_BUFFER) {
     const hookOutput = [result.stderr, result.stdout].filter(Boolean).join("\n");
     if (result.timedOut) {
         return formatCommitTimeoutError({ timeoutMs, hookOutput });
     }
+    if (isBufferOverflowErrorCode(result.errorCode)) {
+        return formatCommitBufferError({
+            maxBufferBytes,
+            errorCode: result.errorCode,
+            hookOutput,
+        });
+    }
     if (result.signal) {
         return formatCommitInterruptError({ signal: result.signal, hookOutput });
     }
-    return hookOutput || "git commit failed; hook changes were preserved.";
+    if (hookOutput) {
+        if (result.errorCode) {
+            return `${hookOutput}\n(spawn error ${result.errorCode})`;
+        }
+        return hookOutput;
+    }
+    if (result.errorCode) {
+        return `git commit failed (spawn error ${result.errorCode}); hook changes were preserved.`;
+    }
+    return "git commit failed; hook changes were preserved.";
 }
 /**
  * Prefix every line of a setup failure so multi-line timeout diagnoses stay
@@ -230,13 +285,20 @@ export function authorConvergenceCommit(options) {
     const commitTimeoutMs = resolveCommitTimeoutMs({
         commitTimeoutMs: options.commitTimeoutMs,
     });
-    const commit = git(options.repoRoot, ["commit", "-m", options.message], commitTimeoutMs);
+    const budgetLabel = commitTimeoutMs > 0
+        ? commitTimeoutMs >= 60_000
+            ? `up to ${Math.round(commitTimeoutMs / 60_000)}m`
+            : `up to ${commitTimeoutMs}ms`
+        : "no artificial time wall";
+    // stderr: setup success path stays machine-friendly on stdout; hooks can take minutes.
+    console.error(`wp setup: running repository pre-commit hooks (${budgetLabel})…`);
+    const commit = git(options.repoRoot, ["commit", "-m", options.message], commitTimeoutMs, GIT_COMMIT_MAX_BUFFER);
     if (!commit.ok) {
         return {
             status: "failed",
             ok: false,
             allowlist,
-            error: classifyCommitFailure(commit, commitTimeoutMs),
+            error: classifyCommitFailure(commit, commitTimeoutMs, GIT_COMMIT_MAX_BUFFER),
         };
     }
     const committedHead = probe(["rev-parse", "--verify", "HEAD"]);

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

@@ -71,6 +71,17 @@ export interface OpencodeProbeRunnerInput {
 }
 export type OpencodeProbeRunner = (input: OpencodeProbeRunnerInput) => Promise<OpencodeProbeResult>;
 export declare function isOpencodeProbeEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * 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`.
+ */
+export declare function spawnOpencodeProbe(input: OpencodeProbeRunnerInput): Promise<OpencodeProbeResult>;
 export interface ProbeOpencodeAccountDeps {
     readonly run?: OpencodeProbeRunner;
     readonly materialize?: (key: string, dataDir: string) => void;

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

@@ -157,7 +157,7 @@ function classifyChunk(captured) {
  * 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) {
+export function spawnOpencodeProbe(input) {
     return new Promise((resolve) => {
         let probeCwd;
         try {

package/dist/esm/cli/commands/quality-runner.js

@@ -145,9 +145,13 @@ function renderSummaryLines(summary, transformed, entry, passed) {
     else if (!passed && transformed.rawOutput?.trim()) {
         lines.push(transformed.rawOutput.trimEnd());
     }
-    if (!passed || transformed.truncated) {
+    // Any elided bytes must remain retrievable: fail, clip, OR compaction that
+    // recorded an elision without setting truncated. Hide Full log / retrieve
+    // hints only when the summary still contains the full content.
+    const hasElisions = (transformed.elisions?.length ?? 0) > 0;
+    if (!passed || transformed.truncated || hasElisions) {
         lines.push(`Full log: wp logs ${entry.command}`);
-        if (transformed.elisions && transformed.elisions.length > 0) {
+        if (hasElisions) {
             lines.push(...transformed.elisions.map((elision) => `Retrieve elision: ${elision.retrieveTool} id=${elision.id}`));
         }
     }

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

@@ -24,7 +24,7 @@ export const TYPECHECK_COMMAND_HELP = [
     "  wp typecheck --affected --branch     # changed vs origin/${GITHUB_BASE_REF:-main}",
     "  wp typecheck --pretty",
     "  wp typecheck --tests                 # test-surface lane (tsconfig.test.json); required in",
-    "                                        # not part of the default gate or ci-preflight yet",
+    "                                        # ci-preflight and CI (not the default untargeted gate)",
 ].join("\n");
 export function registerTypecheckCommand(cli, deps = {}) {
     addAffectedOptions(cli

package/dist/esm/cli/commands/worktree/router-dispatch.d.ts

@@ -55,6 +55,12 @@ export interface MergeCleanupDecisionInput {
     readonly repoDirty: boolean;
     readonly targetDirty: boolean;
     readonly stashPrimary?: boolean;
+    /**
+     * When target is dirty, optional porcelain -z + slug enrich the refusal message
+     * (scaffold-only vs other dirt). Omitted messages stay generic for unit tests.
+     */
+    readonly targetPorcelainZ?: string;
+    readonly targetBlueprintSlug?: string;
 }
 export interface NewWorktreeTargetInput {
     branch?: string;
@@ -97,4 +103,6 @@ export interface CreateManagedWorktreeResult {
 export declare function formatWorktreeList(entries: WorktreeEntry[], currentWorktreePath: string): string[];
 export declare function formatManagedWorktreeList(entries: readonly ManagedWorktreeEntry[]): string[];
 export declare function createManagedWorktree(opts?: CreateManagedWorktreeOptions): Promise<CreateManagedWorktreeResult>;
+/** `.../blueprints/<slug>/owner` → slug */
+export declare function inferBlueprintSlugFromOwnerPath(ownerPath: string): string | undefined;
 export declare function executeWorktreeSubcommand(subcommand: string, args: string[], opts: WorktreeCommandOptions): Promise<void>;

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

@@ -15,6 +15,7 @@ import { runWorktreeSetup, runWorktreeTeardown } from "#worktrees/lifecycle-scri
 import { hydrateWorktreeDependencies, reconcileWorktreeDependencies, } from "#worktrees/dependencies.js";
 import { projectWorktreeAgentSurfaces } from "#worktrees/project-agent-surfaces.js";
 import { assertNotLocalMainBranch } from "#worktrees/main-ownership.js";
+import { formatTargetDirtyRefusal } from "#worktrees/owner-dirt.js";
 import { buildWorktreeInventory, canonicalizeWorktreePath, classifyMembership, isManagedWorktreePath, resolveRepoIdentity, } from "#worktrees/identity.js";
 import { findRegistryCandidatesByPath, planStaleWorktreeRegistryPrune, readWorktreeRegistry, removeWorktreeRegistryEntries, repoScopedPathPredicate, upsertWorktreeRegistryEntry, } from "#worktrees/registry.js";
 import { buildRegistryRepoRootMap, classifyOrphanCandidate, discoverOrphanScanCandidates, resolveRepoRootFromGitPointer, } from "#worktrees/orphan-scan.js";
@@ -182,6 +183,13 @@ export function decideMergeCleanup(input) {
         throw new Error(`wp worktree merge-cleanup refused: ${input.targetPath} is locked`);
     }
     if (input.targetDirty) {
+        if (input.targetPorcelainZ !== undefined) {
+            throw new Error(formatTargetDirtyRefusal({
+                targetPath: input.targetPath,
+                porcelainZ: input.targetPorcelainZ,
+                slug: input.targetBlueprintSlug,
+            }));
+        }
         throw new Error(`wp worktree merge-cleanup refused: ${input.targetPath} has uncommitted changes`);
     }
     if (input.repoDirty) {
@@ -561,6 +569,12 @@ function isDirty(path) {
         return true;
     return String(status.stdout ?? "").trim().length > 0;
 }
+/** `.../blueprints/<slug>/owner` → slug */
+export function inferBlueprintSlugFromOwnerPath(ownerPath) {
+    const normalized = ownerPath.replace(/\\/gu, "/");
+    const match = /\/blueprints\/([^/]+)\/owner\/?$/u.exec(normalized);
+    return match?.[1];
+}
 function currentBranch(repoRoot) {
     const result = spawnSync("git", ["branch", "--show-current"], {
         cwd: repoRoot,
@@ -691,6 +705,14 @@ async function handleMergeCleanup(nameOrPath, opts) {
     const scopedRegistryEntries = findRegistryCandidatesByPath(resolved)
         .filter((candidate) => classifyMembership(candidate.entry.repoRoot, mergeAuthKey) === "same")
         .map((candidate) => candidate.entry);
+    const targetDirty = isDirty(resolved);
+    const targetPorcelainZ = targetDirty
+        ? (() => {
+            const status = spawnSync("git", ["status", "--porcelain=v1", "--untracked-files=all", "--ignored=no", "-z"], { cwd: resolved, encoding: "utf8" });
+            return status.status === 0 ? String(status.stdout ?? "") : "?? (git-status-failed)\0";
+        })()
+        : undefined;
+    const targetBlueprintSlug = inferBlueprintSlugFromOwnerPath(resolved);
     const plan = decideMergeCleanup({
         repoRoot,
         targetPath: resolved,
@@ -699,8 +721,10 @@ async function handleMergeCleanup(nameOrPath, opts) {
         registryEntries: scopedRegistryEntries,
         currentBranch: currentBranch(repoRoot),
         repoDirty: isDirty(repoRoot),
-        targetDirty: isDirty(resolved),
+        targetDirty,
         stashPrimary: opts.stashPrimary === true,
+        ...(targetPorcelainZ !== undefined ? { targetPorcelainZ } : {}),
+        ...(targetBlueprintSlug !== undefined ? { targetBlueprintSlug } : {}),
     });
     if (opts.dryRun) {
         console.log("[dry-run] Would run merge cleanup:");

package/dist/esm/review/execution/review-checkout.d.ts

@@ -4,4 +4,10 @@ export interface ReviewTargetCheckout {
     readonly changes: () => readonly string[];
     readonly cleanup: () => void;
 }
+declare function statusEntryPath(line: string): string;
 export declare function createReviewTargetCheckout(repositoryRoot: string, targetSha: string): ReviewTargetCheckout;
+/** Test-only surface for porcelain path parsing. */
+export declare const reviewCheckoutInternals: {
+    statusEntryPath: typeof statusEntryPath;
+};
+export {};

package/dist/esm/review/execution/review-checkout.js

@@ -121,11 +121,33 @@ function isNormalizedPackageJsonModification(cwd, line) {
 // Single source of truth for turning a `git status --porcelain=v1` line into
 // its relative path, shared by status()'s filter predicate and
 // worktreeFingerprint()'s dirty-path hashing so both stay aligned by
-// construction. Does not special-case the rename arrow (`old -> new`); a
-// rename line's raw tail is used as-is, matching this function's prior
-// (pre-refactor) inline behavior.
+// construction.
+//
+// Rename/copy lines use non-null porcelain form `XY ORIG -> DEST` (or quoted
+// paths). The destination is the live path whose bytes must be fingerprinted;
+// using the raw `ORIG -> DEST` tail makes lstat miss both sides and silently
+// drops content from the hash (regression vs paired-record `-z` parsing).
 function statusEntryPath(line) {
-    return line.slice(3).replace(/\/$/u, "");
+    const tail = line.slice(3).replace(/\/$/u, "");
+    const renameSep = " -> ";
+    const sep = tail.lastIndexOf(renameSep);
+    const pathPart = sep === -1 ? tail : tail.slice(sep + renameSep.length);
+    return unquotePorcelainPath(pathPart);
+}
+/** Strip git porcelain double-quotes and reverse C-style escapes for a path. */
+function unquotePorcelainPath(pathPart) {
+    if (!pathPart.startsWith('"') || !pathPart.endsWith('"') || pathPart.length < 2) {
+        return pathPart;
+    }
+    return pathPart.slice(1, -1).replace(/\\([\\"ntr])/gu, (_m, ch) => {
+        if (ch === "n")
+            return "\n";
+        if (ch === "t")
+            return "\t";
+        if (ch === "r")
+            return "\r";
+        return ch;
+    });
 }
 function status(cwd, ignoredPaths = new Set()) {
     const output = git(cwd, ["status", "--porcelain=v1", "--untracked-files=all", "--ignored"]);
@@ -245,3 +267,7 @@ function projectCallerDependencies(repositoryRoot, checkoutRoot) {
     projected.add(dependencyPath);
     return projected;
 }
+/** Test-only surface for porcelain path parsing. */
+export const reviewCheckoutInternals = {
+    statusEntryPath,
+};

package/dist/esm/worktrees/owner-dirt.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Owner-worktree dirt classification for scaffold abandon + merge-cleanup hints.
+ *
+ * Machine-parse `git status --porcelain=v1 -z` only (NUL records; renames are
+ * destination then origin with no `->`). Do not use line-oriented porcelain for
+ * path classification — special characters and renames mis-parse.
+ *
+ * Parity with `isDirty`: ignored files are not considered (no `--ignored`).
+ */
+export type OwnerDirtKind = "clean" | "scaffold-only" | "other";
+export interface OwnerDirtClassification {
+    readonly kind: OwnerDirtKind;
+    /** Repo-relative paths contributing to dirt (bounded callers may slice). */
+    readonly paths: readonly string[];
+    /** Paths under the draft scaffold prefix, when slug is provided. */
+    readonly scaffoldPaths: readonly string[];
+}
+export interface PorcelainPathRecord {
+    readonly statusCode: string;
+    readonly paths: readonly string[];
+}
+/** Blueprint draft tree for a slug (no leading/trailing slash on slug). */
+export declare function draftScaffoldPrefix(slug: string): string;
+export declare function isUnderDraftScaffold(relativePath: string, slug: string): boolean;
+/**
+ * Parse `git status --porcelain=v1 -z` stdout into path records.
+ * Rename/copy: first path is destination, second (next record) is origin.
+ */
+export declare function parsePorcelainV1Z(output: string): readonly PorcelainPathRecord[];
+/**
+ * Classify dirt relative to an optional draft slug.
+ * Without slug, any non-empty porcelain is `other` (or `clean` if empty).
+ */
+export declare function classifyOwnerDirt(porcelainZ: string, slug?: string): OwnerDirtClassification;
+export declare function formatBoundedPaths(paths: readonly string[], limit?: number): string;
+export declare function formatTargetDirtyRefusal(input: {
+    readonly targetPath: string;
+    readonly porcelainZ: string;
+    readonly slug?: string;
+}): string;

package/dist/esm/worktrees/owner-dirt.js

@@ -0,0 +1,104 @@
+/**
+ * Owner-worktree dirt classification for scaffold abandon + merge-cleanup hints.
+ *
+ * Machine-parse `git status --porcelain=v1 -z` only (NUL records; renames are
+ * destination then origin with no `->`). Do not use line-oriented porcelain for
+ * path classification — special characters and renames mis-parse.
+ *
+ * Parity with `isDirty`: ignored files are not considered (no `--ignored`).
+ */
+/** Blueprint draft tree for a slug (no leading/trailing slash on slug). */
+export function draftScaffoldPrefix(slug) {
+    return `blueprints/draft/${slug}`;
+}
+export function isUnderDraftScaffold(relativePath, slug) {
+    const prefix = draftScaffoldPrefix(slug);
+    return relativePath === prefix || relativePath.startsWith(`${prefix}/`);
+}
+/**
+ * Parse `git status --porcelain=v1 -z` stdout into path records.
+ * Rename/copy: first path is destination, second (next record) is origin.
+ */
+export function parsePorcelainV1Z(output) {
+    const records = output.split("\0").filter((record) => record.length > 0);
+    const parsed = [];
+    for (let index = 0; index < records.length; index += 1) {
+        const record = records[index];
+        if (record.length < 3)
+            continue;
+        const statusCode = record.slice(0, 2);
+        const firstPath = record.slice(3);
+        const paths = [firstPath];
+        if (/[RC]/u.test(statusCode)) {
+            const originalPath = records[index + 1];
+            if (originalPath !== undefined) {
+                paths.push(originalPath);
+                index += 1;
+            }
+        }
+        parsed.push({ statusCode, paths });
+    }
+    return parsed;
+}
+/**
+ * Classify dirt relative to an optional draft slug.
+ * Without slug, any non-empty porcelain is `other` (or `clean` if empty).
+ */
+export function classifyOwnerDirt(porcelainZ, slug) {
+    const records = parsePorcelainV1Z(porcelainZ);
+    if (records.length === 0) {
+        return { kind: "clean", paths: [], scaffoldPaths: [] };
+    }
+    const paths = new Set();
+    const scaffoldPaths = new Set();
+    let allScaffold = slug !== undefined && slug.length > 0;
+    for (const record of records) {
+        for (const relativePath of record.paths) {
+            if (relativePath.length === 0)
+                continue;
+            paths.add(relativePath);
+            if (slug && isUnderDraftScaffold(relativePath, slug)) {
+                scaffoldPaths.add(relativePath);
+            }
+            else {
+                allScaffold = false;
+            }
+        }
+    }
+    const pathList = [...paths].toSorted();
+    const scaffoldList = [...scaffoldPaths].toSorted();
+    if (pathList.length === 0) {
+        return { kind: "clean", paths: [], scaffoldPaths: [] };
+    }
+    if (allScaffold && scaffoldList.length > 0) {
+        return { kind: "scaffold-only", paths: pathList, scaffoldPaths: scaffoldList };
+    }
+    return { kind: "other", paths: pathList, scaffoldPaths: scaffoldList };
+}
+export function formatBoundedPaths(paths, limit = 10) {
+    if (paths.length === 0)
+        return "(none)";
+    const head = paths.slice(0, limit);
+    const more = paths.length - head.length;
+    return more > 0 ? `${head.join("\n")}\n(and ${more} more)` : head.join("\n");
+}
+export function formatTargetDirtyRefusal(input) {
+    const classification = classifyOwnerDirt(input.porcelainZ, input.slug);
+    const pathBlock = formatBoundedPaths(classification.paths);
+    const header = `wp worktree merge-cleanup refused: ${input.targetPath} has uncommitted changes`;
+    if (classification.kind === "scaffold-only" && input.slug) {
+        return [
+            header,
+            "Owner has only uncommitted draft scaffold dirt:",
+            pathBlock,
+            `fix: wp blueprint abandon ${input.slug} --confirm`,
+            "  or: commit the draft and land it with the PR",
+        ].join("\n");
+    }
+    return [
+        header,
+        "Paths:",
+        pathBlock,
+        `fix: commit or stash work in ${input.targetPath}, then re-run merge-cleanup`,
+    ].join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpresso/agent-kit",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "private": false,
   "description": "TypeScript-first agent harness for guarded develop/deploy workflows: wp CLI gates, MCP tools, hooks, memory, worktrees, secrets, audits, and evidence checks.",
   "keywords": [
@@ -507,16 +507,16 @@
     "setupWpActionRef": "c2c71a7a4be446fc6858e6b57bf55a11ccfa2d88"
   },
   "optionalDependencies": {
-    "@webpresso/agent-kit-runtime-darwin-arm64": "3.3.0",
-    "@webpresso/agent-kit-runtime-darwin-x64": "3.3.0",
-    "@webpresso/agent-kit-runtime-linux-x64": "3.3.0",
-    "@webpresso/agent-kit-runtime-linux-arm64": "3.3.0",
-    "@webpresso/agent-kit-runtime-windows-x64": "3.3.0",
-    "@webpresso/agent-kit-session-memory-darwin-x64": "3.3.0",
-    "@webpresso/agent-kit-session-memory-darwin-arm64": "3.3.0",
-    "@webpresso/agent-kit-session-memory-linux-x64": "3.3.0",
-    "@webpresso/agent-kit-session-memory-linux-arm64": "3.3.0",
-    "@webpresso/agent-kit-session-memory-win32-x64": "3.3.0",
-    "@webpresso/agent-kit-session-memory-win32-arm64": "3.3.0"
+    "@webpresso/agent-kit-runtime-darwin-arm64": "3.3.1",
+    "@webpresso/agent-kit-runtime-darwin-x64": "3.3.1",
+    "@webpresso/agent-kit-runtime-linux-x64": "3.3.1",
+    "@webpresso/agent-kit-runtime-linux-arm64": "3.3.1",
+    "@webpresso/agent-kit-runtime-windows-x64": "3.3.1",
+    "@webpresso/agent-kit-session-memory-darwin-x64": "3.3.1",
+    "@webpresso/agent-kit-session-memory-darwin-arm64": "3.3.1",
+    "@webpresso/agent-kit-session-memory-linux-x64": "3.3.1",
+    "@webpresso/agent-kit-session-memory-linux-arm64": "3.3.1",
+    "@webpresso/agent-kit-session-memory-win32-x64": "3.3.1",
+    "@webpresso/agent-kit-session-memory-win32-arm64": "3.3.1"
   }
 }