@webpresso/agent-kit 3.3.3 → 3.3.4

package/dist/esm/daemon/handlers/product.d.ts

@@ -5,11 +5,21 @@
  * Domain implementations live in the sibling `*-handlers.ts` files; this
  * module only aggregates them into the map `startDaemonServer` consumes.
  */
+import type { BlueprintExecLedger } from "#daemon/domains/blueprint-exec-ledger.js";
+import type { LaunchLedger } from "#daemon/domains/launch.js";
 import type { MethodHandler } from "#daemon/rpc.js";
 /**
  * Build the default handler map. Callers may override individual methods via
  * `startDaemonServer({ handlers })` — overrides win.
+ *
+ * `launchLedger` / `execLedger` are daemon-scoped (one per server, not one per
+ * connection): blueprint exec registers a job on the webview connection and
+ * binds the PTY session on the rust connection, so both peers must see the
+ * same ledger instances.
  */
 export declare function createDefaultProductHandlers(options?: {
     readonly repoRoot?: string;
+    readonly allowlistedRoots?: readonly string[];
+    readonly launchLedger?: LaunchLedger;
+    readonly execLedger?: BlueprintExecLedger;
 }): Readonly<Partial<Record<string, MethodHandler>>>;

package/dist/esm/daemon/handlers/product.js

