@webpresso/agent-kit 3.3.2 → 3.3.4

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.

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

@@ -15,9 +15,10 @@ 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 { formatBoundedPaths, formatTargetDirtyRefusal, parsePorcelainV1Z, } 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 { isStaleWorktreeRegistration, pruneStaleGitWorktreeMetadata, } from "#worktrees/git-metadata.js";
 import { buildRegistryRepoRootMap, classifyOrphanCandidate, discoverOrphanScanCandidates, resolveRepoRootFromGitPointer, } from "#worktrees/orphan-scan.js";
 function parseDepsOption(value) {
     if (value === undefined || value === null || value === "")
@@ -165,9 +166,24 @@ export function planMergeCleanup(targetPath, baseRef) {
         mergeArgs: ["merge", "--ff-only", baseRef],
     };
 }
-function primaryStashMessage(input) {
-    const current = input.currentBranch || "(detached)";
-    return `wp worktree merge-cleanup preserve primary state from ${current} before syncing ${input.expectedPrimaryBranch} and removing ${basename(input.targetPath)}`;
+/**
+ * Refusal for a DIRTY primary checkout. Reuses the same low-level porcelain
+ * parser and bounded-list formatter `formatTargetDirtyRefusal` uses for the
+ * target worktree (`#worktrees/owner-dirt.js`) — this is NOT a classifier:
+ * it never decides whose dirt it is or whether it's "safe" to move. A dirty
+ * primary always refuses; this only lists the paths so the human knows what
+ * blocked the command.
+ */
+function formatPrimaryDirtyRefusal(repoRoot, porcelainZ) {
+    const paths = [
+        ...new Set(parsePorcelainV1Z(porcelainZ).flatMap((record) => record.paths.filter((path) => path.length > 0))),
+    ].toSorted();
+    return [
+        `wp worktree merge-cleanup refused: primary checkout ${repoRoot} has uncommitted changes`,
+        "Paths:",
+        formatBoundedPaths(paths),
+        "fix: commit or `git stash` the listed paths yourself (or `wp blueprint abandon <slug> --confirm` if this is leftover blueprint draft scaffold), then re-run merge-cleanup",
+    ].join("\n");
 }
 export function decideMergeCleanup(input) {
     const entry = input.entries.find((candidate) => candidate.path === input.targetPath);
@@ -193,34 +209,18 @@ export function decideMergeCleanup(input) {
         throw new Error(`wp worktree merge-cleanup refused: ${input.targetPath} has uncommitted changes`);
     }
     if (input.repoDirty) {
-        if (input.stashPrimary === true) {
-            return {
-                ...plan,
-                stashArgs: [
-                    "stash",
-                    "push",
-                    "--include-untracked",
-                    "--message",
-                    primaryStashMessage({
-                        currentBranch: input.currentBranch,
-                        expectedPrimaryBranch: plan.expectedPrimaryBranch,
-                        targetPath: input.targetPath,
-                    }),
-                ],
-                ...(input.currentBranch !== plan.expectedPrimaryBranch
-                    ? {
-                        switchArgs: ["switch", plan.expectedPrimaryBranch],
-                        preservedPrimaryBranch: input.currentBranch || "(detached)",
-                    }
-                    : {
-                        preservedPrimaryBranch: input.currentBranch || "(detached)",
-                    }),
-            };
-        }
-        throw new Error(`wp worktree merge-cleanup refused: primary checkout ${input.repoRoot} has uncommitted changes`);
+        // A dirty primary ALWAYS refuses -- unconditionally, regardless of
+        // --switch-primary/--stash-primary. merge-cleanup never stashes primary
+        // state; it never decides whose dirt it is or whether moving it is safe.
+        throw new Error(input.repoPorcelainZ !== undefined
+            ? formatPrimaryDirtyRefusal(input.repoRoot, input.repoPorcelainZ)
+            : `wp worktree merge-cleanup refused: primary checkout ${input.repoRoot} has uncommitted changes`);
     }
     if (input.currentBranch !== plan.expectedPrimaryBranch) {
-        if (input.stashPrimary === true) {
+        // --switch-primary bypasses ONLY this refusal, and only for a CLEAN
+        // primary: switching a clean checkout to the expected branch is
+        // harmless (nothing to lose), unlike stashing dirty state.
+        if (input.switchPrimary === true) {
             return {
                 ...plan,
                 switchArgs: ["switch", plan.expectedPrimaryBranch],
@@ -456,10 +456,14 @@ function handleRefresh(opts) {
 async function handlePrune(opts) {
     if (!opts.all)
         throw new Error("Usage: wp worktree prune --all");
+    const repoRoot = resolveWorktreeRepoRoot(opts.repo ?? opts.cwd ?? process.cwd());
+    // Reconcile git's own admin records FIRST: a hand-deleted worktree directory
+    // leaves a record that still claims its branch, and it would otherwise report
+    // as live below and pin the matching registry entry in place too.
+    const gitPruned = pruneStaleGitWorktreeMetadata(repoRoot, listEntries(repoRoot));
     // Repository-scoped, three-state prune: only THIS repo's entries that are
     // proven stale against a COMPLETE git-live inventory are dropped; unknown,
     // other-repo, and live-legacy entries are retained.
-    const repoRoot = resolveWorktreeRepoRoot(opts.repo ?? opts.cwd ?? process.cwd());
     const inventory = buildWorktreeInventory(repoRoot);
     const result = planStaleWorktreeRegistryPrune({
         inventory,
@@ -468,6 +472,13 @@ async function handlePrune(opts) {
     await removeCodexProjectTrusts(result.removed.map((entry) => entry.path));
     result.commit();
     console.log(`Pruned ${result.removed.length} stale managed registry entr${result.removed.length === 1 ? "y" : "ies"}.`);
+    if (gitPruned.error)
+        console.log(`warning: git worktree prune failed: ${gitPruned.error}`);
+    else {
+        console.log(`Cleared ${gitPruned.prunedPaths.length} stale git worktree registration${gitPruned.prunedPaths.length === 1 ? "" : "s"}.`);
+        for (const path of gitPruned.prunedPaths)
+            console.log(`  ${path}`);
+    }
     for (const warning of result.warnings)
         console.log(`warning: ${warning}`);
 }
@@ -546,6 +557,23 @@ async function handleRemove(nameOrPath, opts) {
     const repoRoot = resolvePrimaryRoot(callerRoot, entries);
     const resolved = resolveWorktreePath(nameOrPath, entries);
     const entry = entries.find((candidate) => candidate.path === resolved);
+    // The directory is already gone (hand-deleted, or a failed earlier removal):
+    // `git worktree remove` cannot act on it and teardown scripts have no cwd, so
+    // reconcile git's leftover admin record instead of failing.
+    if (isStaleWorktreeRegistration(entry, resolved, existsSync)) {
+        // Staleness is not a bypass for the managed-root boundary, which is the
+        // same protection the MCP surface applies to registry-gone stale targets.
+        if (!isManagedWorktreePath(canonicalizeWorktreePath(resolved), resolveKnownManagedWorktreeRoots())) {
+            throw new Error(`Refusing to reconcile ${resolved}: its directory is gone but it is not under a known managed worktree root.`);
+        }
+        const gitPruned = pruneStaleGitWorktreeMetadata(repoRoot, entries);
+        if (gitPruned.error)
+            throw new Error(`git worktree prune failed: ${gitPruned.error}`);
+        await removeCodexProjectTrust(resolved);
+        removeWorktreeRegistryEntries(repoScopedPathPredicate(resolved, { authoritativeRepoKey: resolveRepoIdentity(repoRoot) }));
+        console.log(`Cleared stale worktree registration for ${resolved} (directory already gone).`);
+        return;
+    }
     if (!opts.force) {
         runWorktreeTeardown(readConfig(resolved) ?? readConfig(repoRoot), {
             worktreePath: resolved,
@@ -713,6 +741,22 @@ async function handleMergeCleanup(nameOrPath, opts) {
         })()
         : undefined;
     const targetBlueprintSlug = inferBlueprintSlugFromOwnerPath(resolved);
+    // `--switch-primary`/legacy `--stash-primary` only ever bypasses the
+    // clean-primary wrong-branch refusal; a dirty primary always refuses (see
+    // `decideMergeCleanup`), so merge-cleanup never stashes primary state.
+    const switchPrimary = opts.switchPrimary === true || opts.stashPrimary === true;
+    const repoDirty = isDirty(repoRoot);
+    const repoPorcelainZ = repoDirty
+        ? (() => {
+            const status = spawnSync("git", ["status", "--porcelain=v1", "--untracked-files=all", "--ignored=no", "-z"], { cwd: repoRoot, encoding: "utf8" });
+            // Unlike the target-worktree probe, do NOT substitute a sentinel path
+            // on failure: a fake "(git-status-failed)" path in the refusal message
+            // would misrepresent what's actually dirty. Leaving this undefined
+            // falls back to the generic (path-free) refusal in decideMergeCleanup
+            // -- the refusal itself is unaffected either way.
+            return status.status === 0 ? String(status.stdout ?? "") : undefined;
+        })()
+        : undefined;
     const plan = decideMergeCleanup({
         repoRoot,
         targetPath: resolved,
@@ -720,16 +764,15 @@ async function handleMergeCleanup(nameOrPath, opts) {
         entries,
         registryEntries: scopedRegistryEntries,
         currentBranch: currentBranch(repoRoot),
-        repoDirty: isDirty(repoRoot),
+        repoDirty,
         targetDirty,
-        stashPrimary: opts.stashPrimary === true,
+        switchPrimary,
         ...(targetPorcelainZ !== undefined ? { targetPorcelainZ } : {}),
         ...(targetBlueprintSlug !== undefined ? { targetBlueprintSlug } : {}),
+        ...(repoPorcelainZ !== undefined ? { repoPorcelainZ } : {}),
     });
     if (opts.dryRun) {
         console.log("[dry-run] Would run merge cleanup:");
-        if (plan.stashArgs)
-            console.log(`  stash:  git ${plan.stashArgs.join(" ")}`);
         if (plan.switchArgs)
             console.log(`  switch: git ${plan.switchArgs.join(" ")}`);
         console.log(`  remove: git ${plan.removeArgs.join(" ")}`);
@@ -737,12 +780,6 @@ async function handleMergeCleanup(nameOrPath, opts) {
         console.log(`  sync:   git ${plan.mergeArgs.join(" ")}`);
         return;
     }
-    if (plan.stashArgs) {
-        const stashResult = spawnSync("git", [...plan.stashArgs], { cwd: repoRoot, stdio: "inherit" });
-        if (stashResult.status !== 0) {
-            throw new Error("git stash push failed");
-        }
-    }
     if (plan.switchArgs) {
         const switchResult = spawnSync("git", [...plan.switchArgs], {
             cwd: repoRoot,
@@ -775,13 +812,8 @@ async function handleMergeCleanup(nameOrPath, opts) {
         throw new Error(`git merge --ff-only ${baseRef} failed`);
     }
     console.log(`Removed worktree ${resolved} and fast-forwarded ${repoRoot} to ${baseRef}.`);
-    if (plan.stashArgs) {
-        const stashRef = spawnSync("git", ["stash", "list", "--format=%gd %gs", "-n", "1"], {
-            cwd: repoRoot,
-            encoding: "utf8",
-        });
-        const summary = String(stashRef.stdout ?? "").trim();
-        console.log(`Preserved prior primary checkout state${plan.preservedPrimaryBranch ? ` from ${plan.preservedPrimaryBranch}` : ""} in ${summary || "git stash list"}.`);
+    if (plan.switchArgs && plan.preservedPrimaryBranch) {
+        console.log(`Switched primary checkout from ${plan.preservedPrimaryBranch} to ${plan.expectedPrimaryBranch}.`);
     }
 }
 export async function executeWorktreeSubcommand(subcommand, args, opts) {

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

@@ -27,7 +27,9 @@ const HELP_TEXT = [
     "  --dry-run           Print the resolved worktree target without writing",
     "  --no-setup          Skip configured worktree.setup scripts (new only)",
     "  --force             Skip configured teardown scripts and force removal",
-    "  --stash-primary     Stash dirty primary state and switch to the expected primary branch before merge-cleanup",
+    "  --switch-primary    Switch a CLEAN primary checkout to the expected branch before merge-cleanup",
+    "                      (a DIRTY primary always refuses, with or without this flag; it is never stashed)",
+    "  --stash-primary     Deprecated alias for --switch-primary. No longer stashes anything.",
     "  --orphans           Filesystem-level orphan sweep for prune (see prune --orphans above)",
     "  --repo-id <id>      Scope prune --orphans to one repo namespace under repos/<id>",
     "  --yes               Alias for --force (prune --orphans only)",
@@ -44,7 +46,8 @@ export function registerWorktreeRouter(cli) {
         .option("--no-setup", "Skip configured worktree.setup scripts (new only)")
         .option("--deps <mode>", "Dependency hydration for new: install-locked (default, pnpm GVS path) or reconcile")
         .option("--force", "Skip configured teardown scripts and force removal (remove/merge-cleanup only)")
-        .option("--stash-primary", "Stash dirty primary state and switch to the expected primary branch before merge-cleanup")
+        .option("--switch-primary", "Switch a CLEAN primary checkout to the expected branch before merge-cleanup (a dirty primary always refuses; never stashed)")
+        .option("--stash-primary", "Deprecated alias for --switch-primary. No longer stashes anything.")
         .option("--all", "Use global managed inventory where supported")
         .option("--repo <dir>", "Repo root for refresh/rebind (default: cwd)")
         .option("--orphans", "Filesystem-level orphan sweep for prune (dry-run unless --force/--yes)")

package/dist/esm/cli/direct-provider-launch.js

@@ -11,7 +11,7 @@ import { canonicalizeWorktreePath } from "#worktrees/identity.js";
 import { dashProviderOwnershipName, parseDashPermissionMode, } from "#cli/commands/dash/provider-capabilities.js";
 import { optionalToolCanonicalCommand } from "#cli/optional-tools.js";
 import { commandExists } from "#runtime/command-exists.js";
-import { ensureCodexProjectMcpServers, ensureCodexWebpressoMcp, } from "#cli/commands/init/scaffolders/codex-mcp/index.js";
+import { ensureCodexProjectMcpServers, findInstalledCodexPluginMcpManifests, pruneLegacyCodexWebpressoMcp, } from "#cli/commands/init/scaffolders/codex-mcp/index.js";
 export class DirectProviderLaunchPreparationError extends Error {
     action;
     constructor(message, action) {
@@ -91,11 +91,19 @@ function validateDirectProviderLaunch(provider, cwd) {
         vpCommand,
     };
 }
+/**
+ * `wp codex` is the only path that reaches machines which never re-run setup,
+ * so it carries the legacy-channel retirement too. The surviving channel is
+ * the bundled Codex plugin: probe its cache directly and WARN when it is
+ * absent. A `codex plugin marketplace` subprocess here would add latency to
+ * every launch and could hard-fail a machine where the plugin already works —
+ * a degraded session beats a blocked launch.
+ */
 function ensureCodexSessionTooling(repoRoot) {
     const options = { dryRun: false, overwrite: false };
-    const webpresso = ensureCodexWebpressoMcp({ options });
-    if (webpresso.kind === "codex-webpresso-mcp-not-installed") {
-        throw new DirectProviderLaunchPreparationError(`Codex webpresso MCP is not configured because no usable agent-kit install root was found. Checked: ${webpresso.checked.join(", ") || "(none)"}`, "Run `wp setup --yes-global` from this repo, then retry `wp codex`.");
+    pruneLegacyCodexWebpressoMcp({ options });
+    if (findInstalledCodexPluginMcpManifests().length === 0) {
+        console.warn("⚠ The webpresso Codex plugin is not installed, so the webpresso MCP server will be unavailable in this session. Run `wp setup` to install it.");
     }
     const project = ensureCodexProjectMcpServers({ repoRoot, options });
     if (project.kind === "codex-project-mcp-invalid") {

package/dist/esm/compiler/flatten.d.ts

@@ -5,5 +5,14 @@ export interface FlattenedAssets {
 }
 /** Reads `.agent/{skills,commands,agents}/` and returns an in-memory flattened structure. */
 export declare function flattenAgentDir(agentDir: string): FlattenedAssets;
-/** Writes flattened assets to a directory structure mirroring rulesync's expected layout. */
+/**
+ * Writes flattened assets to the layout rulesync reads.
+ *
+ * The three shapes are not interchangeable, and getting one wrong is silent:
+ * rulesync discovers skills by globbing `skills/` for *directories* and reading
+ * `SKILL.md` inside each, reads subagents from `subagents/` (not `agents/`),
+ * and reads commands as flat `commands/*.md`. An asset written in the wrong
+ * shape is simply never seen — rulesync still exits 0, having generated
+ * nothing for it.
+ */
 export declare function writeFlattenedAssets(assets: FlattenedAssets, outDir: string): Promise<void>;

package/dist/esm/compiler/flatten.js

@@ -60,19 +60,29 @@ export function flattenAgentDir(agentDir) {
     }
     return { skills, commands, agents };
 }
-/** Writes flattened assets to a directory structure mirroring rulesync's expected layout. */
+/**
+ * Writes flattened assets to the layout rulesync reads.
+ *
+ * The three shapes are not interchangeable, and getting one wrong is silent:
+ * rulesync discovers skills by globbing `skills/` for *directories* and reading
+ * `SKILL.md` inside each, reads subagents from `subagents/` (not `agents/`),
+ * and reads commands as flat `commands/*.md`. An asset written in the wrong
+ * shape is simply never seen — rulesync still exits 0, having generated
+ * nothing for it.
+ */
 export async function writeFlattenedAssets(assets, outDir) {
-    const subdirs = ["skills", "commands", "agents"];
+    const subdirs = ["skills", "commands", "subagents"];
     for (const sub of subdirs) {
         mkdirSync(join(outDir, sub), { recursive: true });
     }
     for (const [name, content] of Object.entries(assets.skills)) {
-        writeFileSync(join(outDir, "skills", `${name}.md`), content);
+        mkdirSync(join(outDir, "skills", name), { recursive: true });
+        writeFileSync(join(outDir, "skills", name, "SKILL.md"), content);
     }
     for (const [name, content] of Object.entries(assets.commands)) {
         writeFileSync(join(outDir, "commands", `${name}.md`), content);
     }
     for (const [name, content] of Object.entries(assets.agents)) {
-        writeFileSync(join(outDir, "agents", `${name}.md`), content);
+        writeFileSync(join(outDir, "subagents", `${name}.md`), content);
     }
 }

package/dist/esm/compose/admin-blocks-registry-integrity.d.ts

@@ -0,0 +1,22 @@
+import { type BlockRegistry } from "./registry-resolve.js";
+export interface SnapshotIntegrityResult {
+    readonly ok: boolean;
+    readonly path: string;
+    readonly registry?: BlockRegistry;
+    readonly diagnostics: readonly string[];
+}
+/**
+ * Fail-on-drift **equivalent** for agent-kit CI without a framework dependency:
+ * load the committed catalog snapshot and enforce generator-contract invariants
+ * (schema parse, version shape, unique name+view, well-formed slots).
+ *
+ * Full regenerate-and-diff against `@webpresso/codegen` remains a cross-repo
+ * operator step; this gate prevents a rotten or hand-broken snapshot from landing.
+ */
+/**
+ * Check (does not throw). Callers must inspect `.ok` — this is a gate helper,
+ * not a Node assertion that aborts the process.
+ */
+export declare function checkAdminBlocksSnapshotIntegrity(options?: {
+    readonly snapshotPath?: string;
+}): SnapshotIntegrityResult;

package/dist/esm/compose/admin-blocks-registry-integrity.js

@@ -0,0 +1,90 @@
+import { readFileSync } from "node:fs";
+import { blockRegistrySchema, defaultSnapshotPath, } from "./registry-resolve.js";
+const SEMVER_LIKE = /^\d+\.\d+\.\d+/;
+const slotSchemaLoose = {
+    isSlot(value) {
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            return false;
+        const rec = value;
+        return typeof rec["name"] === "string" && rec["name"].length > 0;
+    },
+};
+/**
+ * Fail-on-drift **equivalent** for agent-kit CI without a framework dependency:
+ * load the committed catalog snapshot and enforce generator-contract invariants
+ * (schema parse, version shape, unique name+view, well-formed slots).
+ *
+ * Full regenerate-and-diff against `@webpresso/codegen` remains a cross-repo
+ * operator step; this gate prevents a rotten or hand-broken snapshot from landing.
+ */
+/**
+ * Check (does not throw). Callers must inspect `.ok` — this is a gate helper,
+ * not a Node assertion that aborts the process.
+ */
+export function checkAdminBlocksSnapshotIntegrity(options = {}) {
+    const path = options.snapshotPath ?? defaultSnapshotPath();
+    const diagnostics = [];
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return { ok: false, path, diagnostics: [`cannot read snapshot: ${detail}`] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return { ok: false, path, diagnostics: [`snapshot is not valid JSON: ${detail}`] };
+    }
+    const result = blockRegistrySchema.safeParse(parsed);
+    if (!result.success) {
+        return {
+            ok: false,
+            path,
+            diagnostics: result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`),
+        };
+    }
+    const registry = result.data;
+    if (!SEMVER_LIKE.test(registry.version)) {
+        diagnostics.push(`version "${registry.version}" is not semver-like`);
+    }
+    if (registry.minVersion !== undefined && !SEMVER_LIKE.test(registry.minVersion)) {
+        diagnostics.push(`minVersion "${registry.minVersion}" is not semver-like`);
+    }
+    const seen = new Set();
+    for (const [index, block] of registry.blocks.entries()) {
+        const key = `${block.view}::${block.name}`;
+        if (seen.has(key)) {
+            diagnostics.push(`duplicate block ${key} at index ${index}`);
+        }
+        seen.add(key);
+        if (block.slots !== undefined) {
+            if (!Array.isArray(block.slots)) {
+                diagnostics.push(`blocks[${index}].slots must be an array`);
+                continue;
+            }
+            for (const [slotIndex, slot] of block.slots.entries()) {
+                if (!slotSchemaLoose.isSlot(slot)) {
+                    diagnostics.push(`blocks[${index}].slots[${slotIndex}] requires string name`);
+                    continue;
+                }
+                const accepts = slot.accepts;
+                if (accepts !== undefined) {
+                    if (!Array.isArray(accepts) || accepts.some((a) => typeof a !== "string")) {
+                        diagnostics.push(`blocks[${index}].slots[${slotIndex}].accepts must be string[] when present`);
+                    }
+                }
+            }
+        }
+    }
+    return {
+        ok: diagnostics.length === 0,
+        path,
+        registry,
+        diagnostics,
+    };
+}