@webpresso/agent-kit 3.1.30 → 3.2.0

package/dist/esm/cli/commands/run-wait.d.ts

@@ -0,0 +1,2 @@
+export declare const RUN_WAIT_HELP = "wp run wait \u2014 read-only GitHub workflow-run waiter (push/dispatch runs, e.g. production deploys on main)\n\nUsage:\n  wp run wait --run-id <id> [options]\n  wp run wait --sha <head-sha> [--workflow <file-or-name>] [options]\n\nSelector (exactly one required):\n  --run-id <id>           Watch a specific workflow run by database id\n  --sha <sha>             Watch the newest run for a head commit SHA\n  --workflow <file|name>  Filter --sha selection to one workflow\n\nOptions:\n  --until <target>        run-terminal (default) | all-jobs-terminal\n  --poll-interval-ms <n>  Poll interval (default 15000)\n  --timeout-ms <n>        Overall watch deadline (max 300000, default 120000)\n  --max-output-bytes <n>  Per-command output budget\n  --cwd <path>            Project root or descendant\n  --json                  Emit exactly one JSON document (default output)\n  -h, --help              Show this help\n\nRead-only: issues only `gh` GET calls; never mutates run state.";
+export declare function runRunWaitCommand(args: readonly string[]): Promise<number>;

package/dist/esm/cli/commands/run-wait.js

