@webpresso/agent-kit 3.1.25 → 3.1.28

package/dist/esm/cli/commands/dash/tui/native-host.js

@@ -0,0 +1,256 @@
+// Domain host for the native Ratatui shell: maps AppViewModel ↔ IPC and keys → reduceTuiKey.
+import { spawn } from "node:child_process";
+import { emitDashE2eState } from "#cli/commands/dash/e2e-state.js";
+import { buildRows } from "#cli/commands/dash/menu-state.js";
+import { filterPaletteCommands, groupPaletteCommands } from "#cli/commands/dash/tui/palette.js";
+import { reduceTuiKey } from "#cli/commands/dash/tui/state.js";
+import { decodeIpcFrames, encodeIpcFrame, parseClientMessage, } from "#cli/commands/dash/tui/ipc-protocol.js";
+import { sanitizeTuiText } from "#cli/commands/dash/tui/sanitize.js";
+function hostAvailabilityNote(agentKey, availability) {
+    const row = availability.find((item) => item.id === agentKey);
+    if (!row || row.available)
+        return null;
+    return row.reason ?? "unavailable";
+}
+export function projectNativeViewModel(state, input) {
+    const rows = buildRows(state.agents, state.menu.expandedAgent);
+    const menuLines = rows.map((row) => {
+        const mark = row.key === state.menu.selectedKey ? "▸" : " ";
+        const note = row.kind === "agent" ? hostAvailabilityNote(row.agentKey, state.hostAvailability) : null;
+        const label = note ? `${row.label} · ${note}` : row.label;
+        return sanitizeTuiText(`${mark} ${label}`);
+    });
+    let overlayKind = state.overlay.kind;
+    let overlayLines = [];
+    if (state.overlay.kind === "palette") {
+        const matches = filterPaletteCommands(state.overlay.query);
+        const groups = groupPaletteCommands(matches);
+        overlayLines = [sanitizeTuiText(`query: ${state.overlay.query || "…"}`)];
+        for (const group of groups) {
+            overlayLines.push(sanitizeTuiText(`— ${group.category}`));
+            for (const [index, command] of group.commands.entries()) {
+                // Approximate global cursor: mark the selected match row.
+                const globalIndex = matches.indexOf(command);
+                const mark = globalIndex === state.overlay.cursor ? "▸" : " ";
+                overlayLines.push(sanitizeTuiText(`${mark} ${command.title} · ${command.keys}`));
+                void index;
+            }
+        }
+        if (matches.length === 0) {
+            overlayLines.push("(no matches)");
+        }
+    }
+    else if (state.overlay.kind === "help") {
+        overlayLines = [
+            "^p palette",
+            "^o mode",
+            "^s sessions",
+            "^x help",
+            "j/k move · h/l fold · g/G jump",
+            "q quit",
+        ];
+    }
+    else if (state.overlay.kind === "wizard") {
+        overlayLines = state.overlay.lines.map((line) => sanitizeTuiText(line));
+    }
+    else if (state.overlay.kind === "browser") {
+        overlayLines = state.overlay.lines.map((line) => sanitizeTuiText(line));
+    }
+    else if (state.overlay.kind === "lifecycle") {
+        overlayLines = [
+            sanitizeTuiText(`target ${state.overlay.target}`),
+            "d detach · s stop · f force-kill · a archive",
+            "Backspace delete · y confirm · Esc cancel",
+        ];
+    }
+    return {
+        repoLabel: sanitizeTuiText(input.repoLabel),
+        width: input.width,
+        height: input.height,
+        permissionMode: state.permissionMode,
+        hostAvailability: state.hostAvailability.map((h) => ({
+            id: h.id,
+            available: h.available,
+            ...(h.reason ? { reason: sanitizeTuiText(h.reason) } : {}),
+        })),
+        status: state.status ? sanitizeTuiText(state.status) : null,
+        warnings: state.warnings.map((w) => sanitizeTuiText(w)),
+        menuLines,
+        overlayKind,
+        overlayLines,
+        paletteQuery: state.overlay.kind === "palette" ? state.overlay.query : null,
+    };
+}
+export function clientMessageToParsedKey(message) {
+    switch (message.kind) {
+        case "char":
+            return message.value ? { kind: "char", value: message.value } : null;
+        case "up":
+        case "down":
+        case "left":
+        case "right":
+        case "enter":
+        case "escape":
+        case "tab":
+        case "backspace":
+            return { kind: message.kind };
+        case "ctrl":
+            return message.value ? { kind: "ctrl", value: message.value } : null;
+        default:
+            return null;
+    }
+}
+/**
+ * Drive pure TUI state from a native binary over length-prefixed JSON frames.
+ * State is owned by the caller (runtime) so launch/HUD/browser updates paint.
+ */
+export async function runNativeTuiHost(input) {
+    const spawnFn = input.spawnImpl ?? spawn;
+    const child = spawnFn(input.binaryPath, [], {
+        stdio: ["pipe", "pipe", "inherit"],
+    });
+    if (!child.stdin || !child.stdout) {
+        throw new Error("native shell spawn did not provide stdio pipes");
+    }
+    let stdinBuf = Buffer.alloc(0);
+    let width = 80;
+    let height = 24;
+    const childStdin = child.stdin;
+    const childStdout = child.stdout;
+    const pushView = () => {
+        if (!childStdin.writable)
+            return;
+        const view = projectNativeViewModel(input.getState(), {
+            repoLabel: input.repoLabel,
+            width,
+            height,
+        });
+        childStdin.write(encodeIpcFrame({ type: "view", view }));
+    };
+    input.onBridge?.({ pushView });
+    childStdin.write(encodeIpcFrame({ type: "hello", schemaVersion: 1 }));
+    pushView();
+    /**
+     * Handshake hang detection: fail closed if the shell never greets.
+     * After ready, probe process liveness so a zombie/stuck native binary
+     * cannot pin the domain host forever (runtime falls back to pure-ANSI).
+     */
+    const HANDSHAKE_MS = 30_000;
+    const LIVENESS_MS = 5_000;
+    return await new Promise((resolve) => {
+        let settled = false;
+        let handshakeDone = false;
+        let handshakeTimer = setTimeout(() => {
+            if (handshakeDone || settled)
+                return;
+            input.handlers.onQuit();
+            child.kill("SIGTERM");
+            setTimeout(() => child.kill("SIGKILL"), 2_000);
+            finish(1);
+        }, HANDSHAKE_MS);
+        let livenessTimer;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            if (handshakeTimer)
+                clearTimeout(handshakeTimer);
+            if (livenessTimer)
+                clearInterval(livenessTimer);
+            resolve(code);
+        };
+        const armLiveness = () => {
+            if (livenessTimer)
+                return;
+            livenessTimer = setInterval(() => {
+                if (settled)
+                    return;
+                // exitCode set when the process has already exited without us finishing.
+                if (child.exitCode !== null || child.signalCode !== null) {
+                    finish(child.exitCode ?? 1);
+                    return;
+                }
+                const pid = child.pid;
+                if (pid === undefined) {
+                    finish(1);
+                    return;
+                }
+                try {
+                    process.kill(pid, 0);
+                }
+                catch {
+                    finish(1);
+                }
+            }, LIVENESS_MS);
+        };
+        childStdout.on("data", (chunk) => {
+            stdinBuf = Buffer.concat([stdinBuf, chunk]);
+            let decoded;
+            try {
+                decoded = decodeIpcFrames(stdinBuf);
+            }
+            catch {
+                // Drop a corrupted frame prefix rather than crashing the domain host.
+                // Keep a bounded tail so a subsequent well-formed frame can resync.
+                stdinBuf = stdinBuf.length > 64 * 1024 ? stdinBuf.subarray(-4096) : Buffer.alloc(0);
+                return;
+            }
+            stdinBuf = Buffer.from(decoded.rest);
+            for (const raw of decoded.messages) {
+                let msg;
+                try {
+                    msg = parseClientMessage(raw);
+                }
+                catch {
+                    continue;
+                }
+                if (msg.type === "hello" || msg.type === "ready") {
+                    handshakeDone = true;
+                    if (handshakeTimer)
+                        clearTimeout(handshakeTimer);
+                    armLiveness();
+                    pushView();
+                    continue;
+                }
+                if (msg.type === "resize") {
+                    width = msg.width;
+                    height = msg.height;
+                    pushView();
+                    continue;
+                }
+                if (msg.type === "key") {
+                    const key = clientMessageToParsedKey(msg);
+                    if (!key)
+                        continue;
+                    const result = reduceTuiKey(input.getState(), key);
+                    input.setState(result.state);
+                    // Match pure-ANSI path: selection transitions ride the E2E channel so
+                    // CI tmux harness can assert menu navigation without screen scrapes.
+                    if (result.state.menu.selectedKey) {
+                        emitDashE2eState({ kind: "selection", row: result.state.menu.selectedKey });
+                    }
+                    for (const effect of result.effects) {
+                        void input.handlers.onEffect(effect);
+                        if (effect.kind === "quit") {
+                            input.handlers.onQuit();
+                            child.kill("SIGTERM");
+                            setTimeout(() => child.kill("SIGKILL"), 2_000);
+                            finish(0);
+                            return;
+                        }
+                    }
+                    if (result.state.quit) {
+                        input.handlers.onQuit();
+                        child.kill("SIGTERM");
+                        setTimeout(() => child.kill("SIGKILL"), 2_000);
+                        finish(0);
+                        return;
+                    }
+                    pushView();
+                }
+            }
+        });
+        child.on("exit", (code) => finish(code ?? 0));
+        child.on("error", () => finish(1));
+    });
+}

