@webpresso/agent-kit 3.3.2 → 3.3.4

package/dist/esm/cli/commands/init/scaffolders/codex-mcp/index.js

@@ -6,26 +6,23 @@
  * the patch tiny and deterministic: per-server upserts, no TOML parser
  * dependency, no edits to unrelated user config.
  *
- * Managed blocks come from two sources:
- *   1. `[mcp_servers.webpresso]` — points at webpresso's own MCP server.
- *      Path-stability requires discovery: webpresso lives in different
- *      locations depending on how the user installed it (Claude plugin
- *      install, bun global, pnpm/npm global). Discovery happens at scaffold
- *      time; the resolved absolute path is written into the codex config.
- *      When the unified-cli sibling cutover lands (`webpresso mcp serve`
- *      from a path-stable bin), this block collapses to a fixed `command`.
- *   2. Consumer-owned `.mcp.json` package declarations — compiled to setup-
- *      provisioned, exact-version binaries with environment-variable names
- *      forwarded through Codex's stdio `env_vars` allow-list.
+ * Webpresso's own MCP server is NOT one of them. Codex receives `webpresso`
+ * over exactly one delivery channel — the bundled Codex plugin's `.mcp.json`.
+ * Setup therefore *retires* the `[mcp_servers.webpresso]` block earlier
+ * versions wrote here (see {@link pruneLegacyCodexWebpressoMcp}) instead of
+ * refreshing it. What remains managed here is consumer-owned `.mcp.json`
+ * package declarations — compiled to setup-provisioned, exact-version binaries
+ * with environment-variable names forwarded through Codex's stdio `env_vars`
+ * allow-list.
  */
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { agentKitMcpLaunchCommand, findWebpressoMcpEntry, resolveExecutableOnPath, resolveWebpressoMcpEntry, WEBPRESSO_MCP_SERVER_NAME, WEBPRESSO_MCP_SPEC, } from "#cli/commands/init/mcp-spec.js";
-// Re-exported so existing importers (tests) keep a stable path; the canonical
-// implementation now lives in `mcp-spec.ts`.
-export { findWebpressoMcpEntry, WEBPRESSO_MCP_SERVER_NAME };
+import { isAgentKitOwnedWpCommand, resolveExecutableOnPath, WEBPRESSO_MCP_SERVER_NAME, } from "#cli/commands/init/mcp-spec.js";
+// Re-exported so existing importers keep a stable path; the canonical
+// implementation lives in `mcp-spec.ts`.
+export { WEBPRESSO_MCP_SERVER_NAME };
 import { updateScaffolderTextFile } from "#cli/commands/init/scaffolders/file-transaction.js";
 import { isJsonRecord, isUnsafeRuntimeLauncher, parseJson, parseProjectMcpServers, parseTomlString, } from "#hooks/host-config-contract.js";
 import { appendGlobalCapableVpArgs, resolveGlobalCapableVpCommand, } from "#cli/global-vp.js";