@@ -0,0 +1,122 @@
+import { RUN_WAIT_UNTIL_VALUES, runRunWait, } from "#mcp/tools/run-wait.js";
+// `wp run wait` is intercepted in cli.ts before the package-manager `run`
+// facade (which maps `wp run <script>` to `vp run <script>`). This module owns
+// only the `wait` subcommand and keeps arg parsing dependency-free so the
+// interception path stays cheap.
+export const RUN_WAIT_HELP = `wp run wait — read-only GitHub workflow-run waiter (push/dispatch runs, e.g. production deploys on main)
+
+Usage:
+  wp run wait --run-id <id> [options]
+  wp run wait --sha <head-sha> [--workflow <file-or-name>] [options]
+
+Selector (exactly one required):
+  --run-id <id>           Watch a specific workflow run by database id
+  --sha <sha>             Watch the newest run for a head commit SHA
+  --workflow <file|name>  Filter --sha selection to one workflow
+
+Options:
+  --until <target>        run-terminal (default) | all-jobs-terminal
+  --poll-interval-ms <n>  Poll interval (default 15000)
+  --timeout-ms <n>        Overall watch deadline (max 300000, default 120000)
+  --max-output-bytes <n>  Per-command output budget
+  --cwd <path>            Project root or descendant
+  --json                  Emit exactly one JSON document (default output)
+  -h, --help              Show this help
+
+Read-only: issues only \`gh\` GET calls; never mutates run state.`;
+function parsePositiveInteger(value, name) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return parsed;
+}
+function normalizeUntil(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.replaceAll("-", "_");
+    if (!RUN_WAIT_UNTIL_VALUES.includes(normalized)) {
+        throw new Error(`Unknown run wait target: ${value}`);
+    }
+    return normalized;
+}
+const VALUE_FLAGS = new Set([
+    "--run-id",
+    "--sha",
+    "--workflow",
+    "--until",
+    "--poll-interval-ms",
+    "--timeout-ms",
+    "--max-output-bytes",
+    "--cwd",
+]);
+function parseFlags(args) {
+    const values = {};
+    let help = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === undefined)
+            continue;
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+            continue;
+        }
+        if (arg === "--json")
+            continue; // JSON is the only output shape
+        const eq = arg.indexOf("=");
+        if (eq !== -1 && arg.startsWith("--")) {
+            const key = arg.slice(0, eq);
+            if (VALUE_FLAGS.has(key)) {
+                values[key] = arg.slice(eq + 1);
+                continue;
+            }
+        }
+        if (VALUE_FLAGS.has(arg)) {
+            const next = args[index + 1];
+            if (next === undefined)
+                throw new Error(`${arg} requires a value`);
+            values[arg] = next;
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown run wait option: ${arg}`);
+    }
+    return { values, help };
+}
+export async function runRunWaitCommand(args) {
+    const { values, help } = parseFlags(args);
+    if (help) {
+        console.log(RUN_WAIT_HELP);
+        return 0;
+    }
+    const runId = values["--run-id"];
+    const input = {
+        sha: values["--sha"],
+        runId: runId === undefined ? undefined : runId,
+        workflow: values["--workflow"],
+        until: normalizeUntil(values["--until"]),
+        pollIntervalMs: parsePositiveInteger(values["--poll-interval-ms"], "--poll-interval-ms"),
+        timeoutMs: parsePositiveInteger(values["--timeout-ms"], "--timeout-ms"),
+        maxOutputBytes: parsePositiveInteger(values["--max-output-bytes"], "--max-output-bytes"),
+        cwd: values["--cwd"],
+    };
+    let payload;
+    try {
+        payload = await runRunWait(input);
+    }
+    catch (error) {
+        const issues = error.issues;
+        if (Array.isArray(issues)) {
+            const message = issues
+                .map((issue) => (typeof issue.message === "string" ? issue.message : String(issue.message)))
+                .join("; ");
+            console.error(`wp run wait: ${message}`);
+            return 1;
+        }
+        throw error;
+    }
+    console.log(JSON.stringify(payload, null, 2));
+    return payload.status === "success" ? 0 : 1;
+}

package/dist/esm/cli/commands/setup-help.js

@@ -8,7 +8,7 @@ export function getSetupHelpText(version) {
         "Options:",
         "  --with <skills>     Comma-separated opt-in skills and/or presets to install (non-interactive). Presets: example-skill, lore-commits, playwright-mcp, rtk, vision plus the special token `all`. Legacy compatibility presets are intentionally omitted; use wp install oh-my opencode when you want WP-owned refreshes. Opt-in skills are listed by 'wp skill list'. ",
         "  --without <skills>  Comma-separated opt-in skills and/or presets to opt out of for this run. ",
-        "  --host <hosts>      Comma-separated host targets: codex, claude, opencode, all, none ",
+        "  --host <hosts>      Comma-separated host targets: codex, claude, opencode, grok, all, none ",
         "  --dry-run           Show what would change without writing anything ",
         "  --cwd <dir>         Working tree to scaffold into (default: process.cwd()) ",
         "  -h, --help          Display this message ",

package/dist/esm/cli/commands/setup-repair-help.js

@@ -5,7 +5,7 @@
 const PRIMARY_SETUP_OPTIONS = [
     "  --with <skills>     Comma-separated opt-in skills and/or presets to install (non-interactive). Presets: example-skill, lore-commits, playwright-mcp, rtk, vision plus the special token `all`. Legacy compatibility presets are intentionally omitted; use wp install oh-my opencode when you want WP-owned refreshes. Opt-in skills are listed by 'wp skill list'. ",
     "  --without <skills>  Comma-separated opt-in skills and/or presets to opt out of for this run. ",
-    "  --host <hosts>      Comma-separated host targets: codex, claude, opencode, all, none ",
+    "  --host <hosts>      Comma-separated host targets: codex, claude, opencode, grok, all, none ",
     "  --prune             Widen stale agent-kit plugin-cache pruning from the default host set (claude, codex, opencode) to every supported host while retaining recent versions ",
     "  --dry-run           Show what would change without writing anything ",
     "  --cwd <dir>         Working tree to scaffold into (default: process.cwd()) ",

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

@@ -5,6 +5,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { findGitRoot } from "#cli/commands/init/detect-consumer.js";
+import { removeCodexProjectTrust, removeCodexProjectTrusts, } from "#worktrees/codex-project-trust.js";
 import { shortId } from "#shared-utils/short-id.js";
 import { readConfig } from "#cli/commands/init/config";
 import { getProjectRoot } from "#cli/utils";
@@ -15,7 +16,7 @@ import { hydrateWorktreeDependencies, reconcileWorktreeDependencies, } from "#wo
 import { projectWorktreeAgentSurfaces } from "#worktrees/project-agent-surfaces.js";
 import { assertNotLocalMainBranch } from "#worktrees/main-ownership.js";
 import { buildWorktreeInventory, canonicalizeWorktreePath, classifyMembership, isManagedWorktreePath, resolveRepoIdentity, } from "#worktrees/identity.js";
-import { findRegistryCandidatesByPath, pruneStaleWorktreeRegistryEntries, readWorktreeRegistry, removeWorktreeRegistryEntries, repoScopedPathPredicate, upsertWorktreeRegistryEntry, } from "#worktrees/registry.js";
+import { findRegistryCandidatesByPath, planStaleWorktreeRegistryPrune, readWorktreeRegistry, removeWorktreeRegistryEntries, repoScopedPathPredicate, upsertWorktreeRegistryEntry, } from "#worktrees/registry.js";
 function parseDepsOption(value) {
     if (value === undefined || value === null || value === "")
         return undefined;
@@ -443,7 +444,7 @@ function handleRefresh(opts) {
     }
     console.log(`Refreshed ${updated} managed worktree entr${updated === 1 ? "y" : "ies"} for ${repoRoot}.`);
 }
-function handlePrune(opts) {
+async function handlePrune(opts) {
     if (!opts.all)
         throw new Error("Usage: wp worktree prune --all");
     // Repository-scoped, three-state prune: only THIS repo's entries that are
@@ -451,10 +452,12 @@ function handlePrune(opts) {
     // other-repo, and live-legacy entries are retained.
     const repoRoot = resolveWorktreeRepoRoot(opts.repo ?? opts.cwd ?? process.cwd());
     const inventory = buildWorktreeInventory(repoRoot);
-    const result = pruneStaleWorktreeRegistryEntries({
+    const result = planStaleWorktreeRegistryPrune({
         inventory,
         scope: { authoritativeRepoKey: resolveRepoIdentity(repoRoot) },
     });
+    await removeCodexProjectTrusts(result.removed.map((entry) => entry.path));
+    result.commit();
     console.log(`Pruned ${result.removed.length} stale managed registry entr${result.removed.length === 1 ? "y" : "ies"}.`);
     for (const warning of result.warnings)
         console.log(`warning: ${warning}`);
@@ -527,7 +530,7 @@ function handleRebind(args, opts) {
     console.log(`  worktree_owner_branch: ${binding.branch}`);
     console.log(`  path: ${binding.path}`);
 }
-function handleRemove(nameOrPath, opts) {
+async function handleRemove(nameOrPath, opts) {
     const cwd = opts.cwd ?? process.cwd();
     const callerRoot = resolveWorktreeRepoRoot(cwd);
     const entries = listEntries(callerRoot);
@@ -548,6 +551,7 @@ function handleRemove(nameOrPath, opts) {
     if (result.status !== 0) {
         throw new Error("git worktree remove failed");
     }
+    await removeCodexProjectTrust(resolved);
     removeWorktreeRegistryEntries(repoScopedPathPredicate(resolved, { authoritativeRepoKey: resolveRepoIdentity(repoRoot) }));
 }
 function isDirty(path) {
@@ -563,7 +567,7 @@ function currentBranch(repoRoot) {
     });
     return result.status === 0 ? String(result.stdout ?? "").trim() : "";
 }
-function handleMergeCleanup(nameOrPath, opts) {
+async function handleMergeCleanup(nameOrPath, opts) {
     const cwd = opts.cwd ?? process.cwd();
     const callerRoot = resolveWorktreeRepoRoot(cwd);
     const entries = listEntries(callerRoot);
@@ -628,6 +632,7 @@ function handleMergeCleanup(nameOrPath, opts) {
     if (removeResult.status !== 0) {
         throw new Error("git worktree remove failed");
     }
+    await removeCodexProjectTrust(resolved);
     removeWorktreeRegistryEntries(repoScopedPathPredicate(resolved, { authoritativeRepoKey: resolveRepoIdentity(repoRoot) }));
     const fetchResult = spawnSync("git", [...plan.fetchArgs], { cwd: repoRoot, stdio: "inherit" });
     if (fetchResult.status !== 0) {
@@ -665,7 +670,7 @@ export async function executeWorktreeSubcommand(subcommand, args, opts) {
             handleRefresh(opts);
             return;
         case "prune":
-            handlePrune(opts);
+            await handlePrune(opts);
             return;
         case "migrate":
             handleMigrate(opts);
@@ -682,7 +687,7 @@ export async function executeWorktreeSubcommand(subcommand, args, opts) {
             if (!nameOrPath) {
                 throw new Error("Usage: wp worktree remove <branch-or-path> [--force]");
             }
-            handleRemove(nameOrPath, opts);
+            await handleRemove(nameOrPath, opts);
             return;
         }
         case "merge-cleanup": {
@@ -690,7 +695,7 @@ export async function executeWorktreeSubcommand(subcommand, args, opts) {
             if (!nameOrPath) {
                 throw new Error("Usage: wp worktree merge-cleanup <branch-or-path> [--base <ref>] [--dry-run]");
             }
-            handleMergeCleanup(nameOrPath, opts);
+            await handleMergeCleanup(nameOrPath, opts);
             return;
         }
         default: {

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

@@ -79,8 +79,8 @@ function validateDirectProviderLaunch(provider, cwd) {
             ? `Run \`${installCommand}\` and retry.`
             : `Install ${ownershipName} and retry.`);
     }
