@webpresso/agent-kit 3.1.30 → 3.3.0

package/dist/esm/test/worker-budget.d.ts

@@ -7,4 +7,10 @@ export interface VitestWorkerBudget {
     readonly subprocess: number;
 }
 export declare function parsePositiveInteger(value: string | undefined): number | undefined;
+/**
+ * Allocate one worker ceiling across concurrently running Vitest projects.
+ * Standalone project runs keep `computeVitestWorkerBudget`; only the supervisor
+ * uses this aggregate contract.
+ */
+export declare function computeConcurrentVitestWorkerBudget(options?: VitestWorkerBudgetOptions): VitestWorkerBudget;
 export declare function computeVitestWorkerBudget(options?: VitestWorkerBudgetOptions): VitestWorkerBudget;

package/dist/esm/test/worker-budget.js

@@ -9,12 +9,70 @@ function splitSharedBudget(totalWorkers) {
     if (totalWorkers <= 2) {
         return { unit: 1, subprocess: 1 };
     }
-    const unit = Math.max(1, Math.round(totalWorkers * (2 / 3)));
+    // Even split. The lanes carry near-equal total work (measured 2026-07-23 on
+    // an 8-core host: unit ≈320 worker-seconds, subprocess ≈266 — see
+    // docs/ci-test-perf.md), so the previous 2/3-unit skew starved the
+    // subprocess lane: its makespan, not unit's, bounded the whole run
+    // (subprocess lane >296s at 2 workers vs 168s at 4 on the same host).
+    // CI is unaffected — it pins WP_VITEST_MAX_WORKERS=2, taking the early
+    // return above.
+    const unit = Math.max(1, Math.round(totalWorkers / 2));
     return {
         unit,
         subprocess: Math.max(1, totalWorkers - unit),
     };
 }