@@ -309,8 +306,10 @@ function hasDottedServerDefinition(lines, startsInsideMultiline, serverId) {
 export function hasAmbiguousMcpServerDottedDefinition(raw, serverId) {
     const lines = raw.trimEnd().split(/\r?\n/);
     const startsInsideMultiline = tomlLinesStartingInsideMultilineString(lines);
-    const start = lines.findIndex((line, index) => !startsInsideMultiline[index] && isServerTableHeader(line, serverId));
-    return start === -1 && hasDottedServerDefinition(lines, startsInsideMultiline, serverId);
+    // Scanned unconditionally, not only when no table header exists: a dotted key
+    // alongside the table would outlive the table's removal and re-declare the
+    // server with no launcher, which breaks the whole config load.
+    return hasDottedServerDefinition(lines, startsInsideMultiline, serverId);
 }
 export function hasManagedMcpServerTableConflict(raw, serverId) {
     const lines = raw.trimEnd().split(/\r?\n/);
@@ -658,39 +657,177 @@ export function ensureClaudePlaywrightMcp(input) {
     return { kind: "claude-playwright-mcp-written", path: configPath };
 }
 // ────────────────────────────────────────────────────────────────────────────
-// Agent-kit MCP server registration
+// Legacy `[mcp_servers.webpresso]` retirement
+//
+// Earlier versions delivered webpresso to Codex over a SECOND channel: a
+// `[mcp_servers.webpresso]` block in the user-global `config.toml` pinned to
+// whatever absolute install path existed at setup time. The bundled Codex
+// plugin is now the single channel, so setup must remove what it used to write
+// — otherwise every machine keeps a duplicate registration pinned to a path
+// agent-kit itself deletes on the next update or worktree cleanup.
+//
+// The removal predicate is OWNERSHIP-based, never shape-based: a live `wp mcp`
+// launcher outside every agent-kit-owned root is an operator pointing Codex at
+// a custom build and is preserved (and reported by `wp doctor`).
 // ────────────────────────────────────────────────────────────────────────────
-export function agentKitMcpBlock(entryPath) {
-    const launch = agentKitMcpLaunchCommand(entryPath);
-    return commandMcpCodexBlock({
-        id: WEBPRESSO_MCP_SERVER_NAME,
+const TOML_COMMAND_ASSIGNMENT = /^\s*command\s*=\s*(.+?)\s*$/u;
+const TOML_ARGS_ASSIGNMENT = /^\s*args\s*=\s*(.+?)\s*$/u;
+function firstTomlAssignmentValue(body, pattern) {
+    for (const line of body) {
+        const match = pattern.exec(line);
+        if (match?.[1] !== undefined)
+            return match[1];
+    }
+    return null;
+}
+function parseTomlStringArray(value) {
+    const trimmed = value.trim();
+    if (!trimmed.startsWith("[") || !trimmed.endsWith("]"))
+        return null;
+    const inner = trimmed.slice(1, -1).trim();
+    if (inner.length === 0)
+        return [];
+    const parsed = inner
+        .split(",")
+        .map((element) => element.trim())
+        .filter((element) => element.length > 0)
+        .map(parseTomlString);
+    return parsed.every((element) => element !== null) ? parsed : null;
+}
+/**
+ * Read the parent block's `command`/`args`, stopping at the first sub-table
+ * header so a `[mcp_servers.<id>.env]` child never supplies the launch tuple.
+ */
+function readManagedBlockLaunch(lines, startsInsideMultiline, start, end) {
+    const body = [];
+    for (let index = start + 1; index < end; index += 1) {
+        // Multiline-string content is document text, not configuration: reading a
+        // decoy tuple from it — or letting a bracket line there end the scan —
+        // would delete the operator's real registration.
+        if (startsInsideMultiline[index])
+            continue;
+        if (lines[index].trim().startsWith("["))
+            break;
+        body.push(lines[index]);
+    }
+    const commandValue = firstTomlAssignmentValue(body, TOML_COMMAND_ASSIGNMENT);
+    const command = commandValue === null ? null : parseTomlString(commandValue);
+    if (command === null)
+        return null;
+    const argsValue = firstTomlAssignmentValue(body, TOML_ARGS_ASSIGNMENT);
+    const args = argsValue === null ? [] : parseTomlStringArray(argsValue);
+    return args === null ? null : { command, args };
+}
+/**
+ * The removal path is the only one that rewrites lines it did not classify, so
+ * it must reproduce the document's existing newline style rather than impose LF.
+ */
+function dominantEol(raw) {
+    const crlf = raw.split("\r\n").length - 1;
+    const lf = raw.split("\n").length - 1;
+    return crlf * 2 > lf ? "\r\n" : "\n";
+}
+function rebuildWithoutSection(lines, start, end, eol) {
+    const kept = lines.slice(0, start);
+    while (kept.at(-1)?.trim() === "")
+        kept.pop();
+    const next = kept
+        .concat(lines.slice(end))
+        .join(eol)
+        .replace(/^(?:[ \t]*(?:\r\n|\n))+/u, "")
+        .trimEnd();
+    return next.length > 0 ? `${next}${eol}` : "";
+}
+/**
+ * Remove `[mcp_servers.<serverId>]` (plus its contiguous sub-tables) when
+ * `isOwned` claims the block's launch tuple. Fails closed — leaving `raw`
+ * byte-identical — for every TOML spelling this line scanner cannot rewrite
+ * safely (dotted keys, inline parent table, array tables, non-contiguous
+ * sub-tables).
+ */
+export function pruneOwnedMcpServerBlock(raw, serverId, isOwned) {
+    if (hasAmbiguousMcpServerDottedDefinition(raw, serverId) ||
+        hasManagedMcpServerTableConflict(raw, serverId)) {
+        return { kind: "ambiguous", raw };
+    }
+    const lines = raw.trimEnd().split(/\r?\n/);
+    const startsInsideMultiline = tomlLinesStartingInsideMultilineString(lines);
+    const start = lines.findIndex((line, index) => !startsInsideMultiline[index] && isServerTableHeader(line, serverId));
+    if (start === -1)
+        return { kind: "absent", raw };
+    const end = managedSectionEnd(lines, startsInsideMultiline, start, serverId);
+    const launch = readManagedBlockLaunch(lines, startsInsideMultiline, start, end);
+    if (launch === null)
+        return { kind: "preserved", raw, command: null };
+    if (!isOwned(launch.command, launch.args)) {
+        return { kind: "preserved", raw, command: launch.command };
+    }
+    return {
+        kind: "removed",
+        raw: rebuildWithoutSection(lines, start, end, dominantEol(raw)),
         command: launch.command,
-        args: launch.args,
-        codexEnv: WEBPRESSO_MCP_SPEC.env,
-    });
+    };
 }
-export function upsertWebpressoMcpServer(raw, entryPath) {
-    return upsertMcpServerBlock(raw, WEBPRESSO_MCP_SERVER_NAME, agentKitMcpBlock(entryPath));
+function legacyPruneResult(outcome, path) {
+    switch (outcome.kind) {
+        case "removed":
+            return { kind: "codex-legacy-webpresso-mcp-removed", path, command: outcome.command };
+        case "preserved":
+            return { kind: "codex-legacy-webpresso-mcp-preserved", path, command: outcome.command };
+        case "ambiguous":
+            return { kind: "codex-legacy-webpresso-mcp-ambiguous", path };
+        case "absent":
+            return { kind: "codex-legacy-webpresso-mcp-absent", path };
+    }
 }
-export function ensureCodexWebpressoMcp(input) {
+/**
+ * Retire the legacy user-global `[mcp_servers.webpresso]` block. Runs from
+ * setup AND from the `wp codex` launch preflight — the launch path is the only
+ * one that reaches machines that never re-run setup.
+ */
+export function pruneLegacyCodexWebpressoMcp(input) {
     const configPath = input.configPath ?? defaultConfigPath();
     if (input.options.dryRun) {
-        return { kind: "codex-webpresso-mcp-skipped-dry-run", path: configPath };
+        return { kind: "codex-legacy-webpresso-mcp-skipped-dry-run", path: configPath };
     }
-    const resolution = input.entryPath === undefined ? resolveWebpressoMcpEntry(input.probe) : undefined;
-    const entryPath = input.entryPath ?? resolution?.entryPath;
-    if (!entryPath) {
-        const checked = resolution?.checked ?? [];
-        return { kind: "codex-webpresso-mcp-not-installed", path: configPath, checked };
+    if (!existsSync(configPath)) {
+        return { kind: "codex-legacy-webpresso-mcp-absent", path: configPath };
     }
-    const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
-    if (hasAmbiguousMcpServerDottedDefinition(existing, WEBPRESSO_MCP_SERVER_NAME) ||
-        hasManagedMcpServerTableConflict(existing, WEBPRESSO_MCP_SERVER_NAME)) {
-        return { kind: "codex-webpresso-mcp-ambiguous", path: configPath, entryPath };
+    // Classify INSIDE the locked transaction so a concurrent writer's block is
+    // never judged from a pre-lock read (PR#767 lost-update guarantee).
+    let outcome = { kind: "absent", raw: "" };
+    updateCodexConfig(configPath, (raw) => {
+        outcome = pruneOwnedMcpServerBlock(raw, WEBPRESSO_MCP_SERVER_NAME, (command, args) => isAgentKitOwnedWpCommand(command, args, input.ownership));
+        return outcome.raw;
+    });
+    return legacyPruneResult(outcome, configPath);
+}
+/**
+ * Installed Codex plugin MCP manifests — the surviving delivery channel.
+ * Cheap directory probe only: no `codex plugin` subprocess belongs on the
+ * launch hot path.
+ */
+export function findInstalledCodexPluginMcpManifests(homeDir = process.env.HOME || homedir()) {
+    const base = join(homeDir, ".codex", "plugins", "cache");
+    const manifests = [];
+    for (const marketplace of safeReadDir(base)) {
+        const pluginDir = join(base, marketplace, "agent-kit");
+        for (const version of safeReadDir(pluginDir)) {
+            const manifest = join(pluginDir, version, ".mcp.json");
+            if (existsSync(manifest))
+                manifests.push(manifest);
+        }
     }
-    const result = updateCodexConfig(configPath, (raw) => upsertWebpressoMcpServer(raw, entryPath));
-    if (result === "unchanged") {
-        return { kind: "codex-webpresso-mcp-unchanged", path: configPath, entryPath };
+    return manifests;
+}
+function safeReadDir(dir) {
+    try {
+        const entries = readdirSync(dir);
+        if (!Array.isArray(entries))
+            return [];
+        return entries.filter((entry) => typeof entry === "string");
+    }
+    catch {
+        return [];
     }
-    return { kind: "codex-webpresso-mcp-written", path: configPath, entryPath };
 }

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/package-manager.js

@@ -184,6 +184,9 @@ function runGlobalUpdateCommand(deps) {
                 else {
                     failed = true;
                     console.error(message);
+                    // Required step failed — stop so optional host refreshes cannot
+                    // look like a successful update after a broken agent-kit install.
+                    break;
                 }
             }
         }
@@ -195,6 +198,7 @@ function runGlobalUpdateCommand(deps) {
             else {
                 failed = true;
                 console.error(message);
+                break;
             }
         }
     }
@@ -313,8 +317,10 @@ function runAgentKitSelfUpdateStep(deps) {
             return spawnLike(status, new Error("another agent-kit installer is active; re-run `wp update` once it finishes"));
         case GUARD_EXIT_OWNERSHIP_LOST:
             return spawnLike(status, new Error("install lease ownership was lost mid-update; the takeover installer verifies the store — re-run `wp update` to confirm"));
-        default:
-            return spawnLike(status === 0 ? 1 : status, new Error(`self-install-guard exited ${status}`));
+        default: {
+            const code = status === 0 ? 1 : status;
+            return spawnLike(code, new Error(`agent-kit self-install failed (self-install-guard exit ${code}); re-run \`wp update\` or \`vp install -g @webpresso/agent-kit\``));
+        }
     }
 }
 function refreshCodexPlugin(deps) {

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",