-    // External PATH hosts (Grok) do not run optional-tool freshness — skip vp.
-    const vpCommand = resolveGlobalCapableVpCommand();
+    // External PATH hosts (Grok) do not run optional-tool freshness.
+    const vpCommand = adapter ? resolveGlobalCapableVpCommand() : null;
     if (adapter && !vpCommand) {
         throw new DirectProviderLaunchPreparationError("No global-capable Vite+ runner found.", "Reinstall @webpresso/agent-kit and retry.");
     }
@@ -105,10 +105,14 @@ function ensureCodexSessionTooling(repoRoot) {
         throw new DirectProviderLaunchPreparationError(`Codex project MCP server ${project.server} is unavailable: ${project.reason}`, "Run `wp setup --yes-global` from this repo to provision project MCP servers, then retry.");
     }
 }
+const PROVIDER_SESSION_PREFLIGHTS = {
+    claude: () => undefined,
+    codex: ensureCodexSessionTooling,
+    grok: () => undefined,
+    opencode: () => undefined,
+};
 function ensureProviderSessionTooling(provider, cwd) {
-    if (provider !== "codex")
-        return;
-    ensureCodexSessionTooling(cwd);
+    PROVIDER_SESSION_PREFLIGHTS[provider](cwd);
 }
 export function isBareInteractiveProviderLaunch(args) {
     return parseDashPermissionMode(args).args.length === 0;

package/dist/esm/cli/optional-tool-freshness.d.ts

@@ -15,6 +15,16 @@ export interface OptionalToolFreshnessCache {
     readonly version: 1;
     readonly tools: Partial<Record<ManagedToolName, OptionalToolFreshnessRecord>>;
 }
+export interface OptionalToolRefreshLeaseRecord {
+    readonly pid: number | null;
+    readonly startedAt: number;
+    readonly heartbeatAt: number;
+    readonly expiresAt: number;
+}
+export interface OptionalToolRefreshLeaseCache {
+    readonly version: 1;
+    readonly tools: Partial<Record<ManagedToolName, OptionalToolRefreshLeaseRecord>>;
+}
 export type OptionalToolFreshnessMode = "force" | "if-needed";
 export type OptionalToolFreshnessResult = {
     readonly kind: "missing";
@@ -66,9 +76,22 @@ export interface OptionalToolFreshnessDeps {
     }) => SpawnSyncReturns<string>;
     readonly readCache?: () => OptionalToolFreshnessCache;
     readonly writeCache?: (cache: OptionalToolFreshnessCache) => void;
+    readonly readLeaseCache?: () => OptionalToolRefreshLeaseCache;
+    readonly writeLeaseCache?: (cache: OptionalToolRefreshLeaseCache) => void;
+    readonly clearLease?: (tool: ManagedToolName) => void;
+    readonly spawnDetached?: (command: string, args: readonly string[], options: {
+        readonly cwd: string;
+    }) => {
+        readonly pid?: number | undefined;
+        readonly unref?: () => void;
+    };
 }
 export declare function readOptionalToolFreshnessCache(path?: string): OptionalToolFreshnessCache;
 export declare function writeOptionalToolFreshnessCache(cache: OptionalToolFreshnessCache, path?: string): void;
