@webpresso/agent-kit 3.3.3 → 3.3.5

package/dist/esm/hooks/doctor.js

@@ -27,6 +27,8 @@ import { isAgentKitSourceRepo } from "#cli/commands/init/source-repo-hook-policy
 import { findAgentKitPackageRoot, resolveAgentKitPackageRoot, } from "#cli/commands/init/package-root";
 import { readInstalledHooksMap } from "#hooks/shared/installed-hooks.js";
 import { auditCodexConfigPaths, checkCodexConfigPathIntegrity } from "#hooks/codex-config-paths.js";
+import { findInstalledCodexPluginMcpManifests, pruneOwnedMcpServerBlock, } from "#cli/commands/init/scaffolders/codex-mcp/index.js";
+import { isAgentKitOwnedWpCommand, WEBPRESSO_MCP_SERVER_NAME, } from "#cli/commands/init/mcp-spec.js";
 import { parseProjectMcpServers, scanCodexConfigDrift } from "#hooks/host-config-contract.js";
 import { defaultCodexConfigFilePath } from "#cli/commands/init/scaffolders/agent-hooks/codex-trust-sync.js";
 import { expectedRootWpBinRelativePath, formatRootLauncherContractFailure, rootContractMode, validateRootLauncherContract, } from "#launcher/root-contract.js";
@@ -55,7 +57,10 @@ function createOwnedProbeSettler(child, timeoutMs, timeoutResult, resolve) {
     return settle;
 }
 const RTK_REQUESTED_MARKER = join(".agent", ".rtk-requested");
-const RTK_INSTALL_HINT = "rtk requested via --with rtk but not on PATH; brew install rtk";
+const RTK_INSTALL_HINT = "rtk requested but managed binary missing; re-run wp setup (or set WP_RTK_BIN)";
+const RTK_FREESTANDING_HOOK_REL = join(".claude", "hooks", "rtk-rewrite.sh");
+const RTK_FREESTANDING_SETTINGS_REL = join(".claude", "settings.json");
+const RTK_FREESTANDING_REPAIR = "stale freestanding rtk-rewrite surface; run wp setup (ensureRtk strips rtk-rewrite.sh — pretool-guard owns rewrite)";
 const HOST_SMOKE_ENV = "WP_RUN_HOST_SMOKE";
 const HOOK_PROBE_TIMEOUT_ENV = "WP_DOCTOR_HOOK_TIMEOUT_MS";
 const WRAPPER_PROBE_ENV = "WP_DOCTOR_WRAPPER_PROBE";
