@webpresso/agent-kit 3.2.0 → 3.3.0

package/dist/esm/review/subject.js

@@ -312,26 +312,32 @@ function neutralizePromotionGateResults(text) {
 // continuation lines). Each mirrors exactly one lifecycle writer:
 // `completed_at` (upsertCompletedAt) and the `wp blueprint start` /
 // progress-stamp fields (setBlueprintFrontmatterFields lifecycle intents).
-const PLAN_LIFECYCLE_STRIPPED_KEYS = [
+// Lifecycle writers only — the pre-tags-strip normalization (compat tier).
+const PLAN_LIFECYCLE_STRIPPED_KEYS_CORE = [
     "completed_at",
     "last_updated",
     "progress",
     "worktree_owner_id",
     "worktree_owner_branch",
 ];
+// Current plan-subject strip set: core lifecycle keys plus advisory `tags`.
+// Tags are not plan substance; MCP put and CLI serialize disagree on array-item
+// quoting (`- "x"` vs `- x`). Approvals recorded before the tags strip must
+// still verify via `preTagsStripNormalizePlanSubjectContent`.
+const PLAN_LIFECYCLE_STRIPPED_KEYS = [...PLAN_LIFECYCLE_STRIPPED_KEYS_CORE, "tags"];
 // Neutralize the lifecycle-owned frontmatter fields (`status:` value plus the
-// stripped keys above) INSIDE the leading frontmatter block only. A body line
+// stripped keys above, including advisory `tags`) INSIDE the leading frontmatter block only. A body line
 // that merely looks like one of these (e.g. task text reading
 // "completed_at: must remain unset until release") is plan substance and must
 // keep affecting the digest. Stripping removes the key line and any indented
 // continuation lines so folded (`>-`) values normalize away too.
-function neutralizeLifecycleFrontmatter(text) {
+function neutralizeLifecycleFrontmatter(text, strippedKeys = PLAN_LIFECYCLE_STRIPPED_KEYS) {
     const match = /^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/u.exec(text);
     if (!match)
         return text;
     let frontmatter = match[0];
     frontmatter = frontmatter.replace(/^(status:\s*)(['"]?)[^'"\r\n]+?(['"]?)(\s*)$/m, `$1${PLAN_STATUS_PLACEHOLDER}$4`);
-    for (const key of PLAN_LIFECYCLE_STRIPPED_KEYS) {
+    for (const key of strippedKeys) {
         frontmatter = frontmatter.replace(new RegExp(String.raw `^${key}:[^\n]*\n?(?:[ \t]+[^\n]*\n?)*`, "gmu"), "");
     }
     return `${frontmatter}${text.slice(match[0].length)}`;
@@ -463,6 +469,20 @@ export function legacyNormalizePlanSubjectContent(content) {
     text = neutralizePromotionGateResults(text);
     return Buffer.from(text, "utf8");
 }
+/**
+ * Digest-compatibility variant for review events recorded after the lifecycle
+ * stripped-key extension but before the advisory `tags` strip. Verification
+ * accepts a match against this tier so existing plan approvals on tagged
+ * blueprints are not stranded by the tags-strip rollout.
+ */
+export function preTagsStripNormalizePlanSubjectContent(content) {
+    let text = typeof content === "string" ? content : content.toString("utf8");
+    text = neutralizeLifecycleFrontmatter(text, PLAN_LIFECYCLE_STRIPPED_KEYS_CORE);
+    text = neutralizeReadinessStamps(text);
+    text = neutralizePromotionGateResults(text);
+    text = neutralizeTaskExecutionState(text);
+    return Buffer.from(text, "utf8");
+}
 function planSubjectAtRef(cwd, ref, blueprintSlug, normalize, blueprintPath) {
     const commit = resolveReviewCommit(cwd, ref);
     const entries = parseTree(cwd, commit);
@@ -491,6 +511,24 @@ export function createPlanSubjectAtRef(cwd, ref, blueprintSlug, blueprintPath) {
 export function createLegacyPlanSubjectAtRef(cwd, ref, blueprintSlug, blueprintPath) {
     return planSubjectAtRef(cwd, ref, blueprintSlug, legacyNormalizePlanSubjectContent, blueprintPath);
 }
+/** Plan subject digested without the advisory `tags` strip (pre-tags-strip tier). */
+export function createPreTagsStripPlanSubjectAtRef(cwd, ref, blueprintSlug, blueprintPath) {
+    return planSubjectAtRef(cwd, ref, blueprintSlug, preTagsStripNormalizePlanSubjectContent, blueprintPath);
+}
+/** Working-ledger digest for the pre-tags-strip compatibility tier. */
+export function createPreTagsStripPlanSubjectDigestForContent(blueprintSlug, content) {
+    const hash = createHash("sha256").update(PLAN_DOMAIN);
+    updateField(hash, blueprintSlug);
+    updateField(hash, preTagsStripNormalizePlanSubjectContent(content));
+    return hash.digest("hex");
+}
+/** Working-ledger digest for the pre-extension legacy compatibility tier. */
+export function createLegacyPlanSubjectDigestForContent(blueprintSlug, content) {
+    const hash = createHash("sha256").update(PLAN_DOMAIN);
+    updateField(hash, blueprintSlug);
+    updateField(hash, legacyNormalizePlanSubjectContent(content));
+    return hash.digest("hex");
+}
 export const reviewSubjectInternals = {
     isExcludedReviewEnvelope,
     isReviewEvidencePath,

package/dist/esm/rust/affected-manifests.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Maps changed repo paths to the tracked Rust crate(s) they belong to.
+ *
+ * Pure and dependency-free so it is unit-testable without shelling out to
+ * `cargo` or `git` — see `#cli/commands/rust-check.js` for the CLI command
+ * that spawns `cargo check`/`cargo test` for whatever this resolves.
+ */
+export interface TrackedRustCrate {
+    /** Crate directory relative to the repo root, e.g. "native/dash-tui". */
+    readonly root: string;
+    /** Manifest path relative to the repo root. */
+    readonly manifest: string;
+    /** `cargo` args (after `cargo`) that prove this crate's tests still pass. */
+    readonly testArgs: readonly string[];
+}
+/**
+ * The Rust crates `wp ci-preflight` proves compile + pass on an affected
+ * change. Mirrors exactly what `.github/workflows/ci.agent-kit.yml` (native
+ * session-memory + dash-tui jobs) and `.github/workflows/desktop-perf.yml`
+ * (desktop `src-tauri`) already build and test in CI — no new cargo
+ * invocation shape is invented here.
+ *
+ * Deliberately EXCLUDES the `spikes/**` crates (`spikes/pty-spawn-transport/
+ * rust`, `spikes/desktop-pty-loadtest/rust`,
+ * `spikes/desktop-pty-loadtest/src-tauri`): no CI workflow builds or tests
+ * them today — they are scratch/prototype crates with no compile guarantee.
+ * Gating pre-push on them would fail closed on code nobody has ever promised
+ * compiles. Revisit this list if a spike graduates to a tracked crate.
+ */
+export declare const TRACKED_RUST_CRATES: readonly TrackedRustCrate[];
+/**
+ * Returns the sorted, deduped list of tracked-crate manifest paths touched by
+ * `files`. Rust files under an untracked crate (e.g. `spikes/**`) or outside
+ * any crate are ignored, not escalated to "affects everything" — each
+ * manifest maps back to `TRACKED_RUST_CRATES` for its `testArgs`.
+ */
+export declare function resolveAffectedRustManifests(files: readonly string[]): readonly string[];
+export declare function trackedCrateForManifest(manifest: string): TrackedRustCrate | undefined;

package/dist/esm/rust/affected-manifests.js

@@ -0,0 +1,69 @@
+/**
+ * Maps changed repo paths to the tracked Rust crate(s) they belong to.
+ *
+ * Pure and dependency-free so it is unit-testable without shelling out to
+ * `cargo` or `git` — see `#cli/commands/rust-check.js` for the CLI command
+ * that spawns `cargo check`/`cargo test` for whatever this resolves.
+ */
+/**
+ * The Rust crates `wp ci-preflight` proves compile + pass on an affected
+ * change. Mirrors exactly what `.github/workflows/ci.agent-kit.yml` (native
+ * session-memory + dash-tui jobs) and `.github/workflows/desktop-perf.yml`
+ * (desktop `src-tauri`) already build and test in CI — no new cargo
+ * invocation shape is invented here.
+ *
+ * Deliberately EXCLUDES the `spikes/**` crates (`spikes/pty-spawn-transport/
+ * rust`, `spikes/desktop-pty-loadtest/rust`,
+ * `spikes/desktop-pty-loadtest/src-tauri`): no CI workflow builds or tests
+ * them today — they are scratch/prototype crates with no compile guarantee.
+ * Gating pre-push on them would fail closed on code nobody has ever promised
+ * compiles. Revisit this list if a spike graduates to a tracked crate.
+ */
+export const TRACKED_RUST_CRATES = [
+    {
+        root: "native/session-memory-engine",
+        manifest: "native/session-memory-engine/Cargo.toml",
+        testArgs: ["test", "--manifest-path", "native/session-memory-engine/Cargo.toml", "--all"],
+    },
+    {
+        root: "native/dash-tui",
+        manifest: "native/dash-tui/Cargo.toml",
+        testArgs: ["test", "--manifest-path", "native/dash-tui/Cargo.toml"],
+    },
+    {
+        root: "apps/desktop/src-tauri",
+        manifest: "apps/desktop/src-tauri/Cargo.toml",
+        testArgs: ["test", "--manifest-path", "apps/desktop/src-tauri/Cargo.toml", "--lib"],
+    },
+];
+function isRustSignalFile(file) {
+    return (file.endsWith(".rs") ||
+        file === "Cargo.toml" ||
+        file.endsWith("/Cargo.toml") ||
+        file === "Cargo.lock" ||
+        file.endsWith("/Cargo.lock"));
+}
+function owningTrackedCrate(file) {
+    return TRACKED_RUST_CRATES.find((candidate) => file === candidate.root || file.startsWith(`${candidate.root}/`));
+}
+/**
+ * Returns the sorted, deduped list of tracked-crate manifest paths touched by
+ * `files`. Rust files under an untracked crate (e.g. `spikes/**`) or outside
+ * any crate are ignored, not escalated to "affects everything" — each
+ * manifest maps back to `TRACKED_RUST_CRATES` for its `testArgs`.
+ */
+export function resolveAffectedRustManifests(files) {
+    const manifests = new Set();
+    for (const rawFile of files) {
+        const file = rawFile.replaceAll("\\", "/");
+        if (!isRustSignalFile(file))
+            continue;
+        const crate = owningTrackedCrate(file);
+        if (crate)
+            manifests.add(crate.manifest);
+    }
+    return [...manifests].sort();
+}
+export function trackedCrateForManifest(manifest) {
+    return TRACKED_RUST_CRATES.find((candidate) => candidate.manifest === manifest);
+}

package/dist/esm/session-memory/fetch-index.d.ts

@@ -20,7 +20,7 @@ export interface FetchAndIndexOptions {
     signal?: AbortSignal;
 }
 export declare function fetchAndIndex(options: FetchAndIndexOptions, deps?: {
-    readonly fetchImpl?: typeof fetch;
+    readonly fetchImpl?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
     /** Internal/test-only escape hatch for loopback fixtures; never exposed in CLI/MCP input. */
     readonly allowedHosts?: readonly string[];
 }): Promise<SessionMemoryChunk[]>;

package/dist/esm/status/snapshot.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { z } from "zod";
+import { hasChangesetEvidence } from "#audit/changeset-evidence.js";
 import { evaluateApprovalReviewers } from "#lifecycle/audit.js";
 import { collectV2ReviewProvenance } from "#lifecycle/review-provenance.js";
 import { evaluateRequiredChecks } from "#mcp/tools/_shared/required-checks.js";
@@ -210,12 +211,7 @@ function hasDisclosure(body, label) {
     return new RegExp(`(?:^|\\n)\\s*(?:-\\s*)?${escaped}:\\s*\\S`, "iu").test(body);
 }
 function hasReleaseEvidence(pr) {
-    const files = prFiles(pr);
-    if (files.length > 0 && files.every((file) => file.endsWith(".md")))
-        return true;
-    if (files.some((file) => /^\.changeset\/[^/]+\.md$/u.test(file)))
-        return true;
-    return /Changeset-exempt:\s*\S/iu.test(stringField(pr.body) ?? "");
+    return hasChangesetEvidence(prFiles(pr), [stringField(pr.body) ?? ""]);
 }
 export function evaluatePrReadiness(evidence) {
     const blockers = [];

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">): Promise<void>;

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

@@ -11,10 +11,6 @@ const MIGRATION_SENTINEL = join(REPO_ROOT, "dist", "esm", "blueprint", "db", "mi
 // 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");
-const DIST_PREP_PROJECTS = new Set(["subprocess", "serial-subprocess"]);
-export function shouldPrepareDistForProject(projectName) {
-    return projectName !== undefined && DIST_PREP_PROJECTS.has(projectName);
-}
 // 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`).
@@ -33,19 +29,21 @@ async function withDistBuildLock(fn) {
         await release();
     }
 }
-// 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 async function setup(project) {
-    syncSastRuleAssets(REPO_ROOT);
-    if (!shouldPrepareDistForProject(project?.name))
-        return;
+// 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)) {
-        if (project?.name === "serial-subprocess") {
-            ensureHostRuntimeArtifactsForSerialTests({ rootDir: REPO_ROOT });
-        }
+    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.
@@ -83,6 +81,11 @@ export async function setup(project) {
             });
         }
     });
+}
+// 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/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;

package/dist/esm/worktrees/orphan-scan.js

@@ -0,0 +1,211 @@
+/**
+ * Filesystem-level orphan scan for `wp worktree prune --orphans`.
+ *
+ * Complements the existing registry-only `wp worktree prune --all`: that
+ * command only drops stale bookkeeping rows from `registry.json`. This module
+ * instead walks the physical managed-worktree roots
+ * (`~/.webpresso/worktrees`, legacy `~/.agent/worktrees`) directly, because a
+ * large share of stale directories on disk were never registered at all
+ * (crashed sessions, `gh pr merge --delete-branch` deregistering the git
+ * worktree out from under the directory, manual `rm` of only part of a
+ * worktree). Git metadata and the registry can both be perfectly clean while
+ * the `~/.webpresso` tree still accumulates dozens of dead directories.
+ *
+ * Classification (see `catalog blueprint worktree-prune-stale-dirs`):
+ *
+ * - `alive`        — path is listed by `git worktree list` for its resolved
+ *                     primary repo. Never removable.
+ * - `orphan`        — a resolvable, existing primary repo's `git worktree
+ *                     list` output does NOT include this path. Removable only
+ *                     when a `git status --porcelain` probe inside the
+ *                     directory succeeds AND reports no changes.
+ * - `broken`        — a primary repo pointer was resolved, but the target
+ *                     repo itself is missing on disk, or its `git worktree
+ *                     list` probe failed outright (bounded, non-retrying).
+ *                     Never removable — the directory's true state cannot be
+ *                     proven.
+ * - `unrecognized`  — no primary repo pointer could be resolved at all
+ *                     (neither `registry.json` nor the directory's own
+ *                     `.git` file yields one), or the directory's `.git`
+ *                     pointer resolves but `git status --porcelain` cannot
+ *                     even run inside it (not a functioning checkout).
+ *                     Reported for manual review; never removable.
+ */
+import { readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { canonicalizeWorktreePath } from "./identity.js";
+function measureSizeSafely(path, deps) {
+    try {
+        return deps.measureSize(path);
+    }
+    catch {
+        return "unknown";
+    }
+}
+function finalizeRow(candidate, classification, reason, deps) {
+    if (classification !== "orphan") {
+        return {
+            ...candidate,
+            classification,
+            dirty: "unknown",
+            sizeBytes: "unknown",
+            removable: false,
+            reason,
+        };
+    }
+    const dirty = deps.probeDirty(candidate.path);
+    if (dirty === "unknown") {
+        return {
+            ...candidate,
+            classification: "unrecognized",
+            dirty,
+            sizeBytes: "unknown",
+            removable: false,
+            reason: "git status probe failed — not a functioning git checkout",
+        };
+    }
+    // Size is decision-relevant only once a row is a confirmed orphan, so it is
+    // measured here — never for alive/broken/unrecognized rows above.
+    const sizeBytes = measureSizeSafely(candidate.path, deps);
+    return {
+        ...candidate,
+        classification,
+        dirty,
+        sizeBytes,
+        removable: dirty === false,
+        reason: dirty ? "uncommitted/untracked changes present" : reason,
+    };
+}
+/** Classify a single on-disk candidate. Pure aside from the injected deps. */
+export function classifyOrphanCandidate(candidate, deps) {
+    const repoRoot = deps.resolveRepoRoot(candidate);
+    if (!repoRoot) {
+        return finalizeRow(candidate, "unrecognized", "no resolvable primary repo pointer", deps);
+    }
+    if (!deps.repoRootExists(repoRoot)) {
+        return finalizeRow(candidate, "broken", `target repo missing: ${repoRoot}`, deps);
+    }
+    const inventory = deps.buildInventory(repoRoot);
+    if (!inventory.complete) {
+        return finalizeRow(candidate, "broken", "git worktree list unavailable for target repo", deps);
+    }
+    const canonical = canonicalizeWorktreePath(candidate.path);
+    if (inventory.canonicalPaths.has(canonical)) {
+        return finalizeRow(candidate, "alive", "present in git worktree list", deps);
+    }
+    return finalizeRow(candidate, "orphan", "absent from git worktree list", deps);
+}
+/** Namespace-keyed lookup of a known-live `repoRoot`, first-registered-wins. */
+export function buildRegistryRepoRootMap(entries) {
+    const map = new Map();
+    for (const entry of entries) {
+        if (!map.has(entry.repoNamespace))
+            map.set(entry.repoNamespace, entry.repoRoot);
+    }
+    return map;
+}
+const WORKTREES_GITDIR_MARKER = "/.git/worktrees/";
+/**
+ * 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 function resolveRepoRootFromGitPointer(path, readGitPointer) {
+    const content = readGitPointer(join(path, ".git"));
+    if (!content)
+        return undefined;
+    const match = /^gitdir:\s*(.+)$/mu.exec(content.trim());
+    const gitdir = match?.[1]?.trim();
+    if (!gitdir)
+        return undefined;
+    const markerIndex = gitdir.lastIndexOf(WORKTREES_GITDIR_MARKER);
+    if (markerIndex === -1)
+        return undefined;
+    return gitdir.slice(0, markerIndex);
+}
+const MAX_SCAN_DEPTH = 8;
+const SKIP_DIR_NAMES = new Set([".git", "node_modules"]);
+function repoNamespaceFromPath(root, path) {
+    const segments = relative(root, path).split(sep).filter(Boolean);
+    const reposIndex = segments.indexOf("repos");
+    if (reposIndex === -1)
+        return undefined;
+    return segments[reposIndex + 1];
+}
+function walkForCandidates(root, dir, depth, out) {
+    if (depth > MAX_SCAN_DEPTH)
+        return;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true, encoding: "utf8" });
+    }
+    catch {
+        return;
+    }
+    if (entries.some((entry) => entry.name === ".git")) {
+        const repoNamespace = repoNamespaceFromPath(root, dir);
+        if (repoNamespace)
+            out.push({ path: dir, repoNamespace });
+        return; // never descend into a worktree checkout's own contents
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || SKIP_DIR_NAMES.has(entry.name))
+            continue;
+        walkForCandidates(root, join(dir, entry.name), depth + 1, out);
+    }
+}
+/** Walk every known managed-worktree root and collect worktree-shaped leaf dirs. */
+export function discoverOrphanScanCandidates(roots, options = {}) {
+    const dirExists = options.dirExists ??
+        ((path) => {
+            try {
+                return statSync(path).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    const out = [];
+    for (const root of roots) {
+        if (!dirExists(root))
+            continue;
+        walkForCandidates(root, root, 0, out);
+    }
+    return options.repoNamespaceFilter
+        ? out.filter((candidate) => candidate.repoNamespace === options.repoNamespaceFilter)
+        : out;
+}
+/** Bounded recursive directory size, symlinks excluded, unreadable entries skipped. */
+export function measureDirectorySizeBytes(path) {
+    let total = 0;
+    const stack = [path];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (current === undefined)
+            break;
+        let entries;
+        try {
+            entries = readdirSync(current, { withFileTypes: true, encoding: "utf8" });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(full);
+                continue;
+            }
+            try {
+                total += statSync(full).size;
+            }
+            catch {
+                // unreadable file: skip rather than fail the whole scan
+            }
+        }
+    }
+    return total;
+}