+function readWorkerOverride(env, name) {
+    const raw = env[name];
+    if (raw === undefined)
+        return;
+    const parsed = parsePositiveInteger(raw);
+    if (parsed === undefined) {
+        throw new Error(`${name} must be a positive integer, got ${JSON.stringify(raw)}`);
+    }
+    return parsed;
+}
+/**
+ * Allocate one worker ceiling across concurrently running Vitest projects.
+ * Standalone project runs keep `computeVitestWorkerBudget`; only the supervisor
+ * uses this aggregate contract.
+ */
+export function computeConcurrentVitestWorkerBudget(options = {}) {
+    const env = options.env ?? process.env;
+    const sharedOverride = readWorkerOverride(env, "WP_VITEST_MAX_WORKERS");
+    const unitOverride = readWorkerOverride(env, "WP_VITEST_UNIT_MAX_WORKERS");
+    const subprocessOverride = readWorkerOverride(env, "WP_VITEST_SUBPROCESS_MAX_WORKERS");
+    if (sharedOverride === undefined &&
+        unitOverride !== undefined &&
+        subprocessOverride !== undefined) {
+        return { unit: unitOverride, subprocess: subprocessOverride };
+    }
+    const total = sharedOverride ?? (env.CI === "true" ? 2 : defaultSharedWorkers(options));
+    if (total < 2) {
+        throw new Error(`WP_VITEST_MAX_WORKERS must be at least 2 for concurrent projects, got ${total}`);
+    }
+    if (unitOverride !== undefined && subprocessOverride !== undefined) {
+        if (unitOverride + subprocessOverride > total) {
+            throw new Error(`Lane worker overrides (${unitOverride + subprocessOverride}) exceed aggregate worker budget ${total}`);
+        }
+        return { unit: unitOverride, subprocess: subprocessOverride };
+    }
+    if (unitOverride !== undefined) {
+        const subprocess = total - unitOverride;
+        if (subprocess < 1) {
+            throw new Error(`Unit worker override ${unitOverride} leaves no aggregate subprocess worker`);
+        }
+        return { unit: unitOverride, subprocess };
+    }
+    if (subprocessOverride !== undefined) {
+        const unit = total - subprocessOverride;
+        if (unit < 1) {
+            throw new Error(`Subprocess worker override ${subprocessOverride} leaves no aggregate unit worker`);
+        }
+        return { unit, subprocess: subprocessOverride };
+    }
+    return splitSharedBudget(total);
+}
 export function computeVitestWorkerBudget(options = {}) {
     const env = options.env ?? process.env;
     const sharedOverride = parsePositiveInteger(env.WP_VITEST_MAX_WORKERS);

package/dist/esm/test-helpers/global-setup.d.ts

@@ -1,3 +1,2 @@
 import type { TestProject } from "vitest/node";
-export declare function shouldPrepareDistForProject(projectName: string | undefined): boolean;
-export declare function setup(project?: Pick<TestProject, "name">): void;
+export declare function setup(project?: Pick<TestProject, "name">): Promise<void>;

package/dist/esm/test-helpers/global-setup.js

@@ -1,44 +1,91 @@
 import { execFileSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import lockfile from "proper-lockfile";
 import { syncSastRuleAssets } from "#build/sast-rule-assets.js";
+import { runFormat } from "#format/index.js";
 import { ensureHostRuntimeArtifactsForSerialTests } from "./runtime-binary-artifacts.js";
 const REPO_ROOT = process.cwd();
 const DIST_SENTINEL = join(REPO_ROOT, "dist", "esm", "index.js");
 const MIGRATION_SENTINEL = join(REPO_ROOT, "dist", "esm", "blueprint", "db", "migrations", "0001_seed.sql");
-const DIST_PREP_PROJECTS = new Set(["subprocess", "serial-subprocess"]);
-export function shouldPrepareDistForProject(projectName) {
-    return projectName !== undefined && DIST_PREP_PROJECTS.has(projectName);
-}
-// Build before subprocess workers fork — tshy's non-atomic package.json write races with bun subprocess reads in init.e2e.test.ts.
-// Unit-only runs should not pay this build/setup cost, and Vitest passes the selected TestProject to globalSetup.
-export function setup(project) {
-    syncSastRuleAssets(REPO_ROOT);
-    if (!shouldPrepareDistForProject(project?.name))
-        return;
-    let builtDist = false;
-    if (!existsSync(DIST_SENTINEL)) {
-        execFileSync("./node_modules/.bin/tshy", [], {
-            cwd: REPO_ROOT,
-            encoding: "utf8",
-            env: { ...process.env, HUSKY: "0" },
-        });
-        builtDist = true;
-    }
-    if (!existsSync(MIGRATION_SENTINEL)) {
-        execFileSync("bun", ["src/build/blueprint-migration-assets.ts"], {
-            cwd: REPO_ROOT,
-            encoding: "utf8",
-            env: { ...process.env, HUSKY: "0" },
-        });
+// Lock target lives outside dist/ (tshy rewrites dist/) and under the always-present, gitignored
+// node_modules/.cache so a concurrent test run cannot clobber it mid-build.
+const BUILD_LOCK_TARGET = join(REPO_ROOT, "node_modules", ".cache", "wp-test-setup");
+// Serialize the dist build across concurrent test runs sharing this checkout: tshy's non-atomic
+// dist/package.json writes corrupt each other if two runs build at once. proper-lockfile gives a
+// bounded wait plus native stale-owner recovery (a dead builder's lock is reclaimed after `stale`).
+// The retry budget spans well past a cold build so a second run waits rather than failing closed.
+async function withDistBuildLock(fn) {
+    mkdirSync(join(REPO_ROOT, "node_modules", ".cache"), { recursive: true });
+    const release = await lockfile.lock(BUILD_LOCK_TARGET, {
+        realpath: false,
+        stale: 120_000,
+        retries: { retries: 40, factor: 1.4, minTimeout: 200, maxTimeout: 5_000 },
+    });
+    try {
+        return await fn();
     }
-    if (builtDist) {
-        execFileSync("bun", ["src/build/normalize-tsconfig-json-exports.ts"], {
-            cwd: REPO_ROOT,
-            encoding: "utf8",
-            env: { ...process.env, HUSKY: "0" },
-        });
+    finally {
+        await release();
     }
+}
+// h-019: scripts/run-vitest-projects.ts spawns the "unit" and "subprocess" vitest projects as two
+// independent, unsynchronized child processes (Promise.all) — the same exposure exists for any two
+// `vitest run --project <name>` invocations that happen to share this checkout. tshy's package.json
+// write below is non-atomic (truncate+write, not write-temp+rename): a project whose setup() returned
+// without taking this lock could start reading package.json (module resolution, etc.) while a sibling
+// project's process was mid-tshy-write, observing a truncated/empty file (JSONError "File is empty").
+// Every project therefore passes through this SAME gate before its tests can start, whether or not
+// that project needs dist output for itself: whichever process reaches the lock first performs the
+// idempotent, re-checked-under-lock build; every other process blocks until that release, then finds
+// the sentinels already satisfied and returns immediately. In the steady state (dist/ already built)
+// this is a single existsSync check with no lock contention at all.
+async function ensureDistPrepared() {
+    // Fast path: nothing to build. Only pay the lock when a build artifact is actually missing.
+    if (existsSync(DIST_SENTINEL) && existsSync(MIGRATION_SENTINEL))
+        return;
+    await withDistBuildLock(async () => {
+        let builtDist = false;
+        // Re-check under the lock: another run may have completed the build while we waited.
+        if (!existsSync(DIST_SENTINEL)) {
+            execFileSync("./node_modules/.bin/tshy", [], {
+                cwd: REPO_ROOT,
+                encoding: "utf8",
+                env: { ...process.env, HUSKY: "0" },
+            });
+            builtDist = true;
+            // tshy rewrites package.json's exports with a trailing newline the repo formatter forbids
+            // (`.editorconfig [*.json] insert_final_newline = false`), which would leave a clean worktree
+            // dirty. The real `build` script (package.json `"build"`) restores it with `wp format --file
+            // package.json`; mirror that here in-process (runFormat spawns only `vp fmt`, avoiding a second
+            // cold CLI launch) so `wp test` never dirties package.json. See package-scripts.test.ts.
+            // Fail loudly if the restore does not succeed — a silent failure would ship a dirty package.json.
+            const restored = await runFormat({ files: ["package.json"], cwd: REPO_ROOT });
+            if (!restored.passed) {
+                throw new Error(`global-setup: could not restore package.json formatting after tshy (exit ${restored.exitCode})` +
+                    `${restored.spawnError ? `: ${restored.spawnError}` : ""}\n${restored.output}`);
+            }
+        }
+        if (!existsSync(MIGRATION_SENTINEL)) {
+            execFileSync("bun", ["src/build/blueprint-migration-assets.ts"], {
+                cwd: REPO_ROOT,
+                encoding: "utf8",
+                env: { ...process.env, HUSKY: "0" },
+            });
+        }
+        if (builtDist) {
+            execFileSync("bun", ["src/build/normalize-tsconfig-json-exports.ts"], {
+                cwd: REPO_ROOT,
+                encoding: "utf8",
+                env: { ...process.env, HUSKY: "0" },
+            });
+        }
+    });
+}
+// Vitest passes the selected TestProject to globalSetup, once per project process.
+export async function setup(project) {
+    syncSastRuleAssets(REPO_ROOT);
+    await ensureDistPrepared();
     if (project?.name === "serial-subprocess") {
         ensureHostRuntimeArtifactsForSerialTests({ rootDir: REPO_ROOT });
     }

package/dist/esm/typecheck/planner.d.ts

@@ -13,7 +13,7 @@ export interface PlannedTypecheckCommand {
 }
 export interface TypecheckExecutionPlan {
     readonly repoRoot: string;
-    readonly mode: "default" | "files" | "packages";
+    readonly mode: "default" | "files" | "packages" | "tests";
     readonly commands: readonly PlannedTypecheckCommand[];
     readonly resolvedScopes: readonly TypecheckScope[];
     readonly preambleLine?: string;
@@ -24,6 +24,14 @@ export interface PlanTypecheckExecutionOptions {
     readonly files?: readonly string[];
     readonly packages?: readonly string[];
     readonly pretty?: boolean;
+    /**
+     * Run the separate test-surface typecheck lane (`tsconfig.test.json`)
+     * instead of the default production-source lane. Mutually exclusive with
+     * `files`/`packages`. This lane is invoked via `wp typecheck --tests` and is
+     * it is not part of the default `wp typecheck` gate or `ci-preflight`
+     * until the test-surface error corpus is burned down to zero.
+     */
+    readonly tests?: boolean;
 }
 export declare function planTypecheckExecution(options: PlanTypecheckExecutionOptions): TypecheckExecutionPlan;
 export declare function formatResolvedScopesLine(scopes: readonly TypecheckScope[]): string;

package/dist/esm/typecheck/planner.js

@@ -3,6 +3,7 @@ import { isAbsolute, join, relative, resolve } from "node:path";
 import { getPackageScript, readPackageJson, isRecursiveWpScript } from "#cli/package-scripts.js";
 import { getWorkspacePackages } from "#quality-engine/target-resolver.js";
 import { getManagedRunner, resolveEffectiveRunnerRoot } from "#tool-runtime";
+const TEST_TSCONFIG_FILENAME = "tsconfig.test.json";
 const GENERATED_ROOT_PREFIXES = [".webpresso/generated"];
 const OUTPUT_SEGMENTS = new Set(["coverage", "dist", "node_modules"]);
 export function planTypecheckExecution(options) {
@@ -14,6 +15,17 @@ export function planTypecheckExecution(options) {
     if (files.length > 0 && packages.length > 0) {
         throw new Error("Cannot use both --file and --package for typecheck targeting.");
     }
+    if (options.tests) {
+        if (files.length > 0 || packages.length > 0) {
+            throw new Error("Cannot use --tests together with --file or --package.");
+        }
+        return {
+            repoRoot,
+            mode: "tests",
+            commands: [buildTestsCommand(defaultScopeRoot, options.pretty)],
+            resolvedScopes: [],
+        };
+    }
     if (packages.length > 0) {
         const scopes = resolvePackageScopes(repoRoot, realRepoRoot, packages);
         return {
@@ -63,6 +75,25 @@ function buildUntargetedCommand(cwd, pretty = false) {
         cwd,
     };
 }
+function buildTestsCommand(cwd, pretty = false) {
+    const testTsconfigPath = join(cwd, TEST_TSCONFIG_FILENAME);
+    if (!existsSync(testTsconfigPath)) {
+        throw new Error(`--tests requires ${TEST_TSCONFIG_FILENAME} at the repo root (not found at ${testTsconfigPath}).`);
+    }
+    const resolution = getManagedRunner("tsc");
+    return {
+        scope: null,
+        command: resolution.command,
+        args: [
+            ...resolution.args,
+            "--noEmit",
+            "-p",
+            TEST_TSCONFIG_FILENAME,
+            ...(pretty ? [] : ["--pretty", "false"]),
+        ],
+        cwd,
+    };
+}
 function buildTargetedCommand(scope, pretty = false) {
     const checkTypesScript = getPackageScript(scope.root, "check-types");
     if (checkTypesScript && !isRecursiveWpScript(checkTypesScript, "typecheck")) {

package/dist/esm/ultragoal/service.d.ts

@@ -70,6 +70,13 @@ export declare function decideUltragoalRun(input: {
     readonly currentSourceSnapshot?: string;
     readonly now?: Date;
 }): UltragoalRunDecision;
+/**
+ * Preflight every blueprint's document shape BEFORE a durable state
+ * transition. Ledger callbacks run after state is committed, so a flat
+ * blueprint must be rejected here or the command throws with state already
+ * written. Missing blueprints are tolerated exactly like the ledger append.
+ */
+export declare function assertUltragoalBlueprintShapes(cwd: string, slugs: readonly string[]): void;
 export declare function createUltragoal(input: {
     readonly cwd?: string;
     readonly brief: string;

package/dist/esm/ultragoal/service.js

@@ -7,6 +7,7 @@ import { BlueprintCreationService } from "#service/BlueprintCreationService.js";
 import { BlueprintService } from "#service/BlueprintService.js";
 import { scanBlueprintDirectory } from "#service/scanner.js";
 import { resolveBlueprintRoot } from "#utils/blueprint-root.js";
+import { assertFolderBlueprintIdentity, resolveBlueprintDocumentIdentity, } from "#utils/document-paths.js";
 import { assertUltragoalEnabled, assertUltragoalMutationAllowed } from "./guards.js";
 import { evaluateUltragoalCompletion, hasRepeatedQaError, MAX_STOP_STREAK, MAX_VALIDATION_ROUNDS, } from "./completion.js";
 import { formatUltragoalHandoff } from "./handoff.js";
@@ -222,14 +223,43 @@ export function decideUltragoalRun(input) {
     }
 }
 function findBlueprint(cwd, slug) {
+    const baseDir = resolveBlueprintRoot(cwd);
     const entries = scanBlueprintDirectory({
-        baseDir: resolveBlueprintRoot(cwd),
+        baseDir,
         includeSpecialFolders: true,
     });
     const found = entries.find((entry) => entry.slug === slug || entry.slug.endsWith(`/${slug}`));
     if (!found)
         throw new Error(`Blueprint not found: ${slug}`);
-    return found;
+    const identity = resolveBlueprintDocumentIdentity(baseDir, found.path);
+    if (!identity) {
+        throw new Error(`Blueprint ${found.slug} resolved to an invalid document path: ${found.path}`);
+    }
+    return { path: found.path, shape: identity.shape, slug: found.slug };
+}
+/**
+ * Preflight every blueprint's document shape BEFORE a durable state
+ * transition. Ledger callbacks run after state is committed, so a flat
+ * blueprint must be rejected here or the command throws with state already
+ * written. Missing blueprints are tolerated exactly like the ledger append.
+ */
+export function assertUltragoalBlueprintShapes(cwd, slugs) {
+    for (const slug of slugs) {
+        let found;
+        try {
+            found = findBlueprint(cwd, slug);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === `Blueprint not found: ${slug}`)
+                continue;
+            throw error;
+        }
+        assertFolderBlueprintIdentity({
+            documentPath: found.path,
+            lifecycleSlug: found.slug,
+            shape: found.shape,
+        });
+    }
 }
 function appendUltragoalLedgerEvent(cwd, slug, state, event) {
     let found;
@@ -241,6 +271,11 @@ function appendUltragoalLedgerEvent(cwd, slug, state, event) {
             return;
         throw error;
     }
+    assertFolderBlueprintIdentity({
+        documentPath: found.path,
+        lifecycleSlug: found.slug,
+        shape: found.shape,
+    });
     const reviewsPath = join(dirname(found.path), "reviews.md");
     mkdirSync(dirname(reviewsPath), { recursive: true });
     const prefix = existsSync(reviewsPath) ? "\n" : "# Blueprint reviews\n\n";
@@ -281,6 +316,7 @@ export async function createUltragoal(input) {
         sessionId: input.sessionId ?? process.env.WP_SESSION_ID ?? randomUUID(),
         ultragoalId: input.ultragoalId ?? `ultragoal-${randomUUID()}`,
     });
+    assertUltragoalBlueprintShapes(cwd, blueprintSlugs);
     await initializeUltragoalState(state, cwd, (written) => {
         for (const slug of blueprintSlugs)
             appendUltragoalLedgerEvent(cwd, slug, written, "created");
@@ -337,6 +373,9 @@ export async function getUltragoalHandoff(cwd = process.cwd()) {
 }
 export async function cancelUltragoal(cwd = process.cwd()) {
     assertUltragoalMutationAllowed(cwd);
+    const current = await readUltragoalState(cwd);
+    if (current)
+        assertUltragoalBlueprintShapes(cwd, current.blueprintSlugs);
     const next = await updateUltragoalState((state) => transitionUltragoalState(state, "cancelled"), cwd, (written) => {
         for (const slug of written.blueprintSlugs) {
             appendUltragoalLedgerEvent(cwd, slug, written, "cancelled");
@@ -394,6 +433,7 @@ export async function runCurrentUltragoal(cwd = process.cwd(), deps = {}) {
         now: deps.now?.() ?? new Date(),
     });
     if (committedDecision.state !== status.state) {
+        assertUltragoalBlueprintShapes(cwd, committedDecision.state.blueprintSlugs);
         await updateUltragoalState((current) => {
             if (current.ultragoalId !== status.state?.ultragoalId ||
                 current.updatedAt !== status.state.updatedAt ||

package/dist/esm/utils/write-json-file.js

@@ -1,4 +1,4 @@
-import { closeSync, copyFileSync, existsSync, fdatasyncSync, fsyncSync, openSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { closeSync, copyFileSync, existsSync, fdatasyncSync, fchmodSync, fsyncSync, openSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
 export function writeJsonFile(path, data, options = {}) {
@@ -45,6 +45,8 @@ function writeFileAtomicWithPolicy(path, content, options, allowCrossDeviceFallb
     let installed = false;
     try {
         fd = openSync(tmpPath, "w", normalized.mode);
+        if (normalized.mode !== undefined)
+            fchmodSync(fd, normalized.mode);
         writeFileSync(fd, content, normalized.writeOptions);
         fdatasyncSync(fd);
         closeSync(fd);

package/dist/esm/worktrees/codex-project-trust.d.ts

@@ -0,0 +1,15 @@
+export interface RemoveCodexProjectTrustOptions {
+    readonly configFilePath?: string;
+}
+/**
+ * Remove the exact Codex project-trust table for a worktree that has just been
+ * removed. This deliberately does not touch nested hook state or other project
+ * entries, which may remain valid user-owned configuration.
+ */
+export declare function removeCodexProjectTrust(worktreePath: string, options?: RemoveCodexProjectTrustOptions): Promise<"removed" | "unchanged">;
+/**
+ * Remove exact Codex project-trust tables in one locked rewrite. Prune can
+ * reconcile several externally deleted worktrees at once, so batching avoids
+ * taking the global config lock and rewriting the file for every entry.
+ */
+export declare function removeCodexProjectTrusts(worktreePaths: readonly string[], options?: RemoveCodexProjectTrustOptions): Promise<"removed" | "unchanged">;

package/dist/esm/worktrees/codex-project-trust.js

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync } from "node:fs";
+import lockfile from "proper-lockfile";
+import { defaultCodexConfigFilePath } from "#cli/commands/init/scaffolders/agent-hooks/codex-trust-sync.js";
+import { writeFileAtomic } from "#shared-utils/write-json-file.js";
+/**
+ * Remove the exact Codex project-trust table for a worktree that has just been
+ * removed. This deliberately does not touch nested hook state or other project
+ * entries, which may remain valid user-owned configuration.
+ */
+export function removeCodexProjectTrust(worktreePath, options = {}) {
+    return removeCodexProjectTrusts([worktreePath], options);
+}
+/**
+ * Remove exact Codex project-trust tables in one locked rewrite. Prune can
+ * reconcile several externally deleted worktrees at once, so batching avoids
+ * taking the global config lock and rewriting the file for every entry.
+ */
+export async function removeCodexProjectTrusts(worktreePaths, options = {}) {
+    if (worktreePaths.length === 0)
+        return "unchanged";
+    const configFilePath = options.configFilePath ?? defaultCodexConfigFilePath();
+    if (!existsSync(configFilePath))
+        return "unchanged";
+    const release = await lockfile.lock(configFilePath, {
+        realpath: false,
+        retries: { retries: 8, factor: 1.5, minTimeout: 25, maxTimeout: 250 },
+    });
+    try {
+        const existing = readFileSync(configFilePath, "utf8");
+        const next = removeProjectTrustTables(existing, worktreePaths);
+        if (next === existing)
+            return "unchanged";
+        writeFileAtomic(configFilePath, next, "utf8");
+        return "removed";
+    }
+    finally {
+        await release();
+    }
+}
+function removeProjectTrustTables(config, worktreePaths) {
+    const lines = config.split("\n");
+    const headers = new Set(worktreePaths.map((worktreePath) => `[projects.${JSON.stringify(worktreePath)}]`));
+    let removed = false;
+    for (let start = 0; start < lines.length;) {
+        if (!headers.has(lines[start]?.trim() ?? "")) {
+            start += 1;
+            continue;
+        }
+        let end = start + 1;
+        while (end < lines.length && !/^\s*\[.+\]\s*$/u.test(lines[end] ?? ""))
+            end += 1;
+        lines.splice(start, end - start);
+        removed = true;
+    }
+    return removed ? lines.join("\n") : config;
+}

package/dist/esm/worktrees/orphan-scan.d.ts

@@ -0,0 +1,50 @@
+import { type WorktreeInventory } from "./identity.js";
+export type OrphanClassification = "alive" | "orphan" | "broken" | "unrecognized";
+export interface OrphanScanCandidate {
+    readonly path: string;
+    readonly repoNamespace: string;
+}
+export interface OrphanScanRow extends OrphanScanCandidate {
+    readonly classification: OrphanClassification;
+    readonly dirty: boolean | "unknown";
+    /**
+     * Recursive size, computed ONLY for the final `orphan` classification.
+     * `alive` worktrees are actively worked on (often large `node_modules`
+     * trees) and are never removable, and `broken`/`unrecognized` rows need
+     * manual review regardless of size, so walking their full tree would burn
+     * significant time for no decision-relevant signal. `"unknown"` also
+     * covers a measurement failure/timeout on an orphan candidate.
+     */
+    readonly sizeBytes: number | "unknown";
+    readonly removable: boolean;
+    readonly reason: string;
+}
+export interface OrphanClassifyDeps {
+    readonly resolveRepoRoot: (candidate: OrphanScanCandidate) => string | undefined;
+    readonly repoRootExists: (repoRoot: string) => boolean;
+    readonly buildInventory: (repoRoot: string) => WorktreeInventory;
+    readonly probeDirty: (path: string) => boolean | "unknown";
+    readonly measureSize: (path: string) => number;
+}
+/** Classify a single on-disk candidate. Pure aside from the injected deps. */
+export declare function classifyOrphanCandidate(candidate: OrphanScanCandidate, deps: OrphanClassifyDeps): OrphanScanRow;
+/** Namespace-keyed lookup of a known-live `repoRoot`, first-registered-wins. */
+export declare function buildRegistryRepoRootMap(entries: readonly {
+    readonly repoNamespace: string;
+    readonly repoRoot: string;
+}[]): ReadonlyMap<string, string>;
+/**
+ * Fallback primary-repo resolver for candidates the registry never recorded:
+ * a linked worktree's `.git` is a file containing `gitdir: <repoRoot>/.git/
+ * worktrees/<name>`. Returns `undefined` when unreadable or unparseable
+ * (e.g. `.git` is a directory, or the pointer target was already reaped).
+ */
+export declare function resolveRepoRootFromGitPointer(path: string, readGitPointer: (gitPath: string) => string | undefined): string | undefined;
+export interface DiscoverOrphanCandidatesOptions {
+    readonly repoNamespaceFilter?: string;
+    readonly dirExists?: (path: string) => boolean;
+}
+/** Walk every known managed-worktree root and collect worktree-shaped leaf dirs. */
+export declare function discoverOrphanScanCandidates(roots: readonly string[], options?: DiscoverOrphanCandidatesOptions): OrphanScanCandidate[];
+/** Bounded recursive directory size, symlinks excluded, unreadable entries skipped. */
+export declare function measureDirectorySizeBytes(path: string): number;