@webpresso/agent-kit 3.2.0 → 3.3.0

package/dist/esm/cli/commands/opencode-rotate.d.ts

@@ -31,6 +31,23 @@ export interface OpencodeRotateDeps {
     readonly materializeGlobalOpencodeAuth?: (key: string) => void;
     readonly recordCooldown?: (canonicalId: string) => Promise<unknown>;
 }
+/**
+ * Cooldown to record when an account is known to be capped but the real reset
+ * window is unknown: it assumes the shortest real OpenCode Go window (5 hours).
+ *
+ * A manual `--wp-rotate` has no provider response at all, so it always lands
+ * here. The launch-time health probe (`#cli/commands/opencode-probe.js`) uses it
+ * only as a fallback, because that path *does* have a provider response and
+ * normally records the true parsed window instead.
+ *
+ * Recording no window at all would leave the record permanently suppressed —
+ * `suppressionExpired` only clears a record that carries `retryAfterMs` — so
+ * every rotated account would be cooled forever and selection would degrade to
+ * "first account" again. A too-short guess is self-correcting: the account is
+ * retried, and if it is still capped the gate (or the next probe/rotation)
+ * simply cools it again.
+ */
+export declare const OPENCODE_UNKNOWN_LIMIT_COOLDOWN_MS: number;
 /**
  * Cool the currently-materialized opencode-go account and materialize the next
  * usable one into the global `auth.json`.
@@ -45,5 +62,11 @@ export interface OpencodeRotateDeps {
  * Never throws: the caller launches the TUI regardless of the outcome.
  */
 export declare function rotateActiveOpencodeAccount(cwd: string, secretProfile: string, deps?: OpencodeRotateDeps): Promise<OpencodeRotateOutcome>;
+/**
+ * Render a cooldown remainder as a short ` (resets in ~Xd)` suffix, or the empty
+ * string when the window is unknown. Shared with the launch-time health probe so
+ * rotation and probe output cannot drift apart.
+ */
+export declare function formatOpencodeResetWait(waitMs: number | undefined): string;
 /** Human-readable lines describing a rotation outcome, in print order. */
 export declare function describeOpencodeRotate(outcome: OpencodeRotateOutcome): readonly string[];

package/dist/esm/cli/commands/opencode-rotate.js

@@ -5,15 +5,22 @@ import { resolveOpencodeAccountsGracefully } from "#runtime/opencode-account-mat
 /** The `--wp-rotate` flag, namespaced like `--wp-permission-mode`. */
 export const OPENCODE_ROTATE_FLAG = "--wp-rotate";
 /**
- * A manual rotation has no provider response to parse a reset window from, so it
- * assumes the shortest real OpenCode Go window (5 hours). Recording no window at
- * all would leave the record permanently suppressed — `suppressionExpired` only
- * clears a record that carries `retryAfterMs` — so every rotated account would
- * be cooled forever and selection would degrade to "first account" again. A
- * too-short guess is self-correcting: the account is retried, and if it is still
- * capped the gate (or the next rotation) simply cools it again.
+ * Cooldown to record when an account is known to be capped but the real reset
+ * window is unknown: it assumes the shortest real OpenCode Go window (5 hours).
+ *
+ * A manual `--wp-rotate` has no provider response at all, so it always lands
+ * here. The launch-time health probe (`#cli/commands/opencode-probe.js`) uses it
+ * only as a fallback, because that path *does* have a provider response and
+ * normally records the true parsed window instead.
+ *
+ * Recording no window at all would leave the record permanently suppressed —
+ * `suppressionExpired` only clears a record that carries `retryAfterMs` — so
+ * every rotated account would be cooled forever and selection would degrade to
+ * "first account" again. A too-short guess is self-correcting: the account is
+ * retried, and if it is still capped the gate (or the next probe/rotation)
+ * simply cools it again.
  */