@@ -6,13 +6,22 @@ import { deployHandlers } from "./deploy-handlers.js";
 /**
  * Build the default handler map. Callers may override individual methods via
  * `startDaemonServer({ handlers })` — overrides win.
+ *
+ * `launchLedger` / `execLedger` are daemon-scoped (one per server, not one per
+ * connection): blueprint exec registers a job on the webview connection and
+ * binds the PTY session on the rust connection, so both peers must see the
+ * same ledger instances.
  */
 export function createDefaultProductHandlers(options) {
     const repoRoot = options?.repoRoot ?? process.cwd();
     return {
         ...gitHandlers,
         ...createFleetHandlers(repoRoot),
-        ...createBlueprintsHandlers(repoRoot),
+        ...createBlueprintsHandlers(repoRoot, {
+            launchLedger: options?.launchLedger,
+            execLedger: options?.execLedger,
+            allowlistedRoots: options?.allowlistedRoots,
+        }),
         ...createSessionsHandlers(repoRoot),
         ...deployHandlers,
     };

package/dist/esm/daemon/methods.d.ts

@@ -148,6 +148,26 @@ export declare const DAEMON_METHOD_REGISTRY: {
         readonly requireHandshake: true;
         readonly uiFacing: true;
     };
+    /** Read-only exec attribution + executor-written progress. Never PTY-derived. */
+    readonly "blueprints.execStatus": {
+        readonly privileged: true;
+        readonly requiresConfirmation: false;
+        readonly mutates: false;
+        readonly requireHandshake: true;
+        readonly uiFacing: true;
+    };
+    /**
+     * Rust-only: binds the spawned PTY session id to an exec job. Not UI-facing —
+     * the webview must never be able to re-point a job at another session.
+     */
+    readonly "blueprints.execBind": {
+        readonly privileged: true;
+        readonly requiresConfirmation: false;
+        readonly mutates: true;
+        readonly requireHandshake: true;
+        readonly allowedRoles: readonly ["rust"];
+        readonly uiFacing: false;
+    };
     readonly "deploy.run": {
         readonly privileged: true;
         readonly requiresConfirmation: true;
@@ -171,7 +191,7 @@ export type UiRpcMethod = {
     [M in DaemonRpcMethod]: (typeof DAEMON_METHOD_REGISTRY)[M]["uiFacing"] extends true ? M : never;
 }[DaemonRpcMethod];
 export declare const UI_RPC_METHODS: UiRpcMethod[];
-export declare const DESTRUCTIVE_METHODS: ("auth.issueNonce" | "blueprints.exec" | "blueprints.list" | "daemon.envMap.push" | "deploy.run" | "fleet.status" | "git.commit" | "git.createPr" | "git.diff" | "handshake" | "launch.claim" | "launch.permissionState" | "launch.prepare" | "ping" | "sessions.list" | "sessions.search" | "worktrees.list")[];
+export declare const DESTRUCTIVE_METHODS: ("auth.issueNonce" | "blueprints.exec" | "blueprints.execBind" | "blueprints.execStatus" | "blueprints.list" | "daemon.envMap.push" | "deploy.run" | "fleet.status" | "git.commit" | "git.createPr" | "git.diff" | "handshake" | "launch.claim" | "launch.permissionState" | "launch.prepare" | "ping" | "sessions.list" | "sessions.search" | "worktrees.list")[];
 export declare function getMethodCapability(method: string): MethodCapability | null;
 export declare function isDaemonRpcMethod(method: string): method is DaemonRpcMethod;
 export declare function isUiRpcMethod(method: string): method is UiRpcMethod;

package/dist/esm/daemon/methods.js

@@ -116,6 +116,26 @@ export const DAEMON_METHOD_REGISTRY = {
         requireHandshake: true,
         uiFacing: true,
     },
+    /** Read-only exec attribution + executor-written progress. Never PTY-derived. */
+    "blueprints.execStatus": {
+        privileged: true,
+        requiresConfirmation: false,
+        mutates: false,
+        requireHandshake: true,
+        uiFacing: true,
+    },
+    /**
+     * Rust-only: binds the spawned PTY session id to an exec job. Not UI-facing —
+     * the webview must never be able to re-point a job at another session.
+     */
+    "blueprints.execBind": {
+        privileged: true,
+        requiresConfirmation: false,
+        mutates: true,
+        requireHandshake: true,
+        allowedRoles: ["rust"],
+        uiFacing: false,
+    },
     "deploy.run": {
         privileged: true,
         requiresConfirmation: true,

package/dist/esm/daemon/protocol/contract.d.ts

@@ -79,6 +79,8 @@ export type HandshakeResult = z.infer<typeof handshakeResultSchema>;
 export declare const daemonRpcMethodSchema: z.ZodEnum<{
     "auth.issueNonce": "auth.issueNonce";
     "blueprints.exec": "blueprints.exec";
+    "blueprints.execBind": "blueprints.execBind";
+    "blueprints.execStatus": "blueprints.execStatus";
     "blueprints.list": "blueprints.list";
     "daemon.envMap.push": "daemon.envMap.push";
     "deploy.run": "deploy.run";
@@ -98,6 +100,7 @@ export declare const daemonRpcMethodSchema: z.ZodEnum<{
 export declare const uiRpcMethodSchema: z.ZodEnum<{
     "auth.issueNonce": "auth.issueNonce";
     "blueprints.exec": "blueprints.exec";
+    "blueprints.execStatus": "blueprints.execStatus";
     "blueprints.list": "blueprints.list";
     "deploy.run": "deploy.run";
     "fleet.status": "fleet.status";
@@ -303,11 +306,42 @@ export declare const blueprintsListResultSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const blueprintsExecParamsSchema: z.ZodObject<{
     slug: z.ZodString;
+    taskId: z.ZodOptional<z.ZodString>;
     confirmationToken: z.ZodString;
 }, z.core.$strict>;
+/**
+ * Opaque only. `jobId` is the durable exec-attribution key; `handle` is the
+ * single-use launch handle the Rust peer claims. Deliberately carries no
+ * command, args, cwd, or env — those never cross to the webview.
+ */
 export declare const blueprintsExecResultSchema: z.ZodObject<{
+    jobId: z.ZodString;
     handle: z.ZodString;
 }, z.core.$strict>;
+export declare const blueprintsExecStatusParamsSchema: z.ZodObject<{
+    slug: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Execution status is sourced from executor-written blueprint metadata, never
+ * from PTY output. The terminal stream is human-viewing only.
+ */
+export declare const blueprintsExecStatusResultSchema: z.ZodObject<{
+    jobs: z.ZodArray<z.ZodObject<{
+        jobId: z.ZodString;
+        slug: z.ZodString;
+        taskId: z.ZodNullable<z.ZodString>;
+        sessionId: z.ZodNullable<z.ZodNumber>;
+        state: z.ZodEnum<{
+            preparing: "preparing";
+            running: "running";
+            terminal: "terminal";
+        }>;
+        startedAt: z.ZodNumber;
+        executionId: z.ZodNullable<z.ZodString>;
+        executionStatus: z.ZodNullable<z.ZodString>;
+        executionUpdatedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 export declare const deployRunParamsSchema: z.ZodObject<{
     cwd: z.ZodString;
     lane: z.ZodString;
@@ -499,12 +533,36 @@ export declare const UI_METHOD_SCHEMAS: {
     readonly "blueprints.exec": {
         readonly params: z.ZodObject<{
             slug: z.ZodString;
+            taskId: z.ZodOptional<z.ZodString>;
             confirmationToken: z.ZodString;
         }, z.core.$strict>;
         readonly result: z.ZodObject<{
+            jobId: z.ZodString;
             handle: z.ZodString;
         }, z.core.$strict>;
     };
+    readonly "blueprints.execStatus": {
+        readonly params: z.ZodObject<{
+            slug: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            jobs: z.ZodArray<z.ZodObject<{
+                jobId: z.ZodString;
+                slug: z.ZodString;
+                taskId: z.ZodNullable<z.ZodString>;
+                sessionId: z.ZodNullable<z.ZodNumber>;
+                state: z.ZodEnum<{
+                    preparing: "preparing";
+                    running: "running";
+                    terminal: "terminal";
+                }>;
+                startedAt: z.ZodNumber;
+                executionId: z.ZodNullable<z.ZodString>;
+                executionStatus: z.ZodNullable<z.ZodString>;
+                executionUpdatedAt: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    };
     readonly "deploy.run": {
         readonly params: z.ZodObject<{
             cwd: z.ZodString;

package/dist/esm/daemon/protocol/contract.js

@@ -301,14 +301,48 @@ export const blueprintsListResultSchema = z
 export const blueprintsExecParamsSchema = z
     .object({
     slug: z.string().min(1),
+    /** Optional attribution only; never becomes part of the composed argv. */
+    taskId: z.string().min(1).optional(),
     confirmationToken: z.string().min(1),
 })
     .strict();
+/**
+ * Opaque only. `jobId` is the durable exec-attribution key; `handle` is the
+ * single-use launch handle the Rust peer claims. Deliberately carries no
+ * command, args, cwd, or env — those never cross to the webview.
+ */
 export const blueprintsExecResultSchema = z
     .object({
+    jobId: z.string().min(1),
     handle: opaqueHandleSchema,
 })
     .strict();
+export const blueprintsExecStatusParamsSchema = z
+    .object({
+    slug: z.string().min(1).optional(),
+})
+    .strict();
+/**
+ * Execution status is sourced from executor-written blueprint metadata, never
+ * from PTY output. The terminal stream is human-viewing only.
+ */
+export const blueprintsExecStatusResultSchema = z
+    .object({
+    jobs: z.array(z
+        .object({
+        jobId: z.string().min(1),
+        slug: z.string().min(1),
+        taskId: z.string().nullable(),
+        sessionId: z.number().int().nonnegative().nullable(),
+        state: z.enum(["preparing", "running", "terminal"]),
+        startedAt: z.number().int().nonnegative(),
+        executionId: z.string().nullable(),
+        executionStatus: z.string().nullable(),
+        executionUpdatedAt: z.string().nullable(),
+    })
+        .strict()),
+})
+    .strict();
 export const deployRunParamsSchema = z
     .object({
     cwd: z.string().min(1),
@@ -344,6 +378,10 @@ export const UI_METHOD_SCHEMAS = {
     "worktrees.list": { params: worktreesListParamsSchema, result: worktreesListResultSchema },
     "blueprints.list": { params: blueprintsListParamsSchema, result: blueprintsListResultSchema },
     "blueprints.exec": { params: blueprintsExecParamsSchema, result: blueprintsExecResultSchema },
+    "blueprints.execStatus": {
+        params: blueprintsExecStatusParamsSchema,
+        result: blueprintsExecStatusResultSchema,
+    },
     "deploy.run": { params: deployRunParamsSchema, result: deployRunResultSchema },
 };
 // ---------------------------------------------------------------------------

package/dist/esm/daemon/server.js

@@ -10,6 +10,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, sta
 import { createConnection, createServer } from "node:net";
 import { dirname, join } from "node:path";
 import { createDaemonAuthz } from "./authz.js";
+import { createBlueprintExecLedger } from "./domains/blueprint-exec-ledger.js";
 import { createLaunchLedger } from "./domains/launch.js";
 import { createDefaultProductHandlers } from "./handlers/product.js";
 import { getDefaultDaemonSocketPath } from "./paths.js";
@@ -104,6 +105,9 @@ export async function startDaemonServer(options = {}) {
         const server = createServer();
         const connections = new Set();
         const launchLedger = createLaunchLedger();
+        // Daemon-scoped, not per-connection: the webview registers an exec job and
+        // the rust peer binds the PTY session from a different connection.
+        const execLedger = createBlueprintExecLedger();
         server.on("connection", (socket) => {
             connections.add(socket);
             socket.on("close", () => connections.delete(socket));
@@ -137,6 +141,9 @@ export async function startDaemonServer(options = {}) {
                 handlers: {
                     ...createDefaultProductHandlers({
                         repoRoot: options.allowlistedRoots?.[0] ?? process.cwd(),
+                        allowlistedRoots: options.allowlistedRoots,
+                        launchLedger,
+                        execLedger,
                     }),
                     ...options.handlers,
                 },

package/dist/esm/docs-linter/blueprint-plan.js

@@ -1,3 +1,4 @@
+import { extractBlockedReason } from "#markdown/blocked-line";
 /**
  * Blueprint Plan Format Validator
  *
@@ -394,7 +395,6 @@ function validateLifecycleContract(filePath, content) {
     const taskBlocks = extractTaskBlocks(content);
     for (const task of taskBlocks) {
         const statusMatch = task.section.match(/\*\*Status:\*\*\s*(.+)/i);
-        const blockedMatch = task.section.match(/\*\*Blocked:\*\*\s*(.+)/i);
         const checkboxMatches = Array.from(task.section.matchAll(/^- \[([ x])\]/gm));
         const total = checkboxMatches.length;
         const checked = checkboxMatches.filter((match) => match[1] === "x").length;
@@ -407,7 +407,7 @@ function validateLifecycleContract(filePath, content) {
             errors.push(createTaskStatusInvalidError(filePath, task.id, taskStatus));
             continue;
         }
-        const blockedReason = blockedMatch?.[1]?.trim() ?? "";
+        const blockedReason = extractBlockedReason(task.section) ?? "";
         if (taskStatus === "blocked" && !blockedReason) {
             errors.push(createBlockedReasonRequiredError(filePath, task.id));
         }

package/dist/esm/errors/wp-error.js

@@ -11,8 +11,23 @@ export function validateWpErrorDocsUrl(value) {
     return value;
 }
 function redactStringValue(value, explicitSecrets) {
-    let next = redactText(value) ?? value;
-    let redacted = next !== value;
+    // Caller-declared secrets are masked FIRST, against the untouched original
+    // string, and always resolve to the full `[REDACTED]` form. The generic
+    // shared-redactor (`redactText`) runs SECOND, on whatever the explicit pass
+    // left behind.
+    //
+    // The order is load-bearing: `redactText`'s pattern set is broad (see
+    // `_shared/redact.ts`) and grows over time (h-010). A caller-supplied
+    // secret can incidentally match one of those generic shapes (e.g. a value
+    // adjacent to a `TOKEN=`/`SECRET:` key). Running the generic pass first
+    // would replace the literal with a *partial* mask (`CA***23`) before the
+    // explicit pass ever sees it, so `next.includes(secret)` fails silently and
+    // the caller's declared secret ends up under-redacted relative to what the
+    // caller explicitly asked to fully hide. A value the caller names as a
+    // secret is a stronger, more specific signal than a generic pattern match
+    // and must win.
+    let next = value;
+    let redacted = false;
     for (const secret of [...explicitSecrets].sort((left, right) => right.length - left.length)) {
         if (!secret)
             continue;
@@ -21,6 +36,10 @@ function redactStringValue(value, explicitSecrets) {
             redacted = true;
         }
     }
+    const generic = redactText(next) ?? next;
+    if (generic !== next)
+        redacted = true;
+    next = generic;
     return { value: next, redacted };
 }
 function redactUnknownEvidence(value, explicitSecrets) {

package/dist/esm/hooks/doctor.d.ts

@@ -57,6 +57,9 @@ export interface ResolvePackageRootForRuntimeOptions {
 }
 export declare function resolvePackageRootForRuntime(options?: ResolvePackageRootForRuntimeOptions): string | null;
 export declare function findOwningPackageRoot(startDir: string): string | null;
+export declare function checkFreestandingRtkSurface(cwd?: string): DoctorCheck | null;
+/** Non-mutating warn for user-global freestanding RTK rewriters (rtk init -g). */
+export declare function checkGlobalFreestandingRtkSurface(): DoctorCheck | null;
 export declare function checkRtkOnPath(cwd?: string): Promise<DoctorCheck | null>;
 export declare function checkRootLauncherContract(): DoctorCheck;
 export declare function checkRuntimePluginCacheStaleSurfaceRepair(options?: {
@@ -66,6 +69,14 @@ export declare function checkRuntimePluginCacheStaleSurfaceRepair(options?: {
 }): DoctorCheck;
 export declare function checkNativePluginRuntime(): DoctorCheck;
 export declare function checkPhase2RuntimeTypecheckParity(): DoctorCheck;
+/**
+ * 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 declare function classifyLegacyCodexWebpressoChannel(configPath?: string, homeDir?: string): string | null;
 export declare function checkPackagedHostArtifacts(cwd?: string): DoctorCheck;
 export declare function checkHostArtifactOwnership(cwd?: string): DoctorCheck;
 export declare function checkHostLifecycleDepth(): DoctorCheck;

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

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;