@webpresso/agent-kit 3.1.30 → 3.3.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/rust-check.d.ts

@@ -0,0 +1,24 @@
+import type { CAC } from "cac";
+import type { AffectedResolutionDeps } from "#git/affected";
+/**
+ * `wp rust-check` — the Rust counterpart of `wp typecheck`/`wp test`: proves
+ * an affected tracked Rust crate still compiles and passes its tests.
+ *
+ * Exists because `wp ci-preflight`'s other stages only resolve TS/JS
+ * affectedness, so a Rust-only branch previously reported every stage as
+ * "no affected files" and exited green without ever invoking `cargo` — a
+ * silent false pass (see `catalog/agent/rules/ci-cost-local-first.md`).
+ * This command always prints an explicit status line, whether or not it
+ * found Rust crates to check, so "green" is never ambiguous.
+ */
+export declare const RUST_CHECK_COMMAND_HELP: string;
+interface RustCheckCommandDeps {
+    readonly getGitTopLevel?: AffectedResolutionDeps["getGitTopLevel"];
+    readonly getStagedFiles?: AffectedResolutionDeps["getStagedFiles"];
+    readonly getBranchChangedFiles?: AffectedResolutionDeps["getBranchChangedFiles"];
+    readonly runCargo?: (args: readonly string[], cwd: string) => {
+        readonly exitCode: number;
+    };
+}
+export declare function registerRustCheckCommand(cli: CAC, deps?: RustCheckCommandDeps): void;
+export {};

package/dist/esm/cli/commands/rust-check.js