-const MANUAL_ROTATION_COOLDOWN_MS = 5 * 60 * 60 * 1_000;
+export const OPENCODE_UNKNOWN_LIMIT_COOLDOWN_MS = 5 * 60 * 60 * 1_000;
 function coolActiveAccount(canonicalId, deps) {
     if (deps.recordCooldown)
         return deps.recordCooldown(canonicalId);
@@ -23,7 +30,7 @@ function coolActiveAccount(canonicalId, deps) {
         failureCode: "opencode-go-usage-limit",
         terminalClassification: "provider-limit-reached",
         limitWindow: "unknown",
-        retryAfterMs: MANUAL_ROTATION_COOLDOWN_MS,
+        retryAfterMs: OPENCODE_UNKNOWN_LIMIT_COOLDOWN_MS,
     });
 }
 /**
@@ -97,7 +104,12 @@ async function rotateOrThrow(cwd, secretProfile, deps) {
         ...(next.waitMs === undefined ? {} : { waitMs: next.waitMs }),
     };
 }
-function formatWait(waitMs) {
+/**
+ * Render a cooldown remainder as a short ` (resets in ~Xd)` suffix, or the empty
+ * string when the window is unknown. Shared with the launch-time health probe so
+ * rotation and probe output cannot drift apart.
+ */
+export function formatOpencodeResetWait(waitMs) {
     if (waitMs === undefined)
         return "";
     const hours = waitMs / 3_600_000;
@@ -127,7 +139,7 @@ export function describeOpencodeRotate(outcome) {
                 `wp opencode: now active -> opencode-go:${outcome.activeAccountId}`,
             ];
             if (outcome.activeIsCooled) {
-                lines.push(`wp opencode: every account is within its cooldown; using the soonest-expiring one${formatWait(outcome.waitMs)}. Run again after it resets, or add another OPENCODE_GO_KEY_<ID>.`);
+                lines.push(`wp opencode: every account is within its cooldown; using the soonest-expiring one${formatOpencodeResetWait(outcome.waitMs)}. Run again after it resets, or add another OPENCODE_GO_KEY_<ID>.`);
             }
             return lines;
         }

package/dist/esm/cli/commands/quality-runner.js

