@webpresso/agent-kit 3.3.3 → 3.3.5

package/dist/esm/cli/commands/gain/index.js

@@ -1,17 +1,24 @@
 import { spawnSync } from "node:child_process";
 import { SessionMemoryStore } from "#session-memory/store.js";
 import { defaultIndexDbPath } from "#mcp/tools/session-restore.js";
+import { resolveManagedRtkExecutable } from "#tool-runtime/managed-rtk.js";
 export function runGain(options = {}) {
     const dbPath = options.indexDbPath ?? defaultIndexDbPath(options.cwd);
     const webpressoStats = readWebpressoGainStats(dbPath);
     printWebpressoGain(webpressoStats, dbPath, { sessions: options.sessions === true });
     console.log("\n── RTK Gain Totals ──────────────────────────────────────────");
-    const rtk = spawnSync("rtk", ["gain", "--format", "json"], { encoding: "utf8" });
+    const rtkBin = resolveManagedRtkExecutable();
+    if (!rtkBin) {
+        console.log("  Managed RTK not available.");
+        console.log("  Enable: wp setup --with rtk  (or set WP_RTK_BIN to a capable rtk binary)");
+        return 0;
+    }
+    const rtk = spawnSync(rtkBin, ["gain", "--format", "json"], { encoding: "utf8" });
     if (rtk.error) {
         const err = rtk.error;
         if (err instanceof Error && "code" in err && err.code === "ENOENT") {
-            console.log("  RTK not installed.");
-            console.log("  Enable: wp setup --with rtk  |  Manual: brew install rtk");
+            console.log("  Managed RTK binary missing at resolved path.");
+            console.log("  Enable: wp setup --with rtk  (or set WP_RTK_BIN)");
             return 0;
         }
         throw err;

package/dist/esm/cli/commands/init/gitignore-patcher.js

@@ -76,6 +76,12 @@ export const GENERATED_PATHS_BLOCK = {
         ".agent/.blueprints.lock",
         ".agent/.blueprints.snapshot.sql",
         ".agent/.tail-hint-history.jsonl",
+        "# `wp compile` derives .rulesync/ from the canonical agent sources and replaces",
+        "# it wholesale on every run, so it is a build artifact rather than the",
+        "# hand-authored source tree rulesync's own docs describe. The .tmp- dirs are",
+        "# its staging area, normally renamed away but left behind by an interrupt.",
+        ".rulesync/",
+        ".rulesync.tmp-*",
         "# Stryker writes these mutation-test artifacts beside consumer source trees.",
         ".stryker-tmp/",
         "reports/mutation/",

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

@@ -54,14 +54,13 @@ import { ensureClaudeCodeUserPlugin } from "./scaffolders/claude-plugin/index.js
 import { ensureCodexUserPlugin } from "./scaffolders/codex-plugin/index.js";
 import { scaffoldClaudeRules } from "./scaffolders/claude-rules/index.js";
 import { ensureCodexCli } from "./scaffolders/codex-cli/index.js";
-import { ensureClaudePlaywrightMcp, ensureCodexProjectMcpServers, ensureCodexWebpressoMcp, } from "./scaffolders/codex-mcp/index.js";
+import { ensureClaudePlaywrightMcp, ensureCodexProjectMcpServers, pruneLegacyCodexWebpressoMcp, } from "./scaffolders/codex-mcp/index.js";
 import { scaffoldExampleSkill } from "./scaffolders/example-skill/index.js";
 import { scaffoldLoreCommits } from "./scaffolders/lore-commits/index.js";
 import { ensureOpenCodeWebpressoPlugin } from "./scaffolders/opencode-plugin/index.js";
 import { ensureGrokWebpressoMcp } from "./scaffolders/grok-mcp/index.js";
 import { ensureRtk } from "./scaffolders/rtk/index.js";
 import { checkRuntimes } from "./scaffolders/runtime-check/index.js";
-import { scaffoldSubagents } from "./scaffolders/subagents/index.js";
 import { maybeRunVisionInterview } from "./scaffolders/vision/interview.js";
 import { scaffoldVision } from "./scaffolders/vision/index.js";
 import { scaffoldWorkspaceConfig } from "./scaffolders/workspace-config/index.js";
@@ -381,24 +380,7 @@ async function runUserOnlySetup(input) {
         console.log("  playwright mcp: - skipped (the preset requires a project-owned .mcp.json; run setup inside the project repo)");
     }
     if (selectedHosts.includes("codex")) {
-        const webpressoMcpResult = ensureCodexWebpressoMcp({ options: userScopeOptions });
-        switch (webpressoMcpResult.kind) {
-            case "codex-webpresso-mcp-written":
-                console.log(`  codex webpresso mcp: ✓ ${webpressoMcpResult.path} → ${webpressoMcpResult.entryPath}`);
-                break;
-            case "codex-webpresso-mcp-unchanged":
-                console.log(`  codex webpresso mcp: already configured at ${webpressoMcpResult.path}`);
-                break;
-            case "codex-webpresso-mcp-ambiguous":
-                console.warn(`  codex webpresso mcp: ⚠ ambiguous MCP config at ${webpressoMcpResult.path}; left unchanged`);
-                break;
-            case "codex-webpresso-mcp-skipped-dry-run":
-                console.log("  codex webpresso mcp: skipped (--dry-run)");
-                break;
-            case "codex-webpresso-mcp-not-installed":
-                console.log(`  codex webpresso mcp: ⚠ no install root found (checked ${webpressoMcpResult.checked.length} paths). Install @webpresso/agent-kit globally (\`bun add -g @webpresso/agent-kit\`) or via the Claude plugin to wire up codex MCP.`);
-                break;
-        }
+        reportLegacyCodexWebpressoMcpPrune(pruneLegacyCodexWebpressoMcp({ options: userScopeOptions }));
         console.log("  codex project mcp: - skipped (no project .mcp.json outside a repo)");
     }
     if (isCiEnvironment) {
@@ -696,6 +678,25 @@ function printCodexPluginResult(result) {
             break;
     }
 }
+function reportLegacyCodexWebpressoMcpPrune(result) {
+    switch (result.kind) {
+        case "codex-legacy-webpresso-mcp-removed":
+            console.log(`  codex webpresso mcp: ✓ retired legacy [mcp_servers.webpresso] in ${result.path} (the bundled Codex plugin is the single delivery channel)`);
+            break;
+        case "codex-legacy-webpresso-mcp-absent":
+            console.log("  codex webpresso mcp: ✓ delivered by the bundled Codex plugin");
+            break;
+        case "codex-legacy-webpresso-mcp-preserved":
+            console.warn(`  codex webpresso mcp: ⚠ ${result.path} declares a user-authored webpresso server (${result.command ?? "no command"}); left unchanged — remove it manually to use the bundled Codex plugin`);
+            break;
+        case "codex-legacy-webpresso-mcp-ambiguous":
+            console.warn(`  codex webpresso mcp: ⚠ ambiguous MCP config at ${result.path}; left unchanged`);
+            break;
+        case "codex-legacy-webpresso-mcp-skipped-dry-run":
+            console.log("  codex webpresso mcp: skipped (--dry-run)");
+            break;
+    }
+}
 function reconcileCodexProjectMcpServers(repoRoot, options) {
     const result = ensureCodexProjectMcpServers({ repoRoot, options });
     switch (result.kind) {
@@ -1331,7 +1332,7 @@ export async function runInit(flags, deps = {}) {
             runUnifiedSync({
                 catalogDir: join(catalogDir, "agent"),
                 consumerRoot: consumer.repoRoot,
-                kinds: ["rule", "skill"],
+                kinds: ["rule", "skill", "agent"],
                 check: false,
                 allowedSkillSlugs,
                 hosts: selectedHosts,
@@ -1482,7 +1483,8 @@ export async function runInit(flags, deps = {}) {
             }
             throw error;
         }
-        const subagentResults = scaffoldSubagents({ repoRoot: consumer.repoRoot, options });
+        // Canonical subagents (.claude/agents/) are projected by the unified sync
+        // call above (kinds includes "agent") — no standalone scaffolder here.
         // Generated host instructions (AGENTS.md) are a tier-1 (guarded/full)
         // surface; the tier-0 quality profile omits them.
         // Base-kit may have created or updated package metadata earlier in this
@@ -1625,29 +1627,14 @@ export async function runInit(flags, deps = {}) {
                 ? { kind: "apply" }
                 : { kind: "skip", reason: skipGlobal ? "--skip-global" : "user-scope writes declined" });
         }
-        // Always upsert webpresso's MCP entry into the user's codex config when
-        // an install root is discoverable. Codex's config.toml is user-global, so
-        // we resolve to whatever absolute install path exists today (Claude
-        // plugin / bun global / pnpm global / npm global) and write that.
+        // Codex receives webpresso over ONE channel: the bundled Codex plugin's
+        // `.mcp.json`. Setup retires the user-global `[mcp_servers.webpresso]`
+        // block earlier versions wrote here rather than refreshing it.
         if (selectedHosts.includes("codex")) {
-            const webpressoMcpResult = ensureCodexWebpressoMcp({ options: userScopeOptions });
-            switch (webpressoMcpResult.kind) {
-                case "codex-webpresso-mcp-written":
-                    console.log(`  codex webpresso mcp: ✓ ${webpressoMcpResult.path} → ${webpressoMcpResult.entryPath}`);
-                    recordUserScope("codex-config");
-                    break;
-                case "codex-webpresso-mcp-unchanged":
-                    console.log(`  codex webpresso mcp: already configured at ${webpressoMcpResult.path}`);
-                    break;
-                case "codex-webpresso-mcp-ambiguous":
-                    console.warn(`  codex webpresso mcp: ⚠ ambiguous MCP config at ${webpressoMcpResult.path}; left unchanged`);
-                    break;
-                case "codex-webpresso-mcp-skipped-dry-run":
-                    console.log("  codex webpresso mcp: skipped (--dry-run)");
-                    break;
-                case "codex-webpresso-mcp-not-installed":
-                    console.log(`  codex webpresso mcp: ⚠ no install root found (checked ${webpressoMcpResult.checked.length} paths). Install @webpresso/agent-kit globally (\`bun add -g @webpresso/agent-kit\`) or via the Claude plugin to wire up codex MCP.`);
-                    break;
+            const pruneResult = pruneLegacyCodexWebpressoMcp({ options: userScopeOptions });
+            reportLegacyCodexWebpressoMcpPrune(pruneResult);
+            if (pruneResult.kind === "codex-legacy-webpresso-mcp-removed") {
+                recordUserScope("codex-config");
             }
             reconcileCodexProjectMcpServers(consumer.repoRoot, userScopeOptions);
         }
@@ -1829,7 +1816,7 @@ export async function runInit(flags, deps = {}) {
             const rtkResult = ensureRtk({ repoRoot: consumer.repoRoot, options: userScopeOptions });
             switch (rtkResult.kind) {
                 case "rtk-ok":
-                    console.log(rtkResult.installed ? "  rtk: ✓ installed + configured" : "  rtk: ✓");
+                    console.log(rtkResult.installed ? "  rtk: ✓ managed binary installed" : "  rtk: ✓");
                     recordUserScope("rtk-install");
                     break;
                 case "rtk-skipped-dry-run":
@@ -1839,10 +1826,6 @@ export async function runInit(flags, deps = {}) {
                     console.error(`  rtk: ✗ ${rtkResult.hint}`);
                     rtkFailure = "not-found";
                     break;
-                case "rtk-init-failed":
-                    console.error(`  rtk: ✗ rtk init exited with ${rtkResult.exitCode}`);
-                    rtkFailure = "init-failed";
-                    break;
             }
         }
         const all = [
@@ -1870,7 +1853,6 @@ export async function runInit(flags, deps = {}) {
                 ]
                 : []),
             ...claudeRulesResults,
-            ...subagentResults,
             ...presetResults,
         ];
         const summary = summarizeResults(all);
@@ -2039,8 +2021,6 @@ export async function runInit(flags, deps = {}) {
         console.log("\nwp init: setup phases finished.");
         if (rtkFailure === "not-found")
             return EXIT_SETUP_FAIL;
-        if (rtkFailure === "init-failed")
-            return EXIT_WRITE_FAIL;
         if (isTelemetryEnabled(process.env)) {
             const payload = {
                 event: "setup-complete",

package/dist/esm/cli/commands/init/mcp-spec.d.ts

@@ -30,7 +30,24 @@ export interface WebpressoInstallProbe {
     stableEntry?: () => string | null;
     /** Test seam — verify that a PATH entry is the Webpresso command. */
     stableEntryIsWebpresso?: (entryPath: string) => boolean;
+    /**
+     * Test seam — resolve the currently executing agent-kit package root.
+     *
+     * Without this seam the self-trust branch below is only reachable when the
+     * test file itself happens to live in a managed worktree, so the regression
+     * guard would silently skip in CI — where the checkout is a plain clone.
+     */
+    sourceRoot?: () => string | null;
 }
+/**
+ * True when `entryPath` is the stable vite-plus multi-package `wp` shim that
+ * dispatches to `@webpresso/agent-kit` via `~/.vite-plus/bins/wp.json`.
+ *
+ * Unlike {@link isWebpressoWpEntry}, this does **not** require realpath to land
+ * inside a package `bin/wp` tree — vite-plus's `wp` is a symlink to the `vp`
+ * binary, so package-root ownership is proven via the bins metadata instead.
+ */
+export declare function isVitePlusManagedWebpressoWp(entryPath: string): boolean;
 /**
  * Resolve the absolute path to webpresso's global `bin/wp` launcher on this
  * machine. Probes the locations consumers use to install webpresso, in order
@@ -43,25 +60,43 @@ export interface WebpressoInstallProbe {
  *   3. Claude plugin install — `~/.claude/plugins/cache/.../agent-kit/`
  *   4. bun global — `~/.bun/install/global/node_modules/@webpresso/agent-kit/`
  *
- * Host MCP configs (Grok/Codex/etc.) must never be pinned to a versioned
+ * Host MCP configs (Grok/OpenCode) must never be pinned to a versioned
  * installId tree: the next `wp update` / `vp update -g` deletes that path and
- * leaves every host with a dead launcher. Returns `null` when none of the
- * candidates yield a durable `wp`.
+ * leaves every host with a dead launcher. `entryPath` is `null` when none of
+ * the candidates yield a durable `wp`.
  */
-export declare function findWebpressoMcpEntry(probe?: WebpressoInstallProbe): string | null;
-/**
- * True when `entryPath` is the stable vite-plus multi-package `wp` shim that
- * dispatches to `@webpresso/agent-kit` via `~/.vite-plus/bins/wp.json`.
- *
- * Unlike {@link isWebpressoWpEntry}, this does **not** require realpath to land
- * inside a package `bin/wp` tree — vite-plus's `wp` is a symlink to the `vp`
- * binary, so package-root ownership is proven via the bins metadata instead.
- */
-export declare function isVitePlusManagedWebpressoWp(entryPath: string): boolean;
 export declare function resolveWebpressoMcpEntry(probe?: WebpressoInstallProbe): {
     entryPath: string | null;
     checked: readonly string[];
 };
+/**
+ * Seams for classifying a persisted host-config `command` path as agent-kit's
+ * own. Kept separate from {@link WebpressoInstallProbe}: that probe answers
+ * "where should we WRITE a launcher", this one answers "did WE write this".
+ */
+export interface AgentKitOwnedCommandProbe {
+    /** Test seam — override `$HOME`. */
+    readonly home?: string;
+    /** Test seam — resolve the currently executing agent-kit package root. */
+    readonly sourceRoot?: () => string | null;
+    /** Test seam — filesystem existence check for the persisted command path. */
+    readonly exists?: (path: string) => boolean;
+}
+/**
+ * Every root under which agent-kit itself installs (or checks out) a `bin/wp`.
+ * A `wp` launcher recorded inside one of these was written by agent-kit; a
+ * launcher anywhere else is an operator's deliberate choice.
+ */
+export declare function agentKitOwnedCommandRoots(probe?: AgentKitOwnedCommandProbe): readonly string[];
+/**
+ * Ownership — not shape — decides whether setup may retire a persisted MCP
+ * entry. An entry is agent-kit's own when it launches `wp mcp` from an
+ * ABSOLUTE path AND either that path is gone (one we would have deleted) or
+ * it lives inside one
+ * of {@link agentKitOwnedCommandRoots}. A *live* `wp mcp` launcher outside
+ * those roots is an operator pointing Codex at a custom build: preserve it.
+ */
+export declare function isAgentKitOwnedWpCommand(command: string, args: readonly string[], probe?: AgentKitOwnedCommandProbe): boolean;
 export declare function isWebpressoWpEntry(entryPath: string): boolean;
 /** Run a discovery probe with bounded output and SIGKILL escalation. */
 export declare function runQuiet(cmd: string, args: readonly string[], timeoutMs?: number): string | null;

package/dist/esm/cli/commands/init/mcp-spec.js

@@ -4,10 +4,15 @@
  * One source of truth for how every supported host launches the webpresso MCP
  * server. Each host channel (Claude plugin manifest, Codex plugin manifest,
  * Codex `config.toml`, OpenCode `opencode.json`, Grok `.grok/config.toml`)
- * projects this spec into its own config dialect. The two committed plugin
- * manifests reference the launcher via `${CLAUDE_PLUGIN_ROOT}`/`${PLUGIN_ROOT}`;
- * the setup-time writers resolve an absolute `bin/wp` path via
- * {@link findWebpressoMcpEntry}. Compare channels *semantically* (command
+ * projects this spec into its own config dialect. The Claude plugin manifest
+ * references the launcher via `${CLAUDE_PLUGIN_ROOT}`, which Claude Code
+ * expands. Codex does **not** expand `${PLUGIN_ROOT}` in a bundled `.mcp.json`
+ * — that variable reaches hook commands only — and it spawns bundled MCP
+ * servers with the *project* cwd and no plugin env, so the Codex manifest can
+ * anchor on neither the plugin root nor a relative path and uses the bare
+ * `wp` name resolved from PATH at spawn time. The remaining setup-time writers
+ * (Grok, OpenCode) resolve an absolute `bin/wp` path via
+ * {@link resolveWebpressoMcpEntry}. Compare channels *semantically* (command
  * basename, args, env) — never byte-for-byte.
  */
 import { accessSync, constants, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
@@ -17,6 +22,8 @@ import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { isVersionedAgentKitPayloadPath } from "#cli/auto-update/self-invocation.js";
 import { pathCandidates } from "#runtime/command-exists.js";
+import { isManagedWorktreePath, isPathContained } from "#worktrees/identity.js";
+import { resolveKnownManagedWorktreeRoots } from "#worktrees/location.js";
 export const WEBPRESSO_MCP_SERVER_NAME = "webpresso";
 /**
  * The single canonical launch spec for the webpresso MCP server. `name` is the
@@ -63,26 +70,6 @@ const WP_LAUNCHER_REQUIRED_RELATIVES = [
     join("bin", "runtime-lanes.js"),
     join("bin", "runtime-manifest.json"),
 ];
-/**
- * Resolve the absolute path to webpresso's global `bin/wp` launcher on this
- * machine. Probes the locations consumers use to install webpresso, in order
- * of stability:
- *
- *   1. the stable global `wp` shim available on PATH (including the
- *      vite-plus multi-package shim at `~/.vite-plus/bin/wp`)
- *   2. the currently executing `@webpresso/agent-kit` package **only when it
- *      is not a vite-plus `agent-kit#<installId>` payload path**
- *   3. Claude plugin install — `~/.claude/plugins/cache/.../agent-kit/`
- *   4. bun global — `~/.bun/install/global/node_modules/@webpresso/agent-kit/`
- *
- * Host MCP configs (Grok/Codex/etc.) must never be pinned to a versioned
- * installId tree: the next `wp update` / `vp update -g` deletes that path and
- * leaves every host with a dead launcher. Returns `null` when none of the
- * candidates yield a durable `wp`.
- */
-export function findWebpressoMcpEntry(probe = {}) {
-    return resolveWebpressoMcpEntry(probe).entryPath;
-}
 function isUsableWebpressoMcpRoot(root) {
     return WP_LAUNCHER_REQUIRED_RELATIVES.every((relativePath) => existsSync(join(root, relativePath)));
 }
@@ -117,6 +104,23 @@ export function isVitePlusManagedWebpressoWp(entryPath) {
 function isDurableMcpEntryPath(entryPath) {
     return !isVersionedAgentKitPayloadPath(entryPath);
 }
+/**
+ * Resolve the absolute path to webpresso's global `bin/wp` launcher on this
+ * machine. Probes the locations consumers use to install webpresso, in order
+ * of stability:
+ *
+ *   1. the stable global `wp` shim available on PATH (including the
+ *      vite-plus multi-package shim at `~/.vite-plus/bin/wp`)
+ *   2. the currently executing `@webpresso/agent-kit` package **only when it
+ *      is not a vite-plus `agent-kit#<installId>` payload path**
+ *   3. Claude plugin install — `~/.claude/plugins/cache/.../agent-kit/`
+ *   4. bun global — `~/.bun/install/global/node_modules/@webpresso/agent-kit/`
+ *
+ * Host MCP configs (Grok/OpenCode) must never be pinned to a versioned
+ * installId tree: the next `wp update` / `vp update -g` deletes that path and
+ * leaves every host with a dead launcher. `entryPath` is `null` when none of
+ * the candidates yield a durable `wp`.
+ */
 export function resolveWebpressoMcpEntry(probe = {}) {
     const checked = [];
     if (probe.candidates === undefined) {
@@ -151,8 +155,9 @@ export function resolveWebpressoMcpEntry(probe = {}) {
             // Never materialize host MCP configs against a vite-plus installId tree.
             if (!isDurableMcpEntryPath(wpBin))
                 continue;
-            if (isTrustedWebpressoPackageRoot(root))
+            if (isTrustedWebpressoPackageRoot(root, probe.sourceRoot)) {
                 return { entryPath: wpBin, checked };
+            }
         }
     }
     return { entryPath: null, checked };
@@ -200,27 +205,78 @@ function isPathInsideOrEqual(parent, candidate) {
     const rel = relative(resolve(parentRoot), resolve(candidateRoot));
     return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
-function isTrustedWebpressoPackageRoot(packageRoot) {
+function isTrustedWebpressoPackageRoot(packageRoot, resolveSourceRoot = currentAgentKitPackageRoot) {
     try {
         if (!isUsableWebpressoPackageRoot(packageRoot))
             return false;
         const realPackageRoot = realpathSync(packageRoot);
-        const sourceRoot = currentAgentKitPackageRoot();
-        if (sourceRoot !== null && realPackageRoot === realpathSync(sourceRoot))
+        const sourceRoot = resolveSourceRoot();
+        // A managed blueprint worktree is deleted by `wp worktree merge-cleanup`
+        // once its PR lands, so self-trusting it here would persist a path into
+        // host MCP configs that later resolves to nothing. Only the durable
+        // primary checkout may earn self-trust.
+        const home = process.env.HOME || homedir();
+        const isManagedWorktree = isManagedWorktreePath(realPackageRoot, resolveKnownManagedWorktreeRoots(home));
+        if (sourceRoot !== null && !isManagedWorktree && realPackageRoot === realpathSync(sourceRoot)) {
             return true;
+        }
         return trustedHomeInstallPackageRoots().some((anchor) => existsSync(anchor) && isPathInsideOrEqual(anchor, realPackageRoot));
     }
     catch {
         return false;
     }
 }
-function trustedHomeInstallPackageRoots() {
-    const home = process.env.HOME || homedir();
+function trustedHomeInstallPackageRoots(home = process.env.HOME || homedir()) {
     return [
         join(home, ".claude", "plugins", "cache", "webpresso", "agent-kit"),
         join(home, ".bun", "install", "global", "node_modules", "@webpresso", "agent-kit"),
     ];
 }
+/**
+ * Every root under which agent-kit itself installs (or checks out) a `bin/wp`.
+ * A `wp` launcher recorded inside one of these was written by agent-kit; a
+ * launcher anywhere else is an operator's deliberate choice.
+ */
+export function agentKitOwnedCommandRoots(probe = {}) {
+    const home = probe.home ?? process.env.HOME ?? homedir();
+    const sourceRoot = (probe.sourceRoot ?? currentAgentKitPackageRoot)();
+    return [
+        ...trustedHomeInstallPackageRoots(home),
+        join(home, ".vite-plus"),
+        ...resolveKnownManagedWorktreeRoots(home),
+        ...(sourceRoot === null ? [] : [sourceRoot]),
+    ];
+}
+const WP_LAUNCHER_BASENAMES = new Set(["wp", "wp.exe"]);
+/**
+ * Ownership — not shape — decides whether setup may retire a persisted MCP
+ * entry. An entry is agent-kit's own when it launches `wp mcp` from an
+ * ABSOLUTE path AND either that path is gone (one we would have deleted) or
+ * it lives inside one
+ * of {@link agentKitOwnedCommandRoots}. A *live* `wp mcp` launcher outside
+ * those roots is an operator pointing Codex at a custom build: preserve it.
+ */
+export function isAgentKitOwnedWpCommand(command, args, probe = {}) {
+    if (!WP_LAUNCHER_BASENAMES.has(basename(command).toLowerCase()))
+        return false;
+    if (args.length !== WEBPRESSO_MCP_SPEC.args.length)
+        return false;
+    if (args.some((value, index) => value !== WEBPRESSO_MCP_SPEC.args[index]))
+        return false;
+    // Every agent-kit writer of this block persisted an ABSOLUTE launcher path
+    // (see resolveWebpressoMcpEntry). A bare PATH name — the spelling the Codex
+    // plugin manifest itself ships — or a cwd-relative path is therefore
+    // operator-authored, and its meaning depends on a PATH/cwd this predicate
+    // cannot reconstruct. Preserve it and let the doctor report it.
+    if (!isAbsolute(command))
+        return false;
+    const exists = probe.exists ?? existsSync;
+    // Only an absolute path can have been written by us and then rotted away
+    // (deleted managed worktree, replaced versioned install tree).
+    if (!exists(command))
+        return true;
+    return agentKitOwnedCommandRoots(probe).some((root) => isPathContained(root, command));
+}
 function packageWpFromAdjacentNpmCmdShim(entryPath) {
     if (!entryPath.toLowerCase().endsWith(".cmd"))
         return null;

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

@@ -9,10 +9,21 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync, readdirSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { convergeUnitFromTarget } from "./convergence.js";
-import { resolveUntrackedCollision } from "./untracked-collision.js";
-function guardUntrackedOverwrite(targetPath, incoming, opts) {
+import { isGitIgnored, resolveUntrackedCollision } from "./untracked-collision.js";
+/**
+ * Guard an overwrite against clobbering unknown untracked content. Returns a
+ * warning to surface to the caller when the write proceeded past divergent
+ * content it could safely recover from (git-ignored lane only); throws when
+ * the write must be blocked.
+ *
+ * `patchDerived` must be true only when `incoming` was computed FROM the
+ * target's existing content (e.g. `patchJsonFile`'s key-preserving patch) —
+ * that is what makes it safe to write through divergent unmarked content
+ * without a backup.
+ */
+function guardUntrackedOverwrite(targetPath, incoming, opts, patchDerived) {
     if (!opts.repoRoot)
-        return;
+        return undefined;
     const repoRoot = resolve(opts.repoRoot);
     const target = resolve(targetPath);
     const repoRelative = relative(repoRoot, target);
@@ -20,19 +31,25 @@ function guardUntrackedOverwrite(targetPath, incoming, opts) {
         repoRelative === ".." ||
         repoRelative.startsWith(`..${sep}`) ||
         isAbsolute(repoRelative)) {
-        return;
+        return undefined;
     }
+    const gitPath = repoRelative.split(sep).join("/");
+    const scope = isGitIgnored(repoRoot, gitPath) ? "repo-ignored" : "repo-committed";
     const result = resolveUntrackedCollision({
         unit: convergeUnitFromTarget(repoRoot, target, {
             action: "modify",
-            scope: "repo-committed",
+            scope,
             reason: "setup merge target",
         }),
         desiredContent: incoming,
         force: opts.overwrite,
+        patchDerived,
     });
     if (!result.ok)
         throw new Error(result.error);
+    if (result.warning)
+        console.error(`wp setup: ${result.warning}`);
+    return result.warning;
 }
 export function writeFileMerged(targetPath, incoming, opts = {}) {
     const exists = existsSync(targetPath);
@@ -51,9 +68,9 @@ export function writeFileMerged(targetPath, incoming, opts = {}) {
     if (shouldOverwrite) {
         if (opts.dryRun)
             return { targetPath, action: "skipped-dry" };
-        guardUntrackedOverwrite(targetPath, incoming, opts);
+        const warning = guardUntrackedOverwrite(targetPath, incoming, opts, false);
         writeFileSync(targetPath, incoming);
-        return { targetPath, action: "overwritten" };
+        return { targetPath, action: "overwritten", ...(warning ? { note: warning } : {}) };
     }
     if (opts.dryRun)
         return { targetPath, action: "skipped-dry" };
@@ -119,11 +136,14 @@ export function patchJsonFile(targetPath, patcher, opts = {}) {
     if (opts.dryRun) {
         return { targetPath, action: "skipped-dry" };
     }
-    if (exists)
-        guardUntrackedOverwrite(targetPath, incoming, opts);
+    const warning = exists ? guardUntrackedOverwrite(targetPath, incoming, opts, true) : undefined;
     mkdirSync(dirname(targetPath), { recursive: true });
     writeFileSync(targetPath, incoming);
-    return { targetPath, action: exists ? "overwritten" : "created" };
+    return {
+        targetPath,
+        action: exists ? "overwritten" : "created",
+        ...(warning ? { note: warning } : {}),
+    };
 }
 export function summarizeResults(results) {
     const summary = {