@@ -347,6 +352,62 @@ function checkConsumerCodexHookPaths(cwd = process.cwd()) {
 function wasRtkRequested(cwd = process.cwd()) {
     return tryAccess(join(cwd, RTK_REQUESTED_MARKER));
 }
+export function checkFreestandingRtkSurface(cwd = process.cwd()) {
+    const hookPath = join(cwd, RTK_FREESTANDING_HOOK_REL);
+    const settingsPath = join(cwd, RTK_FREESTANDING_SETTINGS_REL);
+    const hookPresent = tryAccess(hookPath);
+    const markers = [];
+    if (hookPresent)
+        markers.push(RTK_FREESTANDING_HOOK_REL);
+    if (tryAccess(settingsPath)) {
+        try {
+            const settings = readFileSync(settingsPath, "utf8");
+            if (settings.includes("rtk-rewrite.sh")) {
+                markers.push(`${RTK_FREESTANDING_SETTINGS_REL} rtk-rewrite.sh`);
+            }
+            if (settings.includes("rtk hook claude")) {
+                markers.push(`${RTK_FREESTANDING_SETTINGS_REL} rtk hook claude`);
+            }
+        }
+        catch {
+            // ignore unreadable settings
+        }
+    }
+    if (markers.length === 0)
+        return null;
+    return {
+        name: "freestanding rtk PreToolUse retired",
+        ok: false,
+        detail: `${RTK_FREESTANDING_REPAIR} (found: ${markers.join(", ")})`,
+    };
+}
+/** Non-mutating warn for user-global freestanding RTK rewriters (rtk init -g). */
+export function checkGlobalFreestandingRtkSurface() {
+    const globalSettings = join(homedir(), ".claude", "settings.json");
+    const globalHook = join(homedir(), ".claude", "hooks", "rtk-rewrite.sh");
+    const markers = [];
+    if (tryAccess(globalHook))
+        markers.push("~/.claude/hooks/rtk-rewrite.sh");
+    if (tryAccess(globalSettings)) {
+        try {
+            const settings = readFileSync(globalSettings, "utf8");
+            if (settings.includes("rtk-rewrite.sh"))
+                markers.push("~/.claude/settings.json rtk-rewrite.sh");
+            if (settings.includes("rtk hook claude"))
+                markers.push("~/.claude/settings.json rtk hook claude");
+        }
+        catch {
+            // ignore
+        }
+    }
+    if (markers.length === 0)
+        return null;
+    return {
+        name: "global freestanding rtk (warn)",
+        ok: true,
+        detail: `WARNING: global freestanding RTK PreToolUse still present (${markers.join(", ")}); remove manually or re-run rtk uninstall — project setup does not mutate ~/.claude. Dual rewriters may race updatedInput with wp-pretool-guard.`,
+    };
+}
 function shouldRunHostChecks(mode) {
     if (mode === "skip")
         return false;
@@ -393,36 +454,13 @@ function resolveRequestedHosts(mode, hostNames) {
 export function checkRtkOnPath(cwd) {
     if (!wasRtkRequested(cwd))
         return Promise.resolve(null);
-    return new Promise((resolve) => {
-        const timeoutMs = hookProbeTimeoutMs();
-        const child = spawn("rtk", ["--version"], {
-            stdio: ["ignore", "pipe", "pipe"],
-            detached: process.platform !== "win32",
-        });
-        let stdout = "";
-        let stderr = "";
-        const settle = createOwnedProbeSettler(child, timeoutMs, () => ({
-            name: "rtk on PATH",
-            ok: false,
-            detail: `rtk probe timed out after ${timeoutMs}ms`,
-        }), resolve);
-        child.stdout.on("data", (chunk) => {
-            stdout += String(chunk);
-        });
-        child.stderr?.on("data", (chunk) => {
-            stderr += String(chunk);
-        });
-        child.on("error", () => {
-            settle({ name: "rtk on PATH", ok: false, detail: RTK_INSTALL_HINT });
-        });
-        child.on("close", (code) => {
-            if (code === 0) {
-                settle({ name: "rtk on PATH", ok: true, detail: stdout.trim() || "rtk present" });
-                return;
-            }
-            const suffix = stderr.trim().length > 0 ? ` (${stderr.trim()})` : "";
-            settle({ name: "rtk on PATH", ok: false, detail: `${RTK_INSTALL_HINT}${suffix}` });
-        });
+    // Managed binary (Webpresso cache / WP_RTK_BIN), not bare PATH brew install.
+    return import("#tool-runtime/managed-rtk.js").then(({ isManagedRtkAvailable, resolveManagedRtkExecutable }) => {
+        const path = resolveManagedRtkExecutable();
+        if (path && isManagedRtkAvailable()) {
+            return { name: "rtk managed", ok: true, detail: path };
+        }
+        return { name: "rtk managed", ok: false, detail: RTK_INSTALL_HINT };
     });
 }
 async function probeHookBin(wpCli, hookName, checkStdin) {
@@ -1184,19 +1222,44 @@ async function checkCodexHost() {
             detail: `missing MCP entry (webpresso=${hasAgentKit})`,
         };
     }
-    const mcpPathFindings = auditCodexConfigPaths().filter((finding) => finding.location.startsWith("mcp_servers.webpresso."));
-    if (mcpPathFindings.length > 0) {
-        const detail = mcpPathFindings
-            .map((finding) => `${finding.location}: ${finding.path} (${finding.reason === "missing" ? "path does not exist" : "volatile versioned path"})`)
-            .join("; ");
-        return {
-            name: "Codex host integration",
-            ok: false,
-            detail: `webpresso MCP listed but launch paths are broken or rot-prone — ${detail}`,
-        };
-    }
+    const legacy = classifyLegacyCodexWebpressoChannel();
+    if (legacy)
+        return { name: "Codex host integration", ok: false, detail: legacy };
     return { name: "Codex host integration", ok: true, detail: "webpresso MCP visible" };
 }
+/**
+ * Codex must receive `webpresso` over exactly one channel — the bundled Codex
+ * plugin. Report the retired user-global `[mcp_servers.webpresso]` block that
+ * `wp setup` removes, and call out a double registration distinctly. A
+ * user-authored block (a live `wp` outside every agent-kit root) is never
+ * removed by setup, so it gets its own manual-action finding.
+ */
+export function classifyLegacyCodexWebpressoChannel(configPath = defaultCodexConfigFilePath(), homeDir = process.env.HOME || homedir()) {
+    const outcome = classifyCodexConfigWebpressoBlock(configPath);
+    if (outcome === null || outcome.kind === "absent")
+        return null;
+    if (outcome.kind === "ambiguous") {
+        return `${configPath} declares webpresso in a TOML spelling wp setup cannot rewrite; remove the [mcp_servers.webpresso] definition by hand — the bundled Codex plugin is the single delivery channel`;
+    }
+    if (outcome.kind === "preserved") {
+        return `${configPath} declares a user-authored webpresso MCP server (${outcome.command ?? "no command"}); wp setup preserves it. Remove it by hand to use the bundled Codex plugin as the single delivery channel`;
+    }
+    const dualChannel = findInstalledCodexPluginMcpManifests(homeDir).length > 0;
+    const prefix = dualChannel
+        ? "webpresso is registered over BOTH delivery channels — the bundled Codex plugin AND a legacy"
+        : "webpresso is still registered over the retired legacy";
+    return `${prefix} [mcp_servers.webpresso] block in ${configPath} (command = ${outcome.command}); run \`wp setup\` — it removes the legacy block`;
+}
+function classifyCodexConfigWebpressoBlock(configPath) {
+    try {
+        if (!existsSync(configPath))
+            return null;
+        return pruneOwnedMcpServerBlock(readFileSync(configPath, "utf8"), WEBPRESSO_MCP_SERVER_NAME, isAgentKitOwnedWpCommand);
+    }
+    catch {
+        return null;
+    }
+}
 async function checkOpenCodeHost(cwd = process.cwd()) {
     const available = await runCommand("opencode", ["--version"]);
     if (!available.ok) {
@@ -1430,9 +1493,8 @@ export function checkPackagedHostArtifacts(cwd = process.cwd()) {
             const serverRecord = server && typeof server === "object" && !Array.isArray(server)
                 ? server
                 : null;
-            if (serverRecord?.command !== "${PLUGIN_ROOT}/bin/wp" ||
-                !stringArrayEquals(serverRecord.args, ["mcp"])) {
-                failures.push("Codex adapter MCP surface must expose direct webpresso server map launching ${PLUGIN_ROOT}/bin/wp mcp");
+            if (serverRecord?.command !== "wp" || !stringArrayEquals(serverRecord.args, ["mcp"])) {
+                failures.push("Codex adapter MCP surface must expose direct webpresso server map launching wp mcp");
             }
         }
         if (codexHooks) {
@@ -2138,6 +2200,13 @@ export async function runHooksDoctor(opts = {}) {
     const rtkCheck = await checkRtkOnPath(opts.cwd);
     if (rtkCheck)
         checks.push(rtkCheck);
+    const freestandingRtk = checkFreestandingRtkSurface(opts.cwd);
+    if (freestandingRtk)
+        checks.push(freestandingRtk);
+    // Non-mutating WARN only — never mutates ~/.claude; surfaces dual-rewriter risk.
+    const globalFreestandingRtk = checkGlobalFreestandingRtkSurface();
+    if (globalFreestandingRtk)
+        checks.push(globalFreestandingRtk);
     if (shouldRunHostChecks(hostMode)) {
         for (const host of requestedHosts) {
             if (host === "codex") {

package/dist/esm/hooks/pretool-guard/dev-routing.js

@@ -23,7 +23,7 @@ function routeRawMutatingGitWorktree(command) {
     return {
         action: "deny",
         tool: "wp_worktree",
-        guidance: "Use the `wp_worktree` MCP tool (or `wp worktree` CLI when MCP is unavailable) instead — managed repositories may mutate linked worktrees only through agent-kit so owner bindings and the global registry stay consistent.",
+        guidance: "Use the `wp_worktree` MCP tool (or `wp worktree prune --all` / `wp worktree remove <target>` when MCP is unavailable) instead — managed repositories may mutate linked worktrees only through agent-kit so owner bindings and the global registry stay consistent. Both prune paths also run `git worktree prune`, so a hand-deleted worktree directory still releases the branch it claimed.",
         code: "GUARD_RAW_GIT_MUTATION",
     };
 }
@@ -296,11 +296,11 @@ const SAFE_PASSTHROUGH_PREFIXES = [
 const SANDBOX_PREFIXES = [
     {
         prefix: "grep",
-        guidance: "Use wp_session_batch_execute for bounded shell gathering/search commands so output is capped, indexed, and recallable instead of flooding the transcript. If MCP is unavailable, use a bounded `rg -n ... | sed -n '1,120p'` excerpt instead of recursive raw grep output",
+        guidance: "Recursive/directory-wide grep is unbounded; narrow to explicit file target(s) (`grep -n pattern file`) to pass through directly. Otherwise use wp_session_batch_execute for bounded search so output is capped, indexed, and recallable instead of flooding the transcript — note wp_session_batch_execute runs argv directly (no shell) and cannot express `|`/`>`. If MCP is unavailable, use a bounded `rg -n ... | sed -n '1,120p'` excerpt instead of recursive raw grep output",
     },
     {
         prefix: "find",
-        guidance: "Use wp_session_batch_execute for bounded shell gathering/search commands so output is capped, indexed, and recallable instead of flooding the transcript. If MCP is unavailable, use `rg --files ... | sed -n '1,120p'` or another explicit bounded listing",
+        guidance: "Use wp_session_batch_execute for bounded shell gathering/search commands so output is capped, indexed, and recallable instead of flooding the transcript — note wp_session_batch_execute runs argv directly (no shell) and cannot express `|`/`>`. If MCP is unavailable, use `rg --files ... | sed -n '1,120p'` or another explicit bounded listing",
     },
     {
         prefix: "cat",
@@ -324,7 +324,7 @@ const SANDBOX_PREFIXES = [
     },
     {
         prefix: "git log",
-        guidance: "Use wp_session_batch_execute for bounded git log shell gathering so output is capped, indexed, and recallable. If MCP is unavailable, use explicit bounds such as `git log --oneline -n 50`",
+        guidance: "Add an explicit count bound (`-N`, `-n N`, or `--max-count=N`) to pass through directly — e.g. `git log --oneline -50`. Otherwise use wp_session_batch_execute for bounded git log shell gathering so output is capped, indexed, and recallable. If MCP is unavailable, use an explicit bound directly, e.g. `git log --oneline -n 50`",
     },
     {
         prefix: "git diff",
@@ -332,7 +332,7 @@ const SANDBOX_PREFIXES = [
     },
     {
         prefix: "git show",
-        guidance: "Use wp_session_batch_execute or wp_session_execute for bounded git show gathering instead of raw large output. If MCP is unavailable, use `git show --stat` or a targeted excerpt",
+        guidance: "Add `--stat`/`--name-only`/`--name-status`/`--shortstat` to pass through directly — e.g. `git show --stat HEAD` — or use wp_session_batch_execute or wp_session_execute for bounded gathering of the full patch",
     },
     {
         prefix: "vp run build",
@@ -782,6 +782,63 @@ const BOUNDED_GIT_DIFF = new RegExp(String.raw `^git\s+${SIMPLE_GIT_GLOBAL_OPTIO
 function isBoundedGitDiffRead(command) {
     return BOUNDED_GIT_DIFF.test(command);
 }
+// `git log`/`git show` reads are bounded (small, predictable output) exactly when
+// they carry an explicit count/summary bound the same way BOUNDED_GIT_DIFF already
+// recognizes `--stat`/`--name-only`/etc. as bounded. Unbounded forms (bare `git log`,
+// full-patch `git show <ref>`) still fall through to the SANDBOX_PREFIXES rules below.
+const SIMPLE_GIT_LOG_PREFIX = new RegExp(String.raw `^git\s+${SIMPLE_GIT_GLOBAL_OPTION}log\b`, "u");
+const GIT_LOG_COUNT_BOUND = /(?:^|\s)(?:-\d+|-n[=\s]?\d+|--max-count(?:=|\s+)\d+)(?:\s|$)/u;
+function isBoundedGitLogRead(command) {
+    return SIMPLE_GIT_LOG_PREFIX.test(command) && GIT_LOG_COUNT_BOUND.test(command);
+}
+const BOUNDED_GIT_SHOW = new RegExp(String.raw `^git\s+${SIMPLE_GIT_GLOBAL_OPTION}show\b(?=[\s\S]*(?:--stat\b|--shortstat\b|--name-only\b|--name-status\b))(?![\s\S]*(?:--patch\b|-p\b))`, "u");
+function isBoundedGitShowRead(command) {
+    return BOUNDED_GIT_SHOW.test(command);
+}
+// A grep read is bounded when it targets explicit file argument(s) (not a whole
+// directory tree via -r/-R/--recursive/--include/--exclude*) and supplies at least
+// one non-flag file target beyond the pattern itself. Recursive/directory-wide grep
+// stays sandboxed since its output size is unpredictable.
+const GREP_RECURSIVE_LONG_FLAGS = new Set([
+    "--recursive",
+    "--include",
+    "--exclude",
+    "--exclude-dir",
+    "--exclude-from",
+]);
+function isBoundedGrepRead(command) {
+    const tokens = tokenizeCommand(command);
+    if (tokens[0] !== "grep")
+        return false;
+    const positionals = [];
+    let optionsEnded = false;
+    for (let index = 1; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (!token)
+            continue;
+        if (!optionsEnded && token === "--") {
+            optionsEnded = true;
+            continue;
+        }
+        if (!optionsEnded && token !== "-" && token.startsWith("-")) {
+            const longFlag = token.split("=")[0] ?? token;
+            if (GREP_RECURSIVE_LONG_FLAGS.has(longFlag))
+                return false;
+            // Strip a trailing bundled numeric argument (e.g. the `2` in `-rA2` for
+            // `-r -A 2`) before checking for a bundled `r`/`R` — otherwise a
+            // recursive short flag bundled with a value-taking flag like `-A`/`-B`/
+            // `-C`/`-m` slips past undetected.
+            const shortCluster = token.slice(1).replace(/\d+$/u, "");
+            if (/^[A-Za-z]+$/u.test(shortCluster) && /[rR]/u.test(shortCluster))
+                return false;
+            continue;
+        }
+        positionals.push(token);
+    }
+    // First positional is the search pattern; at least one more explicit file
+    // target is required to count as a bounded (non-stdin, non-directory) read.
+    return positionals.length >= 2;
+}
 function escapedRegexToken(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
@@ -982,6 +1039,12 @@ export function routeCommand(command, _sessionId) {
     }
     if (isBoundedGitDiffRead(trimmed))
         return { action: { action: "passthrough" } };
+    if (isBoundedGitLogRead(trimmed))
+        return { action: { action: "passthrough" } };
+    if (isBoundedGitShowRead(trimmed))
+        return { action: { action: "passthrough" } };
+    if (isBoundedGrepRead(trimmed))
+        return { action: { action: "passthrough" } };
     // Explicit passthroughs (audits, safe git/nav commands)
     for (const prefix of PASSTHROUGH_PREFIXES) {
         if (matchesPrefix(trimmed, prefix))

package/dist/esm/hooks/pretool-guard/rtk-rewrite.d.ts

@@ -0,0 +1,24 @@
+/**
+ * RTK rewrite inside path-stable pretool-guard (no freestanding consumer hook).
+ *
+ * v1: exact `git status` → `<managed-rtk> git status` when managed rtk is available.
+ */
+export type RtkRewriteDecision = {
+    readonly action: "rewrite";
+    readonly command: string;
+} | {
+    readonly action: "noop";
+    readonly reason: string;
+};
+export type RtkPresenceProbe = () => boolean;
+export type RtkExecutableResolver = () => string | null;
+/**
+ * Decide whether to rewrite a Bash command through managed rtk.
+ */
+export declare function decideRtkRewrite(command: string, isRtkPresent?: RtkPresenceProbe, resolveExecutable?: RtkExecutableResolver): RtkRewriteDecision;
+/**
+ * POSIX single-quote wrap for absolute managed paths.
+ * Refuse NUL/newline/single-quote — those cannot be safely embedded in `'…'`.
+ * Double-quote wrapping is intentionally avoided ($ / ` / " injection).
+ */
+export declare function shellQuoteExecutable(path: string): string | null;

package/dist/esm/hooks/pretool-guard/rtk-rewrite.js

@@ -0,0 +1,50 @@
+/**
+ * RTK rewrite inside path-stable pretool-guard (no freestanding consumer hook).
+ *
+ * v1: exact `git status` → `<managed-rtk> git status` when managed rtk is available.
+ */
+import { isManagedRtkAvailable, resolveManagedRtkExecutable } from "#tool-runtime/managed-rtk.js";
+const UNCERTAIN_SHELL_RE = /[\n\r|;&<>`$(){}[\]\\'"#*?]/u;
+/**
+ * Decide whether to rewrite a Bash command through managed rtk.
+ */
+export function decideRtkRewrite(command, isRtkPresent = isManagedRtkAvailable, resolveExecutable = resolveManagedRtkExecutable) {
+    if (command !== command.trim() || command.length === 0) {
+        return { action: "noop", reason: "uncertain-parse" };
+    }
+    if (UNCERTAIN_SHELL_RE.test(command)) {
+        return { action: "noop", reason: "uncertain-parse" };
+    }
+    // already managed absolute path or bare rtk prefix
+    if (command.startsWith("rtk ") || command.includes("/rtk ")) {
+        return { action: "noop", reason: "already-rtk" };
+    }
+    if (command !== "git status") {
+        return { action: "noop", reason: "not-eligible" };
+    }
+    if (!isRtkPresent()) {
+        return { action: "noop", reason: "rtk-missing" };
+    }
+    const executable = resolveExecutable();
+    if (!executable) {
+        return { action: "noop", reason: "rtk-missing" };
+    }
+    const bin = shellQuoteExecutable(executable);
+    if (!bin) {
+        return { action: "noop", reason: "rtk-missing" };
+    }
+    return { action: "rewrite", command: `${bin} git status` };
+}
+/**
+ * POSIX single-quote wrap for absolute managed paths.
+ * Refuse NUL/newline/single-quote — those cannot be safely embedded in `'…'`.
+ * Double-quote wrapping is intentionally avoided ($ / ` / " injection).
+ */
+export function shellQuoteExecutable(path) {
+    if (path.length === 0 || /[\0\n\r']/.test(path))
+        return null;
+    // Unquoted only for the common managed-cache shape (no shell metacharacters).
+    if (/^[A-Za-z0-9_./:@+=,-]+$/.test(path))
+        return path;
+    return `'${path}'`;
+}

package/dist/esm/hooks/pretool-guard/runner.js

@@ -11,6 +11,7 @@ import { VALIDATORS } from "./validators/index.js";
 import { isDirectEntrypoint } from "#hooks/shared/direct-entrypoint";
 import { optimizeToolInput, } from "./optimization.js";
 import { recordOptimizationEvent } from "./optimization-events.js";
+import { decideRtkRewrite } from "./rtk-rewrite.js";
 const RED = "\x1b[31m";
 const YELLOW = "\x1b[33m";
 const DIM = "\x1b[2m";
@@ -256,6 +257,11 @@ export function processValidation(inputJson, options = {}) {
         process.exit(2);
     }
     if (command) {
+        const rtkRewrite = decideRtkRewrite(command);
+        if (rtkRewrite.action === "rewrite") {
+            writeUpdatedInput(input, rtkRewrite.command);
+            process.exit(0);
+        }
         const originalAction = routeCommand(command)?.action ?? { action: "passthrough" };
         const optimization = optimizeToolInput(input, originalAction, options.optimizationRules);
         if (optimization.action === "rewrite") {

package/dist/esm/hooks/pretool-guard/validators/worktree-discipline.js

@@ -850,7 +850,9 @@ const GIT_GLOBAL_RUN = `(?:-C\\s+${QUOTED_ARG}\\s+|-c\\s+${QUOTED_ARG}\\s+|--git
 // branch flags are allowed.
 const FORBIDDEN_SUBCOMMAND = "(commit\\b|switch\\b(?!\\s+(?:-h|--help)\\b)|checkout\\s+(?!--(?:\\s|$))(?:(?:\\S+\\s+)*)\\S|branch\\s+(?:(?!-|--)\\S|--track\\b|--no-track\\b|--create-reflog\\b|--force\\b|-f\\b|-c\\b|-C\\b|-m\\b|-M\\b))";
 const FORBIDDEN_OP = new RegExp(`\\bgit\\s+(${GIT_GLOBAL_RUN})${FORBIDDEN_SUBCOMMAND}`, "gu");
-const MAIN_OWNERSHIP_OP = new RegExp(`\\bgit\\s+(${GIT_GLOBAL_RUN})(switch\\b[^;&|(){}]*|checkout\\b[^;&|(){}]*|branch\\b[^;&|(){}]*|worktree\\s+add\\b[^;&|(){}]*)`, "gu");
+// Verb-only: deliberately does NOT slurp trailing arguments itself (see
+// mainOwnershipGitOps below for why a naive `[^;&|(){}]*` capture is unsafe).
+const MAIN_OWNERSHIP_VERB = new RegExp(`\\bgit\\s+(${GIT_GLOBAL_RUN})(switch\\b|checkout\\b|branch\\b|worktree\\s+add\\b)`, "gu");
 function labelFor(subcommand) {
     if (subcommand.startsWith("commit"))
         return "git commit";
@@ -958,12 +960,69 @@ function mainOwnershipLabel(words) {
         return "git worktree add main";
     return null;
 }
+/**
+ * Quote-aware segment bounds for `command`, split on the same unquoted
+ * `;&|(){}` control characters as {@link splitShellSegments} (kept in sync
+ * intentionally), but returning OFFSETS instead of trimmed substrings so a
+ * caller can slice the original command text for a match that falls inside a
+ * given segment.
+ */
+function segmentBounds(command) {
+    const bounds = [];
+    let start = 0;
+    let quote = null;
+    let escaped = false;
+    for (let i = 0; i < command.length; i += 1) {
+        const ch = command[i];
+        if (ch === undefined)
+            continue;
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (quote !== "'" && ch === "\\") {
+            escaped = true;
+            continue;
+        }
+        if ((ch === '"' || ch === "'") && (quote === null || quote === ch)) {
+            quote = quote === ch ? null : ch;
+            continue;
+        }
+        if (!quote && /[;&|(){}]/u.test(ch)) {
+            bounds.push({ start, end: i });
+            start = i + 1;
+        }
+    }
+    bounds.push({ start, end: command.length });
+    return bounds;
+}
+/**
+ * Main-ownership candidate ops (`git switch|checkout|branch|worktree add`).
+ *
+ * MAIN_OWNERSHIP_VERB intentionally does NOT slurp trailing arguments itself
+ * (unlike the pre-fix implementation) — a naive `[^;&|(){}]*` character class
+ * is not quote-aware, so a read-only `git branch --format='%(refname:short)'`
+ * has its captured subcommand text truncated mid-quote at the `(` inside the
+ * quoted format string, producing an unterminated quote that shellWords()
+ * reports as "ambiguous" and gets fail-closed blocked — purely because of a
+ * paren inside its OWN quoted argument, not because it mutates anything.
+ * Bounding the subcommand text to the enclosing quote-aware shell segment
+ * (segmentBounds, sharing splitShellSegments' control-char set) fixes that
+ * without weakening real-mutation detection: genuinely ambiguous syntax
+ * (nested shells, unresolved substitutions, unterminated quotes) still
+ * produces "ambiguous" and fails closed exactly as before.
+ */
 function mainOwnershipGitOps(command) {
     if (!/\bgit\b/u.test(command))
         return [];
     const ops = [];
-    for (const m of command.matchAll(MAIN_OWNERSHIP_OP)) {
-        const subcommand = m[2] ?? "";
+    const segments = segmentBounds(command);
+    for (const m of command.matchAll(MAIN_OWNERSHIP_VERB)) {
+        const verb = m[2] ?? "";
+        const verbStart = (m.index ?? 0) + m[0].length - verb.length;
+        const segment = segments.find((s) => verbStart >= s.start && verbStart < s.end) ??
+            { start: verbStart, end: command.length };
+        const subcommand = command.slice(verbStart, segment.end);
         const words = shellWords(subcommand);
         if (words === "ambiguous") {
             ops.push({ label: "git main", globals: m[1] ?? "", index: m.index ?? 0 });

package/dist/esm/hooks/status/index.js

@@ -109,7 +109,7 @@ function hasValidCodexPluginArtifacts(repoRoot) {
     const hookMap = hooks?.hooks;
     return (plugin?.mcpServers === "./.mcp.json" &&
         plugin.hooks === "./hooks/hooks.json" &&
-        serverRecord?.command === "${PLUGIN_ROOT}/bin/wp" &&
+        serverRecord?.command === "wp" &&
         stringArrayEquals(serverRecord.args, ["mcp"]) &&
         hookMap !== null &&
         typeof hookMap === "object" &&

package/dist/esm/mcp/blueprint/_shared/lifecycle.js

@@ -94,21 +94,49 @@ export async function applyLocalBlueprintTransition(input) {
     mkdirSync(path.dirname(found.shape === "flat" ? destination.flat : destination.directory), {
         recursive: true,
     });
+    const sourcePath = found.shape === "flat" ? overviewPath : found.dir;
+    const destinationPath = found.shape === "flat" ? destination.flat : destination.directory;
     let finalOverviewPath = overviewPath;
+    let renamed = false;
     if (found.state !== to_state) {
         const { renameSync } = await import("node:fs");
-        renameSync(found.shape === "flat" ? overviewPath : found.dir, found.shape === "flat" ? destination.flat : destination.directory);
+        renameSync(sourcePath, destinationPath);
+        renamed = true;
         finalOverviewPath = found.shape === "flat" ? destination.flat : destination.folder;
     }
-    writeFileAtomic(finalOverviewPath, updated, "utf8");
-    await reIngest(projectCwd);
-    const refreshed = getCurrentProjectBlueprint(projectCwd, slug);
-    if (!refreshed.blueprint) {
-        throw new Error(`Blueprint "${slug}" did not appear in the projection after transition`);
+    // Atomicity: everything from here on can still fail (re-ingest, projection
+    // lookup). The rename above may already have happened, and the frontmatter
+    // write below always happens before those checks run. Roll BOTH back
+    // before rethrowing so a failed transition never leaves the blueprint
+    // stranded in the destination lifecycle directory, nor leaves stale
+    // frontmatter (bumped last_updated/progress/status) on an otherwise
+    // unmoved file — either the transition fully lands (moved + content
+    // updated + re-ingested + visible in the projection) or the working tree
+    // is restored to exactly what it was before this call.
+    try {
+        writeFileAtomic(finalOverviewPath, updated, "utf8");
+        await reIngest(projectCwd);
+        const refreshed = getCurrentProjectBlueprint(projectCwd, slug);
+        if (!refreshed.blueprint) {
+            throw new Error(`Blueprint "${slug}" did not appear in the projection after transition`);
+        }
+        return {
+            blueprint: refreshed.blueprint,
+            overviewPath: finalOverviewPath,
+            fromState: found.state,
+        };
+    }
+    catch (error) {
+        try {
+            if (renamed) {
+                const { renameSync } = await import("node:fs");
+                renameSync(destinationPath, sourcePath);
+            }
+            writeFileAtomic(overviewPath, markdown, "utf8");
+        }
+        catch (rollbackError) {
+            throw new Error(`Transition to "${to_state}" failed and automatic rollback also failed; the blueprint may be left ${renamed ? `moved at ${destinationPath}` : "with partially-updated frontmatter"}. Original error: ${error instanceof Error ? error.message : String(error)}. Rollback error: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
+        }
+        throw error;
     }
-    return {
-        blueprint: refreshed.blueprint,
-        overviewPath: finalOverviewPath,
-        fromState: found.state,
-    };
 }

package/dist/esm/mcp/blueprint/handlers/review-log.d.ts

@@ -2,13 +2,20 @@ import type { ProjectResolver } from "#project-resolver.js";
 import type { ToolHandlerResult } from "#mcp/auto-discover.js";
 /**
  * MCP wrapper around the SAME reviews.md-ledger writer `logReviewEntry` that
- * (an unwired) `wp review log` uses, plus the matching frontmatter `approvals:`
- * entry that `collectTrackedReviewProvenance` (the promotion approval gate)
- * actually reads. This is the tracked/frontmatter provenance path — the same
- * trust model a hand-authored `approvals:` block already had (the reviewer id
- * is caller-asserted, verified only by the referenced artifact/reviews.md
- * entry being tracked in git) — this tool just makes that existing path
- * reachable from MCP instead of a raw Write/Edit or a Bash/python workaround.
+ * (an unwired) `wp review log` uses. For NON-approval verdicts it also appends
+ * the matching frontmatter `approvals:` entry, so rejection attribution stays
+ * visible where readers already look. This is the tracked/frontmatter provenance
+ * path — the same trust model a hand-authored `approvals:` block already had (the
+ * reviewer id is caller-asserted, verified only by the referenced
+ * artifact/reviews.md entry being tracked in git) — this tool just makes that
+ * existing path reachable from MCP instead of a raw Write/Edit or a Bash/python
+ * workaround.
+ *
+ * It never writes a POLICY-APPROVAL entry (approve / approve-with-nits) into
+ * frontmatter. `collectTrackedReviewProvenance` — the legacy promotion leg — only
+ * counts policy approvals and never reads or hashes the blueprint body, so such
+ * an entry would be gate authority that survives an arbitrary rewrite of the
+ * plan. See `LEGACY_APPROVAL_LEG_ANCHOR_COMMIT` in `#lifecycle/rollout-anchor.js`.
  *
  * A policy-approval verdict (approve / approve-with-nits) REQUIRES
  * reviewer==="human" — matching `logReviewEvent`'s existing v2-ledger