package/dist/esm/cli/commands/dash/tui/native-path.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Env contract:
+ * - `WP_DASH_NATIVE=0|false|off` → force pure-ANSI
+ * - `WP_DASH_NATIVE=1|true|on` → prefer native when binary present
+ * - unset → prefer native when binary present (cutover default)
+ * - `WP_DASH_TUI_BIN` → absolute path override
+ * - `WP_DASH_FORCE_ANSI=1` → runtime force pure-ANSI even if a binary resolves
+ */
+export declare function shouldPreferNativeDashTui(env?: NodeJS.ProcessEnv): boolean;
+export declare function resolveNativeDashTuiBinary(env?: NodeJS.ProcessEnv, candidates?: readonly string[]): string | null;
+export declare function defaultBinaryCandidates(cwd?: string): readonly string[];

package/dist/esm/cli/commands/dash/tui/native-path.js

@@ -0,0 +1,41 @@
+// Resolve the optional native wp-dash-tui binary for the control-plane shell.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { findPackageAsset } from "#utils/package-assets.js";
+/**
+ * Env contract:
+ * - `WP_DASH_NATIVE=0|false|off` → force pure-ANSI
+ * - `WP_DASH_NATIVE=1|true|on` → prefer native when binary present
+ * - unset → prefer native when binary present (cutover default)
+ * - `WP_DASH_TUI_BIN` → absolute path override
+ * - `WP_DASH_FORCE_ANSI=1` → runtime force pure-ANSI even if a binary resolves
+ */
+export function shouldPreferNativeDashTui(env = process.env) {
+    const flag = env["WP_DASH_NATIVE"]?.trim().toLowerCase();
+    if (flag === "0" || flag === "false" || flag === "off" || flag === "no") {
+        return false;
+    }
+    return true;
+}
+export function resolveNativeDashTuiBinary(env = process.env, candidates = defaultBinaryCandidates()) {
+    const override = env["WP_DASH_TUI_BIN"]?.trim();
+    if (override && existsSync(override))
+        return override;
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+export function defaultBinaryCandidates(cwd = process.cwd()) {
+    const fromPackage = [
+        findPackageAsset("native/dash-tui/target/release/wp-dash-tui", { cwd }),
+        findPackageAsset("native/dash-tui/target/debug/wp-dash-tui", { cwd }),
+    ].filter((path) => path !== null);
+    return [
+        join(cwd, "native/dash-tui/target/release/wp-dash-tui"),
+        join(cwd, "native/dash-tui/target/debug/wp-dash-tui"),
+        ...fromPackage,
+        join(cwd, "bin/wp-dash-tui"),
+    ];
+}

package/dist/esm/cli/commands/dash/tui/runtime.js

@@ -234,6 +234,8 @@ export async function runTuiMenu(input) {
     let dirty = true;
     let lastFrame = "";
     let running = true;
+    /** When set, domain state paints via the native shell instead of pure-ANSI. */
+    let nativePushView = null;
     /** Once true, no new launch effects may call selectAgent. */
     let shuttingDown = false;
     let initialLaunchConsumed = false;
@@ -261,6 +263,14 @@ export async function runTuiMenu(input) {
     const paint = () => {
         if (shuttingDown)
             return;
+        // Native shell owns the terminal; never write pure-ANSI frames over it.
+        if (nativePushView) {
+            if (!dirty && !input.smokeOnce)
+                return;
+            nativePushView();
+            dirty = false;
+            return;
+        }
         if (!dirty && !input.smokeOnce)
             return;
         const frame = renderFrame(toViewModel(state, {
@@ -621,6 +631,68 @@ export async function runTuiMenu(input) {
             stdout.write(`\n${note}\n`);
         return 0;
     }
+    // Primary path: native Ratatui shell when binary is available (WP_DASH_NATIVE=0 forces pure-ANSI).
+    const { shouldPreferNativeDashTui, resolveNativeDashTuiBinary } = await import("#cli/commands/dash/tui/native-path.js");
+    const nativeBinary = shouldPreferNativeDashTui() && !process.env["WP_DASH_FORCE_ANSI"]
+        ? resolveNativeDashTuiBinary()
+        : null;
+    if (nativeBinary) {
+        try {
+            const { runNativeTuiHost } = await import("#cli/commands/dash/tui/native-host.js");
+            process.stderr.write(`wp dash: native control-plane shell (${nativeBinary})\n`);
+            // Ensure agent list is loaded before first native frame when possible.
+            state = { ...state, loading: false };
+            const code = await runNativeTuiHost({
+                binaryPath: nativeBinary,
+                repoLabel: input.repoLabel,
+                getState: () => state,
+                setState: (next) => {
+                    state = next;
+                },
+                onBridge: (bridge) => {
+                    nativePushView = bridge.pushView;
+                },
+                handlers: {
+                    onEffect: (effect) => {
+                        // Match pure-ANSI: repaint after async effects settle so launch /
+                        // browser / status mutations reach the native shell without waiting
+                        // for the next key or timer tick.
+                        void enqueueEffects([effect]).then(() => {
+                            if (!shuttingDown)
+                                paint();
+                        });
+                    },
+                    onQuit: () => {
+                        shuttingDown = true;
+                        running = false;
+                        coordinator.discardPending();
+                    },
+                },
+            });
+            nativePushView = null;
+            if (code !== 0) {
+                throw new Error(`native shell exited with code ${code}`);
+            }
+            shuttingDown = true;
+            running = false;
+            coordinator.discardPending();
+            clearInterval(usageTimer);
+            clearInterval(ultragoalTimer);
+            clearInterval(statusTimer);
+            stopObservingLayout?.();
+            const note = await controller?.dispose();
+            await effectQueue.catch(() => {
+                /* best-effort drain after dispose */
+            });
+            if (note)
+                stdout.write(`\n${note}\n`);
+            return code;
+        }
+        catch (error) {
+            nativePushView = null;
+            process.stderr.write(`wp dash: native shell failed (${error instanceof Error ? error.message : String(error)}); falling back to pure-ANSI\n`);
+        }
+    }
     const wasRaw = stdin.isRaw;
     if (typeof stdin.setRawMode === "function")
         stdin.setRawMode(true);

package/dist/esm/cli/commands/init/scaffolders/agent-kit-global/index.js

@@ -26,7 +26,7 @@ import { spawnSync } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { buildVpGlobalInstallCommand, confirmInstalledGlobally, PUBLIC_PACKAGE_NAME, resolveBundledVpCommand, } from "#cli/auto-update/detect-pm.js";
-import { buildSelfInvocationCommand } from "#cli/commands/self-install-guard.js";
+import { buildSelfInvocationCommand } from "#cli/auto-update/self-invocation.js";
 import { findAgentKitPackageRoot, resolveAgentKitPackageRoot, } from "#cli/commands/init/package-root";
 import { makeNoopSpinnerFactory, } from "#cli/commands/init/scaffolders/spinner";
 import { UPDATE_CACHE_FILENAME, readFreshCachedLatestVersion } from "#cli/auto-update/cache.js";

package/dist/esm/cli/commands/package-manager.js

@@ -7,7 +7,8 @@ import { readToolingOwnershipState, tryReadRepoKey, writeToolingOwnershipState,
 import { resolveGlobalCapableVpCommand } from "#cli/global-vp.js";
 import { UPDATE_CACHE_FILENAME, formatStaleAgentKitVersionWarning, reconcileUpdateNotifierCache, } from "#cli/auto-update/cache.js";
 import { buildVpGlobalUpdateCommand, resolveBundledVpCommand } from "#cli/auto-update/detect-pm.js";
-import { GUARD_EXIT_CHILD_FAILED, GUARD_EXIT_LEASE_HELD, GUARD_EXIT_OWNERSHIP_LOST, GUARD_EXIT_UNRESOLVABLE, buildSelfInvocationCommand, } from "#cli/commands/self-install-guard.js";
+import { buildSelfInvocationCommand } from "#cli/auto-update/self-invocation.js";
+import { GUARD_EXIT_CHILD_FAILED, GUARD_EXIT_LEASE_HELD, GUARD_EXIT_OWNERSHIP_LOST, GUARD_EXIT_UNRESOLVABLE, } from "#cli/commands/self-install-guard.js";
 import { readPackageVersion } from "#cli/utils";
 import { resolveFreshAgentKitPackageRoot } from "#cli/commands/init/package-root";
 import { DEFAULT_PLUGIN_CACHE_PRUNE_HOSTS, pruneOutdatedAgentKitPluginCaches, } from "#cli/commands/init/plugin-cache-prune.js";

package/dist/esm/cli/commands/quality-log-store.d.ts

@@ -10,6 +10,12 @@ export interface CliLogEntry {
     readonly summary?: string;
 }
 export declare function isCliLogCommandName(value: string): value is CliLogCommandName;
+/**
+ * Create a durable CLI log sink. When the preferred repo state surface is not
+ * writable (EPERM/EACCES/EROFS — common in Codex/read-only sandboxes), fall
+ * back to TMPDIR so `wp audit`/`wp test` still execute. The fallback is loud
+ * on stderr; it is not a silent swallow.
+ */
 export declare function createCliLogSink(command: CliLogCommandName, cwd?: string): CliLogSink;
 export interface CliLogSink {
     readonly command: CliLogCommandName;

package/dist/esm/cli/commands/quality-log-store.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { closeSync, createWriteStream, mkdirSync, openSync, readdirSync, readFileSync, statSync, renameSync, utimesSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { getSurfacePath } from "#paths/state-root.js";
 import { readTrustedJsonFile } from "#shared-utils/read-json-file.js";
@@ -18,9 +19,17 @@ const ORPHAN_LOG_GRACE_MS = 60_000;
 export function isCliLogCommandName(value) {
     return CLI_LOG_COMMANDS.includes(value);
 }
-export function createCliLogSink(command, cwd = process.cwd()) {
+function isUnwritableFsError(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return false;
+    const code = error.code;
+    return code === "EPERM" || code === "EACCES" || code === "EROFS";
+}
+/**
+ * Open a CLI log sink in an explicit directory (preferred state surface or fallback).
+ */
+function openCliLogSink(commandDir, command, cwd) {
     const id = createLogId();
-    const commandDir = getCommandLogDir(command, cwd);
     mkdirSync(commandDir, { recursive: true });
     const absoluteLogPath = join(commandDir, `${id}.log`);
     const activeMarkerPath = getActiveMarkerPath(absoluteLogPath);
@@ -80,7 +89,8 @@ export function createCliLogSink(command, cwd = process.cwd()) {
             };
             try {
                 markLogRecentlyFinalized(absoluteLogPath);
-                writeLogEntry(entry, cwd);
+                // Index/lock live next to the log file so fallback dirs stay consistent.
+                writeLogEntryInDir(entry, commandDir);
             }
             finally {
                 rmSync(activeMarkerPath, { force: true });
@@ -89,6 +99,28 @@ export function createCliLogSink(command, cwd = process.cwd()) {
         },
     };
 }
+/**
+ * Create a durable CLI log sink. When the preferred repo state surface is not
+ * writable (EPERM/EACCES/EROFS — common in Codex/read-only sandboxes), fall
+ * back to TMPDIR so `wp audit`/`wp test` still execute. The fallback is loud
+ * on stderr; it is not a silent swallow.
+ */
+export function createCliLogSink(command, cwd = process.cwd()) {
+    const preferredDir = getCommandLogDir(command, cwd);
+    try {
+        return openCliLogSink(preferredDir, command, cwd);
+    }
+    catch (error) {
+        if (!isUnwritableFsError(error))
+            throw error;
+        const fallbackDir = join(tmpdir(), "webpresso", "cli-logs", command);
+        const code = typeof error === "object" && error !== null && "code" in error
+            ? String(error.code)
+            : "unknown";
+        process.stderr.write(`wp: CLI log directory not writable (${preferredDir}): ${code}; using ${fallbackDir}\n`);
+        return openCliLogSink(fallbackDir, command, cwd);
+    }
+}
 export function readCliLogEntries(command, cwd = process.cwd()) {
     const indexPath = getCommandIndexPath(command, cwd);
     try {
@@ -104,11 +136,21 @@ export function readCliLogEntry(command, ordinal = 1, cwd = process.cwd()) {
         return;
     return readCliLogEntries(command, cwd)[ordinal - 1];
 }
-function writeLogEntry(entry, cwd) {
-    withCommandIndexLock(entry.command, cwd, () => {
-        const indexPath = getCommandIndexPath(entry.command, cwd);
+function readCliLogEntriesFromDir(commandDir) {
+    const indexPath = join(commandDir, "index.json");
+    try {
+        const parsed = readTrustedJsonFile(indexPath);
+        return Array.isArray(parsed.entries) ? parsed.entries : [];
+    }
+    catch {
+        return [];
+    }
+}
+function writeLogEntryInDir(entry, commandDir) {
+    withCommandIndexLockInDir(commandDir, () => {
+        const indexPath = join(commandDir, "index.json");
         mkdirSync(dirname(indexPath), { recursive: true });
-        const currentEntries = readCliLogEntries(entry.command, cwd).filter((current) => current.id !== entry.id);
+        const currentEntries = readCliLogEntriesFromDir(commandDir).filter((current) => current.id !== entry.id);
         const nextEntries = [entry, ...currentEntries].slice(0, 10);
         const retainedLogPaths = new Set(nextEntries.map((item) => item.logPath));
         for (const removed of currentEntries.slice(9)) {
@@ -116,7 +158,7 @@ function writeLogEntry(entry, cwd) {
                 rmSync(removed.logPath, { force: true });
             }
         }
-        pruneInactiveOrphanedLogFiles(entry.command, retainedLogPaths, cwd);
+        pruneInactiveOrphanedLogFilesInDir(commandDir, retainedLogPaths);
         const index = {
             version: 1,
             command: entry.command,
@@ -125,8 +167,7 @@ function writeLogEntry(entry, cwd) {
         writeIndexAtomically(indexPath, index);
     });
 }
-function withCommandIndexLock(command, cwd, fn) {
-    const commandDir = getCommandLogDir(command, cwd);
+function withCommandIndexLockInDir(commandDir, fn) {
     mkdirSync(commandDir, { recursive: true });
     const lockPath = join(commandDir, "index.lock");
     const started = Date.now();
@@ -157,13 +198,12 @@ function writeIndexAtomically(indexPath, index) {
     writeJsonFile(tmpPath, index);
     renameSync(tmpPath, indexPath);
 }
-function pruneInactiveOrphanedLogFiles(command, retainedLogPaths, cwd) {
-    const directory = getCommandLogDir(command, cwd);
-    mkdirSync(directory, { recursive: true });
-    for (const file of readdirSync(directory)) {
+function pruneInactiveOrphanedLogFilesInDir(commandDir, retainedLogPaths) {
+    mkdirSync(commandDir, { recursive: true });
+    for (const file of readdirSync(commandDir)) {
         if (!file.endsWith(".log"))
             continue;
-        const absolutePath = join(directory, file);
+        const absolutePath = join(commandDir, file);
         if (!retainedLogPaths.has(absolutePath) && canPruneLogPath(absolutePath)) {
             rmSync(absolutePath, { force: true });
         }

package/dist/esm/cli/commands/self-install-guard.d.ts

@@ -30,13 +30,17 @@
  *      chain unresolvable after repair; 12 lease held; 13 ownership lost.
  *   7. Release the lease owner-checked in a finally.
  *
- * Post-swap import rule: the child `vp update -g @webpresso/agent-kit` may
- * delete this process's on-disk package tree (old installId) before probe/
- * repair run. Post-child helpers MUST be static imports loaded at process
- * start — never `await import("#cli/…")` after the child exits, or Node
- * re-resolves against a removed path (`Cannot find module …/global-vp.js`).
- * Probe/repair logic itself reads the vite-plus store SSOT + PATH, not this
- * process's dying package root.
+ * Survival layers (in-repo SOTA bar):
+ * 1. Prefer a **stable** non-versioned launcher when re-execing the guard
+ *    (`#cli/auto-update/self-invocation.js`) — primary defense.
+ * 2. Self-package helpers (probe, repair, tombstone) MUST be static imports
+ *    loaded at process start — never package-local dynamic import, or Node
+ *    re-resolves against a removed installId path after `vp update -g`.
+ * 3. Argument builders depend on cycle-free leaves (self-invocation,
+ *    guard-tombstone), never on this command module solely for argv.
+ *
+ * Probe/repair reads the vite-plus store SSOT + PATH, not this process's
+ * dying package root.
  *
  * Custody boundary (stated exactly, mirrored from install-lock.ts): a stale,
  * OS-suspended holder whose child completes a mutation AFTER the successor
@@ -45,6 +49,9 @@
  * resource-side fencing.
  */
 import type { CAC } from "cac";
+import { buildSelfInvocationCommand, isVersionedAgentKitPayloadPath, resolveStableWpLauncher } from "#cli/auto-update/self-invocation.js";
+/** Re-export leaf helpers for public ergonomics / existing imports. */
+export { buildSelfInvocationCommand, isVersionedAgentKitPayloadPath, resolveStableWpLauncher };
 export declare function registerSelfInstallGuardCommand(cli: CAC): void;
 export declare const GUARD_EXIT_CHILD_FAILED = 10;
 export declare const GUARD_EXIT_UNRESOLVABLE = 11;
@@ -85,12 +92,3 @@ export interface SelfInstallGuardDeps {
  * Testable core. The CLI action wires `process.exit(await runSelfInstallGuard(...))`.
  */
 export declare function runSelfInstallGuard(rawArgs: readonly string[], deps?: SelfInstallGuardDeps): Promise<number>;
-/**
- * How wp re-invokes itself: the bun-compiled binary IS process.execPath (its
- * argv[1] is a virtual /$bunfs path), while the source/dev lane runs
- * `<runtime> <script>`.
- */
-export declare function buildSelfInvocationCommand(args: readonly string[], options?: {
-    readonly execPath?: string;
-    readonly argv1?: string;
-}): string[];