@webpresso/agent-kit 3.2.0 → 3.3.1

package/dist/esm/review/execution/review-checkout.js

@@ -23,24 +23,34 @@ function frame(hash, label, value) {
     hash.update(`${label}\0${bytes.byteLength}\0`, "utf8");
     hash.update(bytes);
 }
-function worktreeFingerprint(cwd) {
+// Fingerprint over the filtered line set `status()` produces below, minus
+// pure gitignored (`!!`) entries, so the two contamination checks
+// (`changes()`'s status() diff and the caller worktree fingerprint) cannot
+// drift apart on what counts as "source" content while still tolerating
+// expected runtime bookkeeping.
+//
+// Before the status()-alignment fix, the fingerprint hashed the raw
+// unfiltered `git status` output (without `--ignored`), so anything status()
+// already tolerates (the self-hosting bootstrap's idempotent `package.json`
+// trailing-whitespace normalization, and non-source ignored paths under
+// dist/.tshy/node_modules) could still flip the fingerprint and false-flag a
+// clean caller worktree as contaminated.
+//
+// Reusing status() alone re-introduces a different false positive: the
+// supervisor writes process records under gitignored `.webpresso/` (and similar
+// runtime roots) during the run. Those appear as `!!` lines only when
+// `--ignored` is on. Dropping `!!` here restores the prior fingerprint
+// contract for ignored paths while keeping the package.json / non-`!!` filters
+// shared with status(). Checkout-side status() still reports non-derived
+// gitignored writes (e.g. a stray `.env`) on the disposable review tree.
+function worktreeFingerprint(cwd, ignoredPaths = new Set()) {
     const hash = createHash("sha256");
-    const porcelain = git(cwd, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]);
-    frame(hash, "porcelain", porcelain);
+    const lines = status(cwd, ignoredPaths).filter((line) => !line.startsWith("!!"));
+    frame(hash, "status-lines", lines.join("\n"));
     frame(hash, "staged", gitBytes(cwd, ["diff", "--cached", "--binary", "--no-ext-diff", "HEAD", "--"]));
-    const records = porcelain.split("\0").filter(Boolean);
     const dirtyPaths = new Set();
-    for (let index = 0; index < records.length; index += 1) {
-        const record = records[index] ?? "";
-        dirtyPaths.add(record.slice(3));
-        if (record.slice(0, 2).match(/[RC]/u)) {
-            const pairedPath = records[index + 1];
-            if (pairedPath) {
-                dirtyPaths.add(pairedPath);
-                index += 1;
-            }
-        }
-    }
+    for (const line of lines)
+        dirtyPaths.add(statusEntryPath(line));
     for (const relativePath of [...dirtyPaths].filter(Boolean).toSorted()) {
         const absolutePath = join(cwd, relativePath);
         frame(hash, "dirty-path", relativePath);
@@ -108,13 +118,44 @@ function isNormalizedPackageJsonModification(cwd, line) {
         return false;
     }
 }
+// Single source of truth for turning a `git status --porcelain=v1` line into
+// its relative path, shared by status()'s filter predicate and
+// worktreeFingerprint()'s dirty-path hashing so both stay aligned by
+// construction.
+//
+// Rename/copy lines use non-null porcelain form `XY ORIG -> DEST` (or quoted
+// paths). The destination is the live path whose bytes must be fingerprinted;
+// using the raw `ORIG -> DEST` tail makes lstat miss both sides and silently
+// drops content from the hash (regression vs paired-record `-z` parsing).
+function statusEntryPath(line) {
+    const tail = line.slice(3).replace(/\/$/u, "");
+    const renameSep = " -> ";
+    const sep = tail.lastIndexOf(renameSep);
+    const pathPart = sep === -1 ? tail : tail.slice(sep + renameSep.length);
+    return unquotePorcelainPath(pathPart);
+}
+/** Strip git porcelain double-quotes and reverse C-style escapes for a path. */
+function unquotePorcelainPath(pathPart) {
+    if (!pathPart.startsWith('"') || !pathPart.endsWith('"') || pathPart.length < 2) {
+        return pathPart;
+    }
+    return pathPart.slice(1, -1).replace(/\\([\\"ntr])/gu, (_m, ch) => {
+        if (ch === "n")
+            return "\n";
+        if (ch === "t")
+            return "\t";
+        if (ch === "r")
+            return "\r";
+        return ch;
+    });
+}
 function status(cwd, ignoredPaths = new Set()) {
     const output = git(cwd, ["status", "--porcelain=v1", "--untracked-files=all", "--ignored"]);
     return output
         .split(/\r?\n/u)
         .filter((line) => line.length > 0)
         .filter((line) => {
-        const relativePath = line.slice(3).replace(/\/$/u, "");
+        const relativePath = statusEntryPath(line);
         if (ignoredPaths.has(relativePath))
             return false;
         if (line.startsWith("!!") && isNonSourceIgnoredPath(relativePath))
@@ -226,3 +267,7 @@ function projectCallerDependencies(repositoryRoot, checkoutRoot) {
     projected.add(dependencyPath);
     return projected;
 }
+/** Test-only surface for porcelain path parsing. */
+export const reviewCheckoutInternals = {
+    statusEntryPath,
+};

package/dist/esm/review/execution/supervisor.js

@@ -123,6 +123,10 @@ export async function superviseReviewExecution(input, adapter, deps = {}) {
     let fallbackSelectionTimer;
     let pendingFallback;
     const seenFrontiers = new Set();
+    const droppedEventWarnings = [];
+    const recordDroppedProviderEvent = (reason) => {
+        droppedEventWarnings.push(reason);
+    };
     const decoder = new StringDecoder("utf8");
     const diagnosticDecoder = new StringDecoder("utf8");
     let buffered = "";
@@ -230,19 +234,41 @@ export async function superviseReviewExecution(input, adapter, deps = {}) {
     const processLine = (line) => {
         if (line.trim().length === 0 || status !== null)
             return;
-        if (Buffer.byteLength(line, "utf8") > MAX_PROVIDER_EVENT_BYTES) {
-            fail("protocol-unsupported", "provider-event-too-large");
-            return;
-        }
+        const oversized = Buffer.byteLength(line, "utf8") > MAX_PROVIDER_EVENT_BYTES;
         let value;
         try {
             value = JSON.parse(line);
         }
         catch {
+            // An oversized frame that also fails to parse carries no recoverable
+            // signal (a genuinely truncated/malformed line looks the same either
+            // way) -- drop it with a warning instead of failing a run that may
+            // still receive a complete, well-formed terminal verdict later. A
+            // normal-sized malformed line is still a protocol violation.
+            if (oversized) {
+                recordDroppedProviderEvent("provider-event-too-large-unparseable");
+                return;
+            }
             fail("protocol-unsupported", "invalid-json-event");
             return;
         }
         const event = adapter.parseEvent(value);
+        if (oversized && (event.kind === "terminal" || event.kind === "failure")) {
+            // Terminal/verdict and failure frames are load-bearing: an oversized
+            // one is treated as a protocol violation, same as before this fix.
+            fail("protocol-unsupported", "provider-event-too-large");
+            return;
+        }
+        if (oversized) {
+            // Non-terminal (progress/neutral/unsupported) oversized frames are
+            // dropped rather than failing the whole run -- a provider that echoes
+            // e.g. a large lockfile read in a progress frame must not discard an
+            // otherwise-complete review verdict. See catalog/agent/rules
+            // /no-timeout-as-fix.md: the byte bound stays in place, we just stop
+            // treating "one big frame" as fatal to the whole run.
+            recordDroppedProviderEvent(`provider-event-too-large-${event.kind}`);
+            return;
+        }
         if (event.kind === "unsupported") {
             fail("protocol-unsupported", "unknown-provider-event");
             return;
@@ -433,6 +459,7 @@ export async function superviseReviewExecution(input, adapter, deps = {}) {
             ...(limitWindow === undefined ? {} : { limitWindow }),
             ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
             summaryPath: artifacts.summaryPath,
+            ...(droppedEventWarnings.length > 0 ? { warnings: [...droppedEventWarnings] } : {}),
         };
     }
     function recordReviewProcessStart(reviewChild, processGroupId) {

package/dist/esm/review/execution/types.d.ts

@@ -81,4 +81,5 @@ export interface ReviewRunSummary {
     readonly limitWindow?: ReviewLimitWindow;
     readonly retryAfterMs?: number;
     readonly summaryPath: string;
+    readonly warnings?: readonly string[];
 }

package/dist/esm/review/subject.d.ts

@@ -43,9 +43,22 @@ export declare function createPlanSubjectDigestForContent(blueprintSlug: string,
  * `normalizePlanSubjectContent`.
  */
 export declare function legacyNormalizePlanSubjectContent(content: Buffer | string): Buffer;
+/**
+ * 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 declare function preTagsStripNormalizePlanSubjectContent(content: Buffer | string): Buffer;
 export declare function createPlanSubjectAtRef(cwd: string, ref: string, blueprintSlug: string, blueprintPath?: string): ReviewSubject;
 /** Plan subject digested with the pre-extension normalization (see above). */
 export declare function createLegacyPlanSubjectAtRef(cwd: string, ref: string, blueprintSlug: string, blueprintPath?: string): ReviewSubject;
+/** Plan subject digested without the advisory `tags` strip (pre-tags-strip tier). */
+export declare function createPreTagsStripPlanSubjectAtRef(cwd: string, ref: string, blueprintSlug: string, blueprintPath?: string): ReviewSubject;
+/** Working-ledger digest for the pre-tags-strip compatibility tier. */
+export declare function createPreTagsStripPlanSubjectDigestForContent(blueprintSlug: string, content: Buffer | string): string;
+/** Working-ledger digest for the pre-extension legacy compatibility tier. */
+export declare function createLegacyPlanSubjectDigestForContent(blueprintSlug: string, content: Buffer | string): string;
 export declare const reviewSubjectInternals: {
     isExcludedReviewEnvelope: typeof isExcludedReviewEnvelope;
     isReviewEvidencePath: typeof isReviewEvidencePath;

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;