+export declare function readOptionalToolRefreshLeaseCache(path?: string): OptionalToolRefreshLeaseCache;
+export declare function writeOptionalToolRefreshLeaseCache(cache: OptionalToolRefreshLeaseCache, path?: string): void;
+export declare function clearOptionalToolRefreshLease(tool: ManagedToolName, path?: string): void;
+export declare function optionalToolRefreshLeaseRecord(pid: number | null, now: number): OptionalToolRefreshLeaseRecord;
 export declare function supportsOptionalToolFreshness(adapter: OptionalToolAdapter): boolean;
 /**
  * Resolve a WP-managed optional-tool adapter for a dash provider.
@@ -78,4 +101,8 @@ export declare function tryResolveProviderToolAdapter(provider: DashProvider): O
 export declare function resolveProviderToolAdapter(provider: DashProvider): OptionalToolAdapter;
 export declare function refreshOptionalToolSync(input: OptionalToolFreshnessInput, deps?: OptionalToolFreshnessDeps): OptionalToolFreshnessResult;
 export declare function ensureOptionalToolFreshnessForLaunch(input: Omit<OptionalToolFreshnessInput, "mode">, deps?: OptionalToolFreshnessDeps): Promise<OptionalToolFreshnessResult>;
+export declare function runOptionalToolRefreshWorker(args: readonly string[], deps?: OptionalToolFreshnessDeps & {
+    readonly readOwnershipState?: () => ToolingOwnershipState;
+    readonly resolveVpCommand?: () => GlobalCapableVpCommandInput | null;
+}): number;
 export {};

package/dist/esm/cli/optional-tool-freshness.js

@@ -1,16 +1,19 @@
-import { mkdirSync, existsSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, existsSync, rmSync } from "node:fs";
 import { dirname } from "node:path";
-import { spawnSync } from "node:child_process";
 import { UPDATE_CHECK_INTERVAL_MS } from "#cli/auto-update/cache.js";
+import { buildSelfInvocationCommand } from "#cli/auto-update/self-invocation.js";
 import { compareVersions } from "#cli/auto-update/version.js";
-import { appendGlobalCapableVpArgs } from "#cli/global-vp.js";
-import { optionalToolCanonicalCommand, resolveOptionalTool, } from "#cli/optional-tools.js";
-import { isUserOwnedTool, } from "#cli/tooling-ownership.js";
+import { appendGlobalCapableVpArgs, resolveGlobalCapableVpCommand, } from "#cli/global-vp.js";
+import { optionalToolCanonicalCommand, OPTIONAL_TOOL_ADAPTERS, resolveOptionalTool, } from "#cli/optional-tools.js";
+import { isUserOwnedTool, readToolingOwnershipState, } from "#cli/tooling-ownership.js";
 import { getSurfacePath, withLock } from "#paths/state-root.js";
 import { readTrustedJsonFile } from "#shared-utils/read-json-file.js";
 import { writeJsonFileAtomic } from "#shared-utils/write-json-file.js";
 const OPTIONAL_TOOL_FRESHNESS_CACHE = "optional-tool-freshness.json";
+const OPTIONAL_TOOL_REFRESH_LEASE = "optional-tool-refresh-lease.json";
 const VERSION_RE = /v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?/u;
+const UNKNOWN_VERSION = "unknown";
 /**
  * Hot-path budget for version probes (`<tool> --version`) and registry
  * latest-version queries (`vp info <pkg>`). These run on the dash/launch turn
@@ -30,9 +33,15 @@ export const OPTIONAL_TOOL_UPDATE_TIMEOUT_MS = 600_000;
 function emptyCache() {
     return { version: 1, tools: {} };
 }
+function emptyLeaseCache() {
+    return { version: 1, tools: {} };
+}
 function cachePath() {
     return getSurfacePath(OPTIONAL_TOOL_FRESHNESS_CACHE, "user");
 }
+function leasePath() {
+    return getSurfacePath(OPTIONAL_TOOL_REFRESH_LEASE, "user");
+}
 export function readOptionalToolFreshnessCache(path = cachePath()) {
     if (!existsSync(path))
         return emptyCache();
@@ -61,6 +70,44 @@ export function writeOptionalToolFreshnessCache(cache, path = cachePath()) {
     mkdirSync(dirname(path), { recursive: true });
     writeJsonFileAtomic(path, cache);
 }
+export function readOptionalToolRefreshLeaseCache(path = leasePath()) {
+    if (!existsSync(path))
+        return emptyLeaseCache();
+    try {
+        const parsed = readTrustedJsonFile(path);
+        if (parsed.version !== 1 || parsed.tools === null || typeof parsed.tools !== "object") {
+            return emptyLeaseCache();
+        }
+        return {
+            version: 1,
+            tools: Object.fromEntries(Object.entries(parsed.tools).filter((entry) => {
+                const record = entry[1];
+                return (record !== undefined &&
+                    (typeof record.pid === "number" || record.pid === null) &&
+                    typeof record.startedAt === "number" &&
+                    typeof record.heartbeatAt === "number" &&
+                    typeof record.expiresAt === "number");
+            })),
+        };
+    }
+    catch {
+        return emptyLeaseCache();
+    }
+}
+export function writeOptionalToolRefreshLeaseCache(cache, path = leasePath()) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeJsonFileAtomic(path, cache);
+}
+export function clearOptionalToolRefreshLease(tool, path = leasePath()) {
+    const cache = readOptionalToolRefreshLeaseCache(path);
+    const tools = { ...cache.tools };
+    delete tools[tool];
+    if (Object.keys(tools).length === 0) {
+        rmSync(path, { force: true });
+        return;
+    }
+    writeOptionalToolRefreshLeaseCache({ version: 1, tools }, path);
+}
 function nextCache(cache, tool, record) {
     return {
         version: 1,
@@ -70,6 +117,15 @@ function nextCache(cache, tool, record) {
         },
     };
 }
+function nextLeaseCache(cache, tool, record) {
+    return {
+        version: 1,
+        tools: {
+            ...cache.tools,
+            [tool]: record,
+        },
+    };
+}
 function readFreshRecord(cache, tool, observedVersion, now) {
     const record = cache.tools[tool];
     if (!record)
@@ -80,6 +136,14 @@ function readFreshRecord(cache, tool, observedVersion, now) {
         return null;
     return record;
 }
+function readFreshLaunchRecord(cache, tool, now) {
+    const record = cache.tools[tool];
+    if (!record)
+        return null;
+    if (now - record.checkedAt > UPDATE_CHECK_INTERVAL_MS)
+        return null;
+    return record;
+}
 function parseVersion(output) {
     const match = VERSION_RE.exec(output.trim());
     return match?.[0] ?? null;
@@ -142,6 +206,72 @@ function persistRecord(deps, adapter, record) {
 function cachedWarnings(record) {
     return record.status === "warning" && record.warning ? [record.warning] : [];
 }
+function launchCacheResult(adapter, record, fromCache) {
+    return {
+        kind: "ready",
+        adapter,
+        observedVersion: record?.observedVersion ?? UNKNOWN_VERSION,
+        latestVersion: record?.latestVersion ?? null,
+        updated: false,
+        warnings: record ? cachedWarnings(record) : [],
+        fromCache,
+    };
+}
+function refreshLeaseIsActive(record, now) {
+    return record !== undefined && record.expiresAt > now;
+}
+export function optionalToolRefreshLeaseRecord(pid, now) {
+    return {
+        pid,
+        startedAt: now,
+        heartbeatAt: now,
+        // The worker may run a real package update with the foreground update
+        // deadline, so the launch lease must cover that blocking child.
+        expiresAt: now + OPTIONAL_TOOL_UPDATE_TIMEOUT_MS + 60_000,
+    };
+}
+function defaultSpawnDetached(command, args, options) {
+    const child = spawn(command, [...args], {
+        cwd: options.cwd,
+        detached: true,
+        env: process.env,
+        stdio: "ignore",
+        windowsHide: true,
+    });
+    child.unref();
+    return child;
+}
+function spawnOptionalToolRefreshWorker(input, deps, now) {
+    const readLease = deps.readLeaseCache ?? readOptionalToolRefreshLeaseCache;
+    const writeLease = deps.writeLeaseCache ?? writeOptionalToolRefreshLeaseCache;
+    const clearLease = deps.clearLease ?? clearOptionalToolRefreshLease;
+    const lease = readLease();
+    if (refreshLeaseIsActive(lease.tools[input.adapter.id], now))
+        return;
+    const command = buildSelfInvocationCommand([
+        "optional-tool-refresh",
+        input.adapter.id,
+        "--cwd",
+        input.cwd,
+    ]);
+    try {
+        writeLease(nextLeaseCache(lease, input.adapter.id, optionalToolRefreshLeaseRecord(null, now)));
+        const child = (deps.spawnDetached ?? defaultSpawnDetached)(command[0], command.slice(1), {
+            cwd: input.cwd,
+        });
+        child.unref?.();
+    }
+    catch (error) {
+        clearLease(input.adapter.id);
+        persistRecord(deps, input.adapter, {
+            checkedAt: now,
+            observedVersion: UNKNOWN_VERSION,
+            latestVersion: null,
+            status: "warning",
+            warning: `${input.adapter.ownershipName} optional refresh could not start; launching without freshness proof.${error instanceof Error ? ` ${error.message}.` : ""}`,
+        });
+    }
+}
 export function supportsOptionalToolFreshness(adapter) {
     return adapter.namespace === "base" && Boolean(adapter.packageName && adapter.executableName);
 }
@@ -312,8 +442,88 @@ export function refreshOptionalToolSync(input, deps = {}) {
     };
 }
 export async function ensureOptionalToolFreshnessForLaunch(input, deps = {}) {
-    return withLock("user", () => refreshOptionalToolSync({
-        ...input,
-        mode: "if-needed",
-    }, deps));
+    if (!isUserOwnedTool(input.ownershipState, input.adapter.id)) {
+        return {
+            kind: "unmanaged",
+            adapter: input.adapter,
+            observedVersion: UNKNOWN_VERSION,
+            warning: `${input.adapter.ownershipName} is installed but not WP-owned. Run \`${optionalToolCanonicalCommand(input.adapter)}\` to let WP keep it current.`,
+        };
+    }
+    return withLock("user", () => {
+        const now = deps.now?.() ?? Date.now();
+        const readCache = deps.readCache ?? readOptionalToolFreshnessCache;
+        const cache = readCache();
+        const fresh = readFreshLaunchRecord(cache, input.adapter.id, now);
+        if (fresh)
+            return launchCacheResult(input.adapter, fresh, true);
+        const stale = cache.tools[input.adapter.id] ?? null;
+        spawnOptionalToolRefreshWorker(input, deps, now);
+        return launchCacheResult(input.adapter, stale, stale !== null);
+    });
+}
+export function runOptionalToolRefreshWorker(args, deps = {}) {
+    const [tool, ...rest] = args;
+    const adapter = OPTIONAL_TOOL_ADAPTERS.find((candidate) => candidate.id === tool);
+    if (!adapter || !supportsOptionalToolFreshness(adapter)) {
+        console.error(`optional-tool-refresh: unsupported tool ${tool ?? "<missing>"}`);
+        return 2;
+    }
+    let cwd = process.cwd();
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        if (arg === "--cwd") {
+            const value = rest[index + 1];
+            if (!value) {
+                console.error("optional-tool-refresh: --cwd requires a value");
+                return 2;
+            }
+            cwd = value;
+            index += 1;
+            continue;
+        }
+        console.error(`optional-tool-refresh: unsupported argument ${arg}`);
+        return 2;
+    }
+    const now = deps.now?.() ?? Date.now();
+    const writeLease = deps.writeLeaseCache ?? writeOptionalToolRefreshLeaseCache;
+    const readLease = deps.readLeaseCache ?? readOptionalToolRefreshLeaseCache;
+    const clearLease = deps.clearLease ?? clearOptionalToolRefreshLease;
+    writeLease(nextLeaseCache(readLease(), adapter.id, optionalToolRefreshLeaseRecord(typeof process.pid === "number" ? process.pid : null, now)));
+    try {
+        const vpCommand = deps.resolveVpCommand !== undefined
+            ? deps.resolveVpCommand()
+            : resolveGlobalCapableVpCommand();
+        if (!vpCommand) {
+            persistRecord(deps, adapter, {
+                checkedAt: now,
+                observedVersion: UNKNOWN_VERSION,
+                latestVersion: null,
+                status: "warning",
+                warning: `${adapter.ownershipName} optional refresh skipped because no global-capable Vite+ runner was found.`,
+            });
+            return 0;
+        }
+        const result = refreshOptionalToolSync({
+            adapter,
+            mode: "if-needed",
+            ownershipState: deps.readOwnershipState?.() ?? readToolingOwnershipState(),
+            vpCommand,
+            cwd,
+        }, deps);
+        if (result.kind === "missing") {
+            persistRecord(deps, adapter, {
+                checkedAt: now,
+                observedVersion: UNKNOWN_VERSION,
+                latestVersion: null,
+                status: "warning",
+                warning: result.warning,
+            });
+            return 0;
+        }
+        return 0;
+    }
+    finally {
+        clearLease(adapter.id);
+    }
 }

package/dist/esm/daemon/domains/git-actions.d.ts

@@ -1,7 +1,16 @@
 /**
  * Daemon-side git helpers for review panel RPCs (Task 1.5).
  * Runs real git via child_process — never re-implements porcelain.
+ *
+ * `gitCreatePr` additionally spawns `gh` (same class of utility-binary spawn
+ * as the `git` calls above — see Trust Dossier Material Decision MD1 on the
+ * desktop-daemon-rpc-completion blueprint overview for why this does not
+ * cross the daemon's "no agent-child spawn" invariant). It adapts
+ * the gh-wrapping logic from `src/mcp/tools/pr-upsert.ts` (preflight,
+ * collision detection, canonical re-fetch, output redaction) to this
+ * module's synchronous-git / injectable-deps pattern.
  */