@@ -0,0 +1,110 @@
+import { spawnSync } from "node:child_process";
+import { addAffectedOptions, resolveAffectedTargets } from "#git/affected";
+import { resolveAffectedRustManifests, trackedCrateForManifest } from "#rust/affected-manifests";
+/**
+ * `wp rust-check` — the Rust counterpart of `wp typecheck`/`wp test`: proves
+ * an affected tracked Rust crate still compiles and passes its tests.
+ *
+ * Exists because `wp ci-preflight`'s other stages only resolve TS/JS
+ * affectedness, so a Rust-only branch previously reported every stage as
+ * "no affected files" and exited green without ever invoking `cargo` — a
+ * silent false pass (see `catalog/agent/rules/ci-cost-local-first.md`).
+ * This command always prints an explicit status line, whether or not it
+ * found Rust crates to check, so "green" is never ambiguous.
+ */
+export const RUST_CHECK_COMMAND_HELP = [
+    "Prove affected tracked Rust crates compile and pass tests (cargo check + cargo test).",
+    "",
+    "Examples:",
+    "  wp rust-check --affected              # staged changed files → owning crate(s)",
+    "  wp rust-check --affected --branch     # changed vs origin/${GITHUB_BASE_REF:-main}",
+    "",
+    "Tracked crates: native/session-memory-engine, native/dash-tui,",
+    "apps/desktop/src-tauri. spikes/** crates are intentionally excluded — no CI",
+    "workflow builds or tests them today.",
+].join("\n");
+export function registerRustCheckCommand(cli, deps = {}) {
+    addAffectedOptions(cli.command("rust-check", RUST_CHECK_COMMAND_HELP)).action(async (flags) => {
+        const affected = Boolean(flags.affected);
+        const branch = Boolean(flags.branch);
+        const cwd = process.cwd();
+        if (!affected && !branch) {
+            console.error("wp rust-check requires --affected (optionally with --branch).");
+            return 1;
+        }
+        const resolution = resolveAffectedTargets({
+            commandName: "rust-check",
+            cwd,
+            affected,
+            branch,
+            policy: "fail-closed",
+            mapChangedFiles: resolveAffectedRustManifests,
+            emptyMessage: rustCheckEmptyMessage,
+            degradedFallbackMessage: rustCheckDegradedMessage,
+            degradedFailClosedMessage: rustCheckDegradedMessage,
+        }, deps);
+        if (resolution.kind === "invalid") {
+            console.error(resolution.message);
+            return 1;
+        }
+        if (resolution.kind === "degraded-fail-closed" || resolution.kind === "degraded-fallback") {
+            console.error(resolution.message);
+            return 1;
+        }
+        if (resolution.kind === "empty") {
+            console.log(resolution.message);
+            return 0;
+        }
+        if (resolution.kind === "disabled") {
+            // Unreachable: the --affected/--branch guard above always sets
+            // `affected: true` before calling resolveAffectedTargets. Handled
+            // for exhaustiveness only.
+            console.error("wp rust-check requires --affected (optionally with --branch).");
+            return 1;
+        }
+        const manifests = resolution.targets;
+        console.log(`wp rust-check: ${manifests.length} tracked Rust crate(s) affected: ${manifests.join(", ")}`);
+        const runCargo = deps.runCargo ?? defaultRunCargo;
+        for (const manifest of manifests) {
+            const crate = trackedCrateForManifest(manifest);
+            if (!crate) {
+                console.error(`wp rust-check: no tracked crate metadata for ${manifest}.`);
+                return 1;
+            }
+            console.log(`wp rust-check: cargo check --manifest-path ${crate.manifest}`);
+            const checkResult = runCargo(["check", "--manifest-path", crate.manifest], resolution.cwd);
+            if (checkResult.exitCode !== 0) {
+                console.error(`wp rust-check: cargo check failed for ${crate.manifest}.`);
+                return checkResult.exitCode;
+            }
+            console.log(`wp rust-check: cargo ${crate.testArgs.join(" ")}`);
+            const testResult = runCargo(crate.testArgs, resolution.cwd);
+            if (testResult.exitCode !== 0) {
+                console.error(`wp rust-check: cargo test failed for ${crate.manifest}.`);
+                return testResult.exitCode;
+            }
+        }
+        console.log(`wp rust-check: ${manifests.length} crate(s) passed: ${manifests.join(", ")}`);
+        return 0;
+    });
+}
+function rustCheckEmptyMessage(scope) {
+    const suffix = scope === "branch" ? "changed vs base ref" : "staged";
+    return (`wp rust-check: 0 tracked Rust crates affected (no ${suffix} files under ` +
+        "native/session-memory-engine, native/dash-tui, or apps/desktop/src-tauri; " +
+        "spikes/** Rust changes, if any, are intentionally not gated) — skipping cargo.");
+}
+function rustCheckDegradedMessage(reason) {
+    return `Unable to determine affected Rust files (${reason}); refusing to skip cargo verification.`;
+}
+function defaultRunCargo(args, cwd) {
+    const result = spawnSync("cargo", args, { cwd, stdio: "inherit" });
+    if (result.error) {
+        const isMissingBinary = result.error.code === "ENOENT";
+        console.error(isMissingBinary
+            ? "wp rust-check: cargo not found on PATH; install the Rust toolchain (https://rustup.rs) to verify Rust changes."
+            : `wp rust-check: ${result.error.message}`);
+        return { exitCode: 1 };
+    }
+    return { exitCode: typeof result.status === "number" ? result.status : 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/typecheck.d.ts

@@ -6,6 +6,7 @@ export interface TypecheckOptions {
     readonly cwd?: string;
     readonly files?: readonly string[];
     readonly packages?: readonly string[];
+    readonly tests?: boolean;
 }
 interface TypecheckCommandDeps {
     readonly getGitTopLevel?: AffectedResolutionDeps["getGitTopLevel"];

package/dist/esm/cli/commands/typecheck.js

@@ -23,6 +23,8 @@ export const TYPECHECK_COMMAND_HELP = [
     "  wp typecheck --affected              # staged changed source → reverse-importer closure",
     "  wp typecheck --affected --branch     # changed vs origin/${GITHUB_BASE_REF:-main}",
     "  wp typecheck --pretty",
+    "  wp typecheck --tests                 # test-surface lane (tsconfig.test.json); required in",
+    "                                        # not part of the default gate or ci-preflight yet",
 ].join("\n");
 export function registerTypecheckCommand(cli, deps = {}) {
     addAffectedOptions(cli
@@ -31,6 +33,7 @@ export function registerTypecheckCommand(cli, deps = {}) {
         .option("--package <name>", "Run the owning-scope typecheck for an exact package.json name (repeatable)"))
         .option("--pretty", "Keep TypeScript pretty output enabled")
         .option("--full", "Print the full raw output instead of the default summary-first view")
+        .option("--tests", "Run the test-surface lane (tsconfig.test.json); required by ci-preflight and CI")
         .action(async (targetsOrFlags, maybeFlags) => {
         const positionalTargets = Array.isArray(targetsOrFlags)
             ? targetsOrFlags.filter((target) => typeof target === "string")
@@ -45,9 +48,29 @@ export function registerTypecheckCommand(cli, deps = {}) {
         const packages = toArray(flags.package);
         const affected = Boolean(flags.affected);
         const branch = Boolean(flags.branch);
+        const tests = Boolean(flags.tests);
         const cwd = process.cwd();
         let files = explicitFiles;
         let executionCwd = cwd;
+        if (tests && (affected || branch || explicitFiles.length > 0 || packages.length > 0)) {
+            console.error("--tests cannot be combined with --affected, --branch, --file, or --package.");
+            return 1;
+        }
+        if (tests) {
+            const result = await runTypecheckCommand({
+                pretty: Boolean(flags.pretty),
+                tests: true,
+                cwd,
+            });
+            emitCliCommandOutput({
+                entry: result.entry,
+                summary: result.entry.summary ?? "",
+                passed: result.exitCode === 0,
+                full: Boolean(flags.full),
+                toolName: "wp_typecheck",
+            });
+            return result.exitCode;
+        }
         if (affected || branch) {
             const resolution = resolveAffectedTargets({
                 commandName: "typecheck",
@@ -131,9 +154,14 @@ export async function runTypecheckCommand(options = {}) {
         options.packages.length > 0) {
         throw new Error("Cannot use both --file and --package for typecheck targeting.");
     }
+    if (options.tests && ((options.files?.length ?? 0) > 0 || (options.packages?.length ?? 0) > 0)) {
+        throw new Error("Cannot use --tests together with --file or --package.");
+    }
     const cwd = options.cwd ?? process.cwd();
     repairCurrentManagedWorktreeDependencies(cwd);
-    const targeted = (options.files?.length ?? 0) > 0 || (options.packages?.length ?? 0) > 0;
+    const targeted = (options.files?.length ?? 0) > 0 ||
+        (options.packages?.length ?? 0) > 0 ||
+        Boolean(options.tests);
     const repoRoot = resolveProjectRoot({ cwd });
     const plan = targeted
         ? planTypecheckExecution({
@@ -141,6 +169,7 @@ export async function runTypecheckCommand(options = {}) {
             defaultScopeRoot: cwd,
             files: options.files,
             packages: options.packages,
+            tests: options.tests,
             pretty: options.pretty,
         })
         : {

package/dist/esm/cli/commands/worktree/router-dispatch.d.ts

@@ -14,6 +14,12 @@ export interface WorktreeCommandOptions {
     deps?: WorktreeDependencyHydration;
     cwd?: string;
     repo?: string;
+    /** `prune` only: filesystem-level orphan sweep instead of registry-only prune. */
+    orphans?: boolean;
+    /** `prune --orphans` only: scope the sweep to one repo namespace. */
+    repoId?: string;
+    /** `prune --orphans` only: alias for `--force` (execute the removal plan). */
+    yes?: boolean;
 }
 export interface WorktreeEntry {
     path: string;

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

@@ -2,9 +2,10 @@
  * `wp worktree` subcommand dispatch.
  */
 import { execFileSync, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync } 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,8 @@ 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";
+import { buildRegistryRepoRootMap, classifyOrphanCandidate, discoverOrphanScanCandidates, resolveRepoRootFromGitPointer, } from "#worktrees/orphan-scan.js";
 function parseDepsOption(value) {
     if (value === undefined || value === null || value === "")
         return undefined;
@@ -443,7 +445,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 +453,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 +531,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 +552,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 +568,114 @@ function currentBranch(repoRoot) {
     });
     return result.status === 0 ? String(result.stdout ?? "").trim() : "";
 }
-function handleMergeCleanup(nameOrPath, opts) {
+function formatOrphanScanBytes(bytes) {
+    if (bytes === "unknown")
+        return "-";
+    if (bytes < 1024)
+        return `${bytes}B`;
+    const units = ["K", "M", "G", "T"];
+    let value = bytes / 1024;
+    let unitIndex = 0;
+    while (value >= 1024 && unitIndex < units.length - 1) {
+        value /= 1024;
+        unitIndex += 1;
+    }
+    return `${value.toFixed(1)}${units[unitIndex]}`;
+}
+function summarizeOrphanScanRows(rows) {
+    const counts = new Map();
+    for (const row of rows)
+        counts.set(row.classification, (counts.get(row.classification) ?? 0) + 1);
+    const removable = rows.filter((row) => row.removable).length;
+    const parts = [...counts.entries()].map(([classification, count]) => `${classification}=${count}`);
+    return `${parts.join(", ")}, removable=${removable}`;
+}
+function printOrphanScanTable(rows) {
+    if (rows.length === 0) {
+        console.log("No candidate directories found under managed worktree roots.");
+        return;
+    }
+    console.log(`${"PATH".padEnd(72)} ${"CLASS".padEnd(13)} ${"DIRTY".padEnd(8)} ${"SIZE".padEnd(7)} ${"RM".padEnd(4)} REASON`);
+    for (const row of rows) {
+        const dirty = row.dirty === "unknown" ? "unknown" : row.dirty ? "yes" : "no";
+        console.log(`${row.path.padEnd(72)} ${row.classification.padEnd(13)} ${dirty.padEnd(8)} ${formatOrphanScanBytes(row.sizeBytes).padEnd(7)} ${(row.removable ? "yes" : "no").padEnd(4)} ${row.reason}`);
+    }
+    console.log("");
+    console.log(`Summary: ${summarizeOrphanScanRows(rows)}`);
+}
+function resolveOrphanScanDeps() {
+    const registryMap = buildRegistryRepoRootMap(readWorktreeRegistry().entries);
+    const readGitPointer = (path) => {
+        try {
+            return readFileSync(path, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return {
+        resolveRepoRoot: (candidate) => registryMap.get(candidate.repoNamespace) ??
+            resolveRepoRootFromGitPointer(candidate.path, readGitPointer),
+        repoRootExists: existsSync,
+        buildInventory: buildWorktreeInventory,
+        probeDirty: (path) => {
+            const result = spawnSync("git", ["status", "--porcelain"], {
+                cwd: path,
+                encoding: "utf8",
+                timeout: 5000,
+            });
+            if (result.status !== 0)
+                return "unknown";
+            return String(result.stdout ?? "").trim().length > 0;
+        },
+        // Native `du` traverses in kernel/C code (no per-file V8 stat overhead),
+        // which is materially faster than the pure-JS walker at the scale a real
+        // managed-worktree tree reaches (hundreds of `node_modules` trees). This
+        // is only invoked for already-confirmed `orphan` candidates (see
+        // `finalizeRow` in orphan-scan.ts), so it never runs against `alive`
+        // worktrees. Bounded, non-retrying: a slow/failed probe throws and
+        // reports `sizeBytes: "unknown"` rather than blocking the scan.
+        measureSize: (path) => {
+            const result = spawnSync("du", ["-sk", path], { encoding: "utf8", timeout: 10000 });
+            if (result.status !== 0) {
+                throw new Error(`du -sk failed or timed out for ${path}`);
+            }
+            const kilobytes = Number.parseInt(String(result.stdout ?? "")
+                .trim()
+                .split(/\s+/u)[0] ?? "", 10);
+            if (Number.isNaN(kilobytes))
+                throw new Error(`du -sk produced unparseable output for ${path}`);
+            return kilobytes * 1024;
+        },
+    };
+}
+/**
+ * Filesystem-level orphan sweep: dry-run by DEFAULT, prints a classification
+ * table, and only removes directories (via `--force`/`--yes`) that are proven
+ * `orphan` (absent from their resolved primary repo's `git worktree list`)
+ * AND proven clean (`git status --porcelain` ran successfully with no
+ * output). `broken` and `unrecognized` rows are always report-only. See
+ * `#worktrees/orphan-scan.js` for the full classification contract.
+ */
+async function handlePruneOrphans(opts) {
+    const roots = resolveKnownManagedWorktreeRoots();
+    const candidates = discoverOrphanScanCandidates(roots, { repoNamespaceFilter: opts.repoId });
+    const deps = resolveOrphanScanDeps();
+    const rows = candidates.map((candidate) => classifyOrphanCandidate(candidate, deps));
+    printOrphanScanTable(rows);
+    if (!(opts.force === true || opts.yes === true)) {
+        console.log("");
+        console.log("Dry run only. Re-run with --force (or --yes) to remove the directories marked removable=yes.");
+        return;
+    }
+    const removable = rows.filter((row) => row.removable);
+    for (const row of removable) {
+        rmSync(row.path, { recursive: true, force: true });
+        console.log(`Removed ${row.path}`);
+    }
+    console.log(`Removed ${removable.length} orphan director${removable.length === 1 ? "y" : "ies"}.`);
+}
+async function handleMergeCleanup(nameOrPath, opts) {
     const cwd = opts.cwd ?? process.cwd();
     const callerRoot = resolveWorktreeRepoRoot(cwd);
     const entries = listEntries(callerRoot);
@@ -628,6 +740,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 +778,11 @@ export async function executeWorktreeSubcommand(subcommand, args, opts) {
             handleRefresh(opts);
             return;
         case "prune":
-            handlePrune(opts);
+            if (opts.orphans) {
+                await handlePruneOrphans(opts);
+                return;
+            }
+            await handlePrune(opts);
             return;
         case "migrate":
             handleMigrate(opts);
@@ -682,7 +799,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 +807,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/commands/worktree/router.js

@@ -8,6 +8,10 @@ const HELP_TEXT = [
     "  list [--all]                                  List repo or global managed worktrees",
     "  refresh [--all|--repo <dir>]                  Refresh managed registry from git",
     "  prune --all                                   Prune stale managed registry entries",
+    "  prune --orphans [--repo-id <id>] [--force|--yes]",
+    "                                                 Scan managed roots for on-disk dirs absent",
+    "                                                 from git worktree list; dry-run by default,",
+    "                                                 removes only proven-clean orphans with --force",
     "  migrate                                       Move legacy sibling _worktrees",
     "  adopt <blueprint-slug> <path>                 Claim existing checkout as owner",
     "  rebind <blueprint-slug> [--path <path>]       Repair owner metadata",
@@ -24,6 +28,9 @@ const HELP_TEXT = [
     "  --no-setup          Skip configured worktree.setup scripts (new only)",
     "  --force             Skip configured teardown scripts and force removal",
     "  --stash-primary     Stash dirty primary state and switch to the expected primary branch before merge-cleanup",
+    "  --orphans           Filesystem-level orphan sweep for prune (see prune --orphans above)",
+    "  --repo-id <id>      Scope prune --orphans to one repo namespace under repos/<id>",
+    "  --yes               Alias for --force (prune --orphans only)",
     "  --cwd <dir>         Repo root (default: process.cwd())",
 ].join("\n");
 export function registerWorktreeRouter(cli) {
@@ -40,6 +47,9 @@ export function registerWorktreeRouter(cli) {
         .option("--stash-primary", "Stash dirty primary state and switch to the expected primary branch before merge-cleanup")
         .option("--all", "Use global managed inventory where supported")
         .option("--repo <dir>", "Repo root for refresh/rebind (default: cwd)")
+        .option("--orphans", "Filesystem-level orphan sweep for prune (dry-run unless --force/--yes)")
+        .option("--repo-id <id>", "Scope prune --orphans to one repo namespace under repos/<id>")
+        .option("--yes", "Alias for --force (prune --orphans only)")
         .option("--cwd <dir>", "Repo root to operate from (default: process.cwd())")
         .action(async (subcommand, args, options) => {
         if (!subcommand) {

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;