@@ -147,9 +147,9 @@ function renderSummaryLines(summary, transformed, entry, passed) {
     }
     if (!passed || transformed.truncated) {
         lines.push(`Full log: wp logs ${entry.command}`);
-    }
-    if (transformed.elisions && transformed.elisions.length > 0) {
-        lines.push(...transformed.elisions.map((elision) => `Retrieve elision: ${elision.retrieveTool} id=${elision.id}`));
+        if (transformed.elisions && transformed.elisions.length > 0) {
+            lines.push(...transformed.elisions.map((elision) => `Retrieve elision: ${elision.retrieveTool} id=${elision.id}`));
+        }
     }
     if (transformed.warnings && transformed.warnings.length > 0) {
         lines.push(...transformed.warnings.map((warning) => `Warning: ${warning}`));

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

@@ -1853,9 +1853,22 @@ function rejectedReviewSubjects(input) {
             !isFormalGateRejection(event)) {
             continue;
         }
-        const canonical = input.purpose === "plan"
-            ? createPlanSubjectAtRef(input.projectRoot, event.reviewedCommit, input.stableSlug)
-            : createDeliverySubjectAtRef(input.projectRoot, event.reviewedCommit, input.stableSlug);
+        // A recorded rejection's `reviewedCommit` can be orphaned by a later rebase.
+        // Rebuilding its subject then throws, and this loop had no guard, so the
+        // failure propagated to the caller and took down the whole rejection
+        // lineage. Skip only the unrebuildable event: the remaining rejections still
+        // count toward the scope-exhaustion circuit breaker, which is the
+        // fail-closed direction.
+        let canonical;
+        try {
+            canonical =
+                input.purpose === "plan"
+                    ? createPlanSubjectAtRef(input.projectRoot, event.reviewedCommit, input.stableSlug)
+                    : createDeliverySubjectAtRef(input.projectRoot, event.reviewedCommit, input.stableSlug);
+        }
+        catch {
+            continue;
+        }
         if (!bySubject.has(canonical.digest)) {
             bySubject.set(canonical.digest, {
                 artifactPath: event.artifactPath,
@@ -2356,14 +2369,21 @@ export async function runReviewGate(projectRoot, slug, input, dependencies = { i
                             }
                             break;
                         }
+                        // OpenCode family-wide stop: `isProviderWideOpenCodeGateResult`
+                        // is exactly `reviewer === "opencode"`, so the final branch below
+                        // already covers provider-limit-reached for that case. Keep the
+                        // provider-limit break only for non-opencode providers here.
                         if (providerResult.terminalClassification === "provider-limit-reached" &&
-                            (provider !== "opencode" || isProviderWideOpenCodeGateResult(providerResult))) {
+                            provider !== "opencode") {
                             break;
                         }
                         if ((provider === "claude" || provider === "codex") &&
                             providerResult.status === "complete")
                             break;
-                        if (provider === "opencode" && providerResult.reviewer === "opencode")
+                        // Also stops the opencode family on any result from the
+                        // family-agnostic "opencode" reviewer (complete, limit, or
+                        // other failure) once per-account failover has already run.
+                        if (provider === "opencode" && isProviderWideOpenCodeGateResult(providerResult))
                             break;
                     }
                 }
@@ -2779,6 +2799,8 @@ export function registerReviewCommand(cli, deps = {}) {
                 const slug = args[0];
                 if (!slug)
                     throw new Error("Usage: wp review gate <blueprint-slug> [--purpose plan|delivery] [--target <git-ref>] [--provider claude|codex|opencode|grok] [--model <model-id>] [--effort medium|high] [--resume <gate-id>] [--json]");
+                if (options.targetId !== undefined || options.targetKind !== undefined)
+                    throw new Error("wp review gate does not accept --target-id/--target-kind: the blueprint slug is positional (wp review gate <blueprint-slug>). --target-id/--target-kind apply only to `wp review log`.");
                 const interrupt = createReviewInterruptScope();
                 try {
                     const result = await runReviewGate(projectRoot, slug, options, {

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/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,7 +2,7 @@
  * `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";
@@ -17,6 +17,7 @@ import { projectWorktreeAgentSurfaces } from "#worktrees/project-agent-surfaces.
 import { assertNotLocalMainBranch } from "#worktrees/main-ownership.js";
 import { buildWorktreeInventory, canonicalizeWorktreePath, classifyMembership, isManagedWorktreePath, resolveRepoIdentity, } from "#worktrees/identity.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;
@@ -567,6 +568,113 @@ function currentBranch(repoRoot) {
     });
     return result.status === 0 ? String(result.stdout ?? "").trim() : "";
 }
+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);
@@ -670,6 +778,10 @@ export async function executeWorktreeSubcommand(subcommand, args, opts) {
             handleRefresh(opts);
             return;
         case "prune":
+            if (opts.orphans) {
+                await handlePruneOrphans(opts);
+                return;
+            }
             await handlePrune(opts);
             return;
         case "migrate":

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/hooks/doctor.d.ts

@@ -118,6 +118,8 @@ export declare function checkCodexConfigKeys(configFilePath?: string, deps?: Hos
 export declare function checkProjectMcpPins(cwd?: string, deps?: HostConfigDoctorDeps): DoctorCheck;
 export interface ClaudeMcpDuplicateRegistrationOptions {
     readonly home?: string;
+    /** Project root used to discover a project-local `.mcp.json` registration. */
+    readonly projectRoot?: string;
     readonly exists?: (path: string) => boolean;
     readonly readFile?: (path: string) => string;
 }

package/dist/esm/hooks/doctor.js

@@ -1838,6 +1838,29 @@ export function checkClaudeMcpDuplicateRegistration(options = {}) {
             manualSources.push(`project scope ${projectDir}`);
         }
     }
+    // Also scan project-local `.mcp.json` (and ancestors). Claude Code honors
+    // this file as a third registration surface; the home JSON projects map
+    // does not always mirror it, so a plugin + project-file pair still doubles
+    // the tool list without the home-JSON check ever firing.
+    const projectRoot = options.projectRoot ?? process.cwd();
+    for (const candidate of collectProjectMcpJsonCandidates(projectRoot)) {
+        if (!exists(candidate))
+            continue;
+        try {
+            const projectParsed = JSON.parse(readFile(candidate));
+            if (projectParsed !== null &&
+                typeof projectParsed === "object" &&
+                "mcpServers" in projectParsed &&
+                projectParsed.mcpServers &&
+                "webpresso" in
+                    (projectParsed.mcpServers ?? {})) {
+                manualSources.push(`project file ${candidate}`);
+            }
+        }
+        catch {
+            // Unreadable/malformed .mcp.json is not a duplicate signal — degrade.
+        }
+    }
     if (manualSources.length === 0) {
         return { name, ok: true, detail: "plugin-scoped registration only" };
     }
@@ -1851,6 +1874,19 @@ export function checkClaudeMcpDuplicateRegistration(options = {}) {
             `claude mcp remove webpresso (run inside the project directory for project-scope entries).`,
     };
 }
+/** Walk projectRoot → filesystem root collecting `.mcp.json` paths that may register MCP servers. */
+function collectProjectMcpJsonCandidates(projectRoot) {
+    const candidates = [];
+    let current = projectRoot;
+    for (;;) {
+        candidates.push(join(current, ".mcp.json"));
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return candidates;
+}
 const QUOTED_TOML_STRING = /"((?:[^"\\]|\\.)*)"/gu;
 const DANGLING_SYMLINK_SCAN_DEPTH = 3;
 function collectDanglingWorktreePaths(raw, worktreesRoot, exists, alreadyReported) {
@@ -2055,7 +2091,7 @@ export async function runHooksDoctor(opts = {}) {
         checks.push(checkCodexConfigKeys());
     }
     checks.push(checkProjectMcpPins(opts.cwd));
-    checks.push(checkClaudeMcpDuplicateRegistration());
+    checks.push(checkClaudeMcpDuplicateRegistration({ projectRoot: opts.cwd ?? process.cwd() }));
     checks.push({ advisory: true, ...checkDanglingHostPaths() });
     checks.push({ advisory: true, ...checkRootLauncherContract() });
     checks.push({ advisory: true, ...checkNativePluginRuntime() });