@webpresso/agent-kit 3.3.3 → 3.3.4

package/dist/esm/cli/commands/init/scaffolders/rtk/index.d.ts

@@ -1,24 +1,36 @@
-import { spawnSync } from "node:child_process";
 import type { MergeOptions } from "#cli/commands/init/merge";
 import { type SpinnerFactory } from "#cli/commands/init/scaffolders/spinner";
+import { type ManagedRtkDownloader } from "#tool-runtime/managed-rtk.js";
 export interface EnsureRtkInput {
     repoRoot: string;
     options: MergeOptions;
-    spawn?: typeof spawnSync;
+    /** @deprecated ignored — managed rtk no longer shells out to brew/PATH install */
+    spawn?: unknown;
     pinFilePath?: string;
     strict?: boolean;
     spinnerFactory?: SpinnerFactory;
+    /** Test seam: inject archive downloader for ensureManagedRtk */
+    downloader?: ManagedRtkDownloader;
 }
 export type EnsureRtkResult = {
     kind: "rtk-ok";
     installed: boolean;
+    path: string;
 } | {
     kind: "rtk-skipped-dry-run";
 } | {
     kind: "rtk-not-found";
     hint: string;
-} | {
-    kind: "rtk-init-failed";
-    exitCode: number;
 };
+/**
+ * Strip freestanding RTK PreToolUse surface from project Claude settings and
+ * delete the retired script. Also removes the historical stale legacy-runtime
+ * PreToolUse group when a direct wp-pretool-guard hook is already present.
+ * Idempotent; no-op when settings are absent or already clean.
+ */
+export declare function stripFreestandingRtkHooks(repoRoot: string): void;
+/**
+ * Ensure managed (embedded-cache) rtk is available and freestanding hooks are gone.
+ * No brew, no rtk init --auto-patch, no PATH install requirement.
+ */
 export declare function ensureRtk(input: EnsureRtkInput): EnsureRtkResult;

package/dist/esm/cli/commands/init/scaffolders/rtk/index.js

@@ -1,32 +1,28 @@
-import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { makeNoopSpinnerFactory, } from "#cli/commands/init/scaffolders/spinner";
-import { checkVersionPin } from "#cli/commands/init/scaffolders/version-pin";
-const NOT_FOUND_HINT = "rtk is not on PATH. Install it manually (macOS: `brew install rtk`) and re-run.";
-// `rtk --version` answers in ~10ms; 3s is generous headroom. Bounding the
-// presence probe keeps a hung/wrong binary from stalling `wp setup`. The
-// `brew install` / `rtk init` calls below are intentionally left unbounded —
-// they are user-driven installs with inherited stdio where a fixed deadline
-// would wrongly kill a legitimately slow run.
-const RTK_PROBE_TIMEOUT_MS = 3000;
+import { ensureManagedRtk } from "#tool-runtime/managed-rtk.js";
+const NOT_FOUND_HINT = "managed rtk binary could not be installed (network/platform). Set WP_SKIP_RTK=1 to skip, or WP_RTK_BIN=/path/to/rtk.";
 const RTK_HOOK_RELATIVE_PATH = join(".claude", "hooks", "rtk-rewrite.sh");
 const CLAUDE_SETTINGS_RELATIVE_PATH = join(".claude", "settings.json");
 const STALE_runtime_CLAUDE_COMMAND = "external-runtime/dist/scripts/codex-native-hook.js";