+import { type RunOutcome } from "#mcp/tools/_shared/run-command.js";
 export type DiffFile = {
     readonly path: string;
     readonly status: string;
@@ -16,3 +25,23 @@ export declare function gitCommit(cwd: string, message: string, paths?: readonly
 }): {
     readonly commitSha: string;
 };
+export type CreatePrResult = {
+    readonly url: string;
+    readonly number?: number;
+};
+export interface GitCreatePrDeps {
+    /** Resolve the current branch name; throws on detached HEAD. Injectable for tests. */
+    readonly currentBranch?: (cwd: string) => string;
+    /** Invoke `gh` with args in `cwd`. Injectable for tests (no real `gh` binary required). */
+    readonly gh?: (args: readonly string[], cwd: string) => Promise<RunOutcome>;
+}
+/**
+ * Upsert semantics (the frozen daemon contract has no create/update `mode`
+ * field, see Trust Dossier MD2): edit the PR for the current branch if one
+ * already exists, else create it against the repo's default branch. Every
+ * success path re-fetches the canonical PR view rather than trusting
+ * `gh pr create`'s stdout alone (matches `src/mcp/tools/pr-upsert.ts`'s
+ * canonical-refetch pattern) so a create-collision (two callers racing)
+ * still returns the real PR instead of throwing.
+ */
+export declare function gitCreatePr(cwd: string, title: string, body: string | undefined, deps?: GitCreatePrDeps): Promise<CreatePrResult>;