-function hasInstalledRtkHook(repoRoot) {
+const FREESTANDING_RTK_HOOK_MARKERS = ["rtk-rewrite.sh", "rtk hook claude"];
+/**
+ * Strip freestanding RTK PreToolUse surface from project Claude settings and
+ * delete the retired script. Also removes the historical stale legacy-runtime
+ * PreToolUse group when a direct wp-pretool-guard hook is already present.
+ * Idempotent; no-op when settings are absent or already clean.
+ */
+export function stripFreestandingRtkHooks(repoRoot) {
     const hookPath = join(repoRoot, RTK_HOOK_RELATIVE_PATH);
-    const settingsPath = join(repoRoot, CLAUDE_SETTINGS_RELATIVE_PATH);
-    if (!existsSync(hookPath) || !existsSync(settingsPath))
-        return false;
-    try {
-        const settings = readFileSync(settingsPath, "utf8");
-        return settings.includes("rtk-rewrite.sh");
-    }
-    catch {
-        return false;
+    if (existsSync(hookPath)) {
+        try {
+            rmSync(hookPath, { force: true });
+        }
+        catch {
+            // best-effort; doctor will still flag if the file remains
+        }
     }
-}
-function normalizeClaudeRtkSettings(repoRoot) {
     const settingsPath = join(repoRoot, CLAUDE_SETTINGS_RELATIVE_PATH);
     if (!existsSync(settingsPath))
         return;
@@ -41,73 +37,58 @@ function normalizeClaudeRtkSettings(repoRoot) {
     if (!Array.isArray(groups) || groups.length === 0)
         return;
     const hasDirectWpGuard = groups.some((group) => (group.hooks ?? []).some((hook) => hook.command?.includes("wp-pretool-guard")));
-    if (!hasDirectWpGuard)
-        return;
     let changed = false;
-    const nextGroups = groups.filter((group) => {
+    const nextGroups = groups
+        .map((group) => {
+        const hooks = group.hooks ?? [];
+        const nextHooks = hooks.filter((hook) => {
+            const command = hook.command ?? "";
+            if (FREESTANDING_RTK_HOOK_MARKERS.some((marker) => command.includes(marker))) {
+                changed = true;
+                return false;
+            }
+            return true;
+        });
+        if (nextHooks.length !== hooks.length) {
+            return { ...group, hooks: nextHooks };
+        }
+        return group;
+    })
+        .filter((group) => {
         const commands = (group.hooks ?? []).map((hook) => hook.command ?? "");
-        const isStaleOmcGroup = commands.some((command) => command.includes(STALE_runtime_CLAUDE_COMMAND));
-        if (isStaleOmcGroup)
+        if (commands.length === 0) {
+            changed = true;
+            return false;
+        }
+        const isStaleOmcGroup = hasDirectWpGuard &&
+            commands.some((command) => command.includes(STALE_runtime_CLAUDE_COMMAND));
+        if (isStaleOmcGroup) {
             changed = true;
-        return !isStaleOmcGroup;
+            return false;
+        }
+        return true;
     });
     if (!changed)
         return;
     parsed.hooks = { ...parsed.hooks, PreToolUse: nextGroups };
     writeFileSync(settingsPath, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
 }
+/**
+ * Ensure managed (embedded-cache) rtk is available and freestanding hooks are gone.
+ * No brew, no rtk init --auto-patch, no PATH install requirement.
+ */
 export function ensureRtk(input) {
     if (input.options.dryRun)
         return { kind: "rtk-skipped-dry-run" };
-    const spawn = input.spawn ?? spawnSync;
     const spinner = (input.spinnerFactory ?? makeNoopSpinnerFactory())("rtk");
-    let installed = false;
     spinner.start();
-    let probe = spawn("rtk", ["--version"], { encoding: "utf8", timeout: RTK_PROBE_TIMEOUT_MS });
-    if (probe.error || (probe.status !== null && probe.status !== 0)) {
-        if (process.platform !== "darwin") {
-            spinner.fail("rtk not found");
-            return { kind: "rtk-not-found", hint: NOT_FOUND_HINT };
-        }
-        const install = spawn("brew", ["install", "rtk"], { stdio: "inherit" });
-        if (install.status !== 0) {
-            spinner.fail("rtk install failed");
-            return { kind: "rtk-not-found", hint: NOT_FOUND_HINT };
-        }
-        installed = true;
-        probe = spawn("rtk", ["--version"], { encoding: "utf8", timeout: RTK_PROBE_TIMEOUT_MS });
-        if (probe.error || (probe.status !== null && probe.status !== 0)) {
-            spinner.fail("rtk not found after install");
-            return { kind: "rtk-not-found", hint: NOT_FOUND_HINT };
-        }
-    }
-    const installedVersion = String(probe.stdout ?? "").trim();
-    const pinCheck = checkVersionPin("rtk", installedVersion, input.pinFilePath ?? join(input.repoRoot, "compatible-versions.json"));
-    if (!pinCheck.ok) {
-        if (input.strict) {
-            spinner.fail("rtk version mismatch");
-            return { kind: "rtk-init-failed", exitCode: -1 };
-        }
-        console.warn(pinCheck.warning);
-    }
-    if (hasInstalledRtkHook(input.repoRoot)) {
-        normalizeClaudeRtkSettings(input.repoRoot);
-        spinner.succeed("rtk ready");
-        return { kind: "rtk-ok", installed };
-    }
-    const result = spawn("rtk", ["init", "-g", "--auto-patch"], {
-        cwd: input.repoRoot,
-        stdio: "inherit",
-        env: {
-            ...process.env,
-            RTK_TELEMETRY_DISABLED: "1",
-        },
-    });
-    if (result.status !== 0) {
-        spinner.fail("rtk init failed");
-        return { kind: "rtk-init-failed", exitCode: result.status ?? -1 };
+    // Always strip freestanding surface first so setup never leaves CLAUDE_PROJECT_DIR hooks.
+    stripFreestandingRtkHooks(input.repoRoot);
+    const ensured = ensureManagedRtk({ downloader: input.downloader });
+    if (!ensured.ok) {
+        spinner.fail("rtk not available");
+        return { kind: "rtk-not-found", hint: `${NOT_FOUND_HINT} (${ensured.error})` };
     }
-    normalizeClaudeRtkSettings(input.repoRoot);
     spinner.succeed("rtk ready");
-    return { kind: "rtk-ok", installed };
+    return { kind: "rtk-ok", installed: ensured.installed, path: ensured.path };
 }

package/dist/esm/cli/commands/init/scaffolders/runtime-check/index.js

@@ -1,11 +1,12 @@
 /**
- * Runtime detection for tools that webpresso consumers commonly need
- * but that `wp setup` cannot install for them (curl-pipe install scripts
- * or system package managers shouldn't be triggered silently).
+ * Runtime detection for host-install tools that webpresso does **not**
+ * managed-download (see catalog rule `managed-tool-binaries`).
  *
- * Auto-runs at the end of `wp setup`; prints a one-line status per
- * runtime so the consumer knows what's missing without surprising them
- * with a download.
+ * Contrasts with managed rtk (`ensureManagedRtk`): bun/vp/actionlint stay
+ * host package-manager installs. This probe only prints status + hints —
+ * it never curl-pipes or brew-installs silently.
+ *
+ * Auto-runs at the end of `wp setup`; one line per runtime.
  */
 import { spawnSync } from "node:child_process";
 function probeVersion(cmd, args = ["--version"]) {

package/dist/esm/cli/commands/init/untracked-collision.d.ts

@@ -1,14 +1,25 @@
 import type { ConvergeUnit } from "./convergence.js";
-export type CollisionResolution = "none" | "tracked" | "removed-identical" | "removed-owned";
+export type CollisionResolution = "none" | "tracked" | "removed-identical" | "removed-owned" | "ignored-patch-derived" | "ignored-backed-up";
 export interface CollisionResult {
     readonly ok: boolean;
     readonly resolution?: CollisionResolution;
     readonly error?: string;
+    /** Set when the collision proceeded but the caller should surface a notice. */
+    readonly warning?: string;
 }
 export interface ResolveCollisionOptions {
     readonly unit: ConvergeUnit;
     readonly desiredContent: string | Uint8Array;
     /** Compatibility input only. Unknown content remains protected when true. */
     readonly force?: boolean;
+    /**
+     * True when `desiredContent` was computed FROM the existing file's own
+     * content (e.g. a JSON key-preserving patch), so a divergent unmarked
+     * existing file is safe to write through: the caller already folded the
+     * user's data into `desiredContent`.
+     */
+    readonly patchDerived?: boolean;
 }
+/** True when `gitPath` is git-ignored in `repoRoot` (machine-local, never committed). */
+export declare function isGitIgnored(repoRoot: string, gitPath: string): boolean;
 export declare function resolveUntrackedCollision(options: ResolveCollisionOptions): CollisionResult;

package/dist/esm/cli/commands/init/untracked-collision.js

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, lstatSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 const GIT_TIMEOUT_MS = 15_000;
 const OWNERSHIP_MARKER = /^\uFEFF?[ \t]*(?:#|\/\/|\/\*|<!--|")?[ \t]*(?:>>> managed by webpresso\b|Generated by webpresso\b)/iu;
 function git(repoRoot, args) {
@@ -12,6 +12,25 @@ function git(repoRoot, args) {
     });
     return { ok: result.status === 0 && !result.error };
 }
+/** True when `gitPath` is git-ignored in `repoRoot` (machine-local, never committed). */
+export function isGitIgnored(repoRoot, gitPath) {
+    return git(repoRoot, ["check-ignore", "--no-index", "-q", "--", gitPath]).ok;
+}
+function resolveIgnoredDivergence(options) {
+    const { unit } = options;
+    if (options.patchDerived) {
+        return { ok: true, resolution: "ignored-patch-derived" };
+    }
+    const current = readFileSync(unit.targetPath);
+    const backupPath = `${unit.targetPath}.bak`;
+    writeFileSync(backupPath, current);
+    return {
+        ok: true,
+        resolution: "ignored-backed-up",
+        warning: `Untracked, git-ignored ${unit.gitPath} had unmanaged content; ` +
+            `the original was backed up to ${unit.gitPath}.bak before it was overwritten.`,
+    };
+}
 export function resolveUntrackedCollision(options) {
     const { unit } = options;
     if (!existsSync(unit.targetPath))
@@ -34,6 +53,9 @@ export function resolveUntrackedCollision(options) {
         rmSync(unit.targetPath);
         return { ok: true, resolution: "removed-owned" };
     }
+    if (unit.scope === "repo-ignored") {
+        return resolveIgnoredDivergence(options);
+    }
     return {
         ok: false,
         error: `Unknown untracked content blocks ${unit.gitPath}; it was preserved${options.force ? " despite --force" : ""}. ` +

package/dist/esm/cli/commands/pr-help.js

@@ -53,7 +53,7 @@ export function getPrWaitCommandHelpText() {
         "  --branch <name>          Branch selector (defaults to current branch)",
         "  --pr <number-or-url>     Explicit PR selector",
         "  --until <target>         ready | checks-terminal | checks-green | merged (default: checks-terminal)",
-        "  --timeout-ms <ms>        Overall deadline; for ready, per-probe timeout only",
+        "  --timeout-ms <ms>        Overall deadline, max 300000 (5min); for ready, per-probe timeout only",
         "  --poll-interval-ms <ms>  Poll interval (default: 15000)",
         "  --include-checks         Include final check snapshot (default: true)",
         "  --no-include-checks      Omit final check snapshot from output",

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

@@ -2,15 +2,29 @@ import { PR_WAIT_UNTIL_VALUES, runPrWait } from "#mcp/tools/pr-wait.js";
 import { buildStatusSnapshot, formatStatusSnapshot } from "#status/snapshot.js";
 // PR help text lives in ./pr-help.ts (dependency-free) so the `wp pr --help`
 // fast path can render it without importing this heavy command module.
-function parsePositiveInteger(value, name) {
+// Mirrors the hard cap `readonlyOpsBaseSchema` enforces downstream for `pr
+// wait` (src/mcp/tools/_readonly-ops.ts). `pr status` shares the same
+// `--timeout-ms` flag but reaches `buildStatusSnapshot` directly, which has
+// no schema of its own, so an over-cap value was silently accepted with no
+// error and no clamp. Validating here makes both subcommands fail the same
+// way, with a clear message, before any network probe starts, instead of
+// relying on a downstream schema that not every code path shares.
+const MAX_TIMEOUT_MS = 300_000;
+function parsePositiveInteger(value, name, max) {
     if (value === undefined)
         return undefined;
     const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
     if (!Number.isFinite(parsed) || parsed <= 0) {
         throw new Error(`${name} must be a positive integer`);
     }
+    if (max !== undefined && parsed > max) {
+        throw new Error(`${name} must not exceed ${max}`);
+    }
     return parsed;
 }
+function parseTimeoutMs(value) {
+    return parsePositiveInteger(value, "--timeout-ms", MAX_TIMEOUT_MS);
+}
 function normalizeUntil(value) {
     if (value === undefined)
         return undefined;
@@ -26,7 +40,7 @@ export function registerPrCommand(cli) {
         .option("--branch <name>", "Branch selector")
         .option("--pr <number-or-url>", "Explicit PR selector")
         .option("--until <target>", "ready | checks-terminal | checks-green | merged")
-        .option("--timeout-ms <ms>", "Overall deadline; for ready, per-probe timeout only")
+        .option("--timeout-ms <ms>", "Overall deadline (max 300000ms / 5min); for ready, per-probe timeout only")
         .option("--poll-interval-ms <ms>", "Poll interval")
         .option("--include-checks", "Include final check snapshot", { default: true })
         .option("--max-output-bytes <n>", "Per-command output budget")
@@ -41,7 +55,7 @@ export function registerPrCommand(cli) {
                 includePr: true,
                 maxOutputBytes: parsePositiveInteger(options.maxOutputBytes, "--max-output-bytes"),
                 pr: options.pr === undefined ? undefined : String(options.pr),
-                timeoutMs: parsePositiveInteger(options.timeoutMs, "--timeout-ms"),
+                timeoutMs: parseTimeoutMs(options.timeoutMs),
             });
             console.log(options.json ? JSON.stringify(snapshot, null, 2) : formatStatusSnapshot(snapshot));
             return options.requireReady && snapshot.status !== "ready" ? 1 : 0;
@@ -57,7 +71,7 @@ export function registerPrCommand(cli) {
             maxOutputBytes: parsePositiveInteger(options.maxOutputBytes, "--max-output-bytes"),
             pollIntervalMs: parsePositiveInteger(options.pollIntervalMs, "--poll-interval-ms"),
             pr: options.pr === undefined ? undefined : String(options.pr),
-            timeoutMs: parsePositiveInteger(options.timeoutMs, "--timeout-ms"),
+            timeoutMs: parseTimeoutMs(options.timeoutMs),
             until,
         });
         console.log(JSON.stringify(payload, null, 2));

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

@@ -1463,6 +1463,35 @@ function gateFailureFromSummary(summary) {
         ...(summary.retryAfterMs === undefined ? {} : { retryAfterMs: summary.retryAfterMs }),
     };
 }
+// `providerErrorDetail`'s doc comment promises "sanitized, length-bounded"
+// text; a checkout-creation error's message/cause chain is target/environment
+// text (pnpm/git stderr), not attacker-shaped, but is still capped here so
+// the invariant holds regardless.
+const MAX_PROVIDER_ERROR_DETAIL_LENGTH = 2000;
+// Walks an `Error.cause` chain into a single human-readable line. Used to
+// surface the real reason a review checkout could not be created instead of
+// discarding it behind a fixed string (see the bare `catch` this replaces in
+// `invokeProvider`). Bounded depth + a `seen` set guard against a pathological
+// or cyclic cause chain.
+function formatErrorWithCauseChain(error, maxDepth = 5) {
+    const parts = [];
+    const seen = new Set();
+    let current = error;
+    for (let depth = 0; depth < maxDepth; depth += 1) {
+        if (current === undefined || current === null || seen.has(current))
+            break;
+        seen.add(current);
+        if (current instanceof Error) {
+            parts.push(current.message);
+            current = current.cause;
+        }
+        else {
+            parts.push(String(current));
+            break;
+        }
+    }
+    return parts.join(" -> caused by: ");
+}
 export async function invokeProvider(input, executeReview = runReviewExecution, runCatalogCommand = runCommand, createTargetCheckout = createReviewTargetCheckout, 
 // A thunk (not a checkout instance) so callers that never reach a real
 // provider attempt — injected fakes included — never pay the checkout's
@@ -1475,19 +1504,34 @@ getSharedCheckout) {
         checkout = existingCheckout ?? createTargetCheckout(input.projectRoot, input.targetSha);
         checkout.beginAttempt();
     }
-    catch {
+    catch (error) {
+        // Bind + chain via Error.cause (ES2022) rather than discarding the real
+        // failure — this exact swallow previously hid a genuine supply-chain
+        // signal (`ERR_PNPM_TRUST_DOWNGRADE`) behind a fixed string for a full
+        // day. See catalog/agent/rules/ts-coding-conventions.md.
+        const isolationFailure = new Error("Unable to create the disposable review checkout; review was not started", { cause: error });
+        let cleanupError;
         if (ownsCheckout) {
             try {
                 checkout?.cleanup();
             }
-            catch {
-                // The attempt already fails closed as an isolation failure.
+            catch (cleanupFailure) {
+                // Cleanup failing must not mask the primary isolation failure above;
+                // capture it as secondary diagnostic context instead of discarding it.
+                cleanupError = cleanupFailure;
             }
         }
         const requestedModel = input.model ?? defaultReviewModel(input.provider) ?? "unresolved";
         const model = resolveReviewModel(input.provider, requestedModel);
+        // Chain from the original `error`, not `isolationFailure` — the latter's
+        // own message is already the fixed prefix below, so chaining from it
+        // would print that fixed sentence twice.
+        const providerErrorDetail = (formatErrorWithCauseChain(error) +
+            (cleanupError === undefined
+                ? ""
+                : ` | cleanup after isolation failure also failed: ${formatErrorWithCauseChain(cleanupError)}`)).slice(0, MAX_PROVIDER_ERROR_DETAIL_LENGTH);
         return {
-            output: "Unable to create the disposable review checkout; review was not started.",
+            output: `${isolationFailure.message}: ${providerErrorDetail}`,
             model,
             reviewer: input.provider === "opencode" && model !== "unresolved"
                 ? reviewerFamily(model)
@@ -1497,6 +1541,7 @@ getSharedCheckout) {
             verdict: "no-verdict",
             terminalClassification: "review-isolation-failure",
             failureCode: "review-isolation-failure",
+            providerErrorDetail,
         };
     }
     try {
@@ -2127,21 +2172,30 @@ export async function runReviewGate(projectRoot, slug, input, dependencies = { i
         // never need one (plan-purpose reuse of an existing approval, terminal
         // rejections, exhausted scope). A setup failure is remembered so provider
         // attempts still surface the same isolation-failure evidence.
+        // Captures the real failure the first time checkoutFactory is
+        // attempted this run, so the re-throw below (reached whenever a later
+        // caller reuses the memoized failure) can chain to it via Error.cause
+        // instead of discarding it — see ts-coding-conventions.md "never
+        // swallow an error".
+        let checkoutSetupError;
         const ensureSharedCheckout = () => {
             if (sharedCheckout !== undefined || checkoutSetupFailed)
                 return sharedCheckout;
             try {
                 sharedCheckout = checkoutFactory(projectRoot, targetSha);
             }
-            catch {
+            catch (error) {
                 checkoutSetupFailed = true;
+                checkoutSetupError = error;
             }
             return sharedCheckout;
         };
         const createCheckoutForAttempt = () => {
             // Only reachable when ensureSharedCheckout() already failed — a live
             // shared checkout is always passed to the attempt as existingCheckout.
-            throw new Error("review checkout setup failed");
+            throw new Error("review checkout setup failed", {
+                cause: checkoutSetupError,
+            });
         };
         let sharedCheckoutCleaned = false;
         const cleanupSharedCheckout = () => {

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

@@ -8,6 +8,18 @@ export interface WorktreeCommandOptions {
     prefix?: string;
     dryRun?: boolean;
     force?: boolean;
+    /**
+     * Bypass the "primary must be on the expected branch" merge-cleanup
+     * refusal by switching a CLEAN primary checkout to that branch. Never
+     * bypasses the "primary is dirty" refusal — a dirty primary always
+     * refuses, regardless of this flag (see `decideMergeCleanup`).
+     */
+    switchPrimary?: boolean;
+    /**
+     * @deprecated Renamed to `switchPrimary`. Kept as an accepted alias only
+     * (mapped from the CLI's legacy `--stash-primary` flag) — it no longer
+     * stashes anything; a dirty primary always refuses regardless of this flag.
+     */
     stashPrimary?: boolean;
     noSetup?: boolean;
     /** Dependency hydration for `new` only: install-locked (default) or reconcile. */
@@ -41,7 +53,6 @@ export interface MergeCleanupPlan {
     readonly removeArgs: readonly string[];
     readonly fetchArgs: readonly string[];
     readonly mergeArgs: readonly string[];
-    readonly stashArgs?: readonly string[];
     readonly switchArgs?: readonly string[];
     readonly preservedPrimaryBranch?: string;
 }
@@ -54,7 +65,18 @@ export interface MergeCleanupDecisionInput {
     readonly currentBranch: string;
     readonly repoDirty: boolean;
     readonly targetDirty: boolean;
-    readonly stashPrimary?: boolean;
+    /**
+     * Bypasses the wrong-branch refusal for a CLEAN primary only. A dirty
+     * primary always refuses — see `decideMergeCleanup` — this never bypasses
+     * that refusal, and merge-cleanup never stashes primary state.
+     */
+    readonly switchPrimary?: boolean;
+    /**
+     * When the primary is dirty, optional porcelain -z lists the offending
+     * paths in the refusal message. Omitted messages stay generic (e.g. for
+     * unit tests that don't care about message content).
+     */
+    readonly repoPorcelainZ?: string;
     /**
      * When target is dirty, optional porcelain -z + slug enrich the refusal message
      * (scaffold-only vs other dirt). Omitted messages stay generic for unit tests.