@cleocode/core 2026.10.1 → 2026.10.2

package/dist/tasks/tool-cache-env.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Environment fingerprint for the evidence tool cache (T12958, review of #1774).
+ *
+ * The tree hash identifies the SOURCE a run measured. Tools that read build
+ * output or installed dependencies also depend on per-checkout state git does
+ * not see: `node_modules`, gitignored `dist/` directories that workspace
+ * packages resolve through, and `.env*` files. Two worktrees with identical
+ * source but a stale `dist/` in one of them must not share a `test` result.
+ *
+ * The fingerprint is cheap and content-shaped, so two checkouts that were
+ * installed and built from the same source compare EQUAL (sharing works) while
+ * a missing install, a different install or a stale build compares different:
+ *
+ *   - the installed-lockfile snapshot the package manager keeps inside
+ *     `node_modules` (`.pnpm/lock.yaml`, `.package-lock.json`,
+ *     `.yarn-state.yml`, `.yarn-integrity`) — hashed by content, because
+ *     pnpm's `.modules.yaml` carries a per-install timestamp;
+ *   - for every workspace package (each tracked `package.json`), the
+ *     relative path and SIZE of every file under its `dist/` — sizes rather
+ *     than mtimes, which differ between two equally fresh builds;
+ *   - the content of untracked `.env*` files at the execution root.
+ *
+ * Sizes are a heuristic: a rebuild from different source that produces
+ * byte-for-byte equal sizes everywhere would collide. When the `dist/` walk
+ * exceeds {@link MAX_DIST_FILES} the fingerprint falls back to the execution
+ * root itself, which disables cross-worktree sharing rather than guessing.
+ *
+ * Only {@link ENV_SENSITIVE_TOOLS} pay for this; other tools get a constant.
+ *
+ * ## Resource environment (T12989)
+ *
+ * {@link captureResourceEnv} is a second, separate key input: the resource
+ * limits the run is spawned with. A run that fits in a 6 GB heap and one that
+ * does not fit in 3 GB are different runs of the same code, and keying only on
+ * source and installed state let a retry with a larger heap replay the cached
+ * 3 GB result (axiom field report, T963). It covers only what decides whether a
+ * run fits, never the whole environment, so an unrelated variable or
+ * `NODE_OPTIONS` flag never moves the key:
+ *
+ *   - the V8 heap flags in `NODE_OPTIONS` ({@link effectiveHeapFlags}), for
+ *     every tool, because every Node process a tool starts inherits them;
+ *   - for heavy tools, every variable `heavyToolEnv` manages (the per-runner
+ *     worker counts, `npm_config_workspace_concurrency`, `MAKEFLAGS`) and the
+ *     cgroup ceiling overrides (`CLEO_TOOL_MEMORY_MAX_MB`, `CLEO_NO_TOOL_CGROUP`).
+ *
+ * The heavy variable list is derived from `heavyToolEnv` itself, so a lever
+ * added there is keyed with no second list to keep in step.
+ *
+ * @task T12958
+ * @task T12989
+ */
+import { type HeavyToolEnv } from './heavy-tool-env.js';
+import type { CanonicalTool } from './tool-resolver.js';
+/** Canonical tools whose result depends on installed deps or build output. */
+export declare const ENV_SENSITIVE_TOOLS: ReadonlySet<string>;
+/** Fingerprint for tools that read only source. */
+export declare const ENV_FINGERPRINT_NONE = "none";
+/** Most `dist/` files walked before falling back to the execution root. */
+export declare const MAX_DIST_FILES = 100000;
+/**
+ * Fingerprint the per-checkout environment a tool run depends on.
+ *
+ * @param root - The execution root.
+ * @param canonical - Canonical tool name.
+ * @returns 32 hex chars, or {@link ENV_FINGERPRINT_NONE} for tools outside
+ *   {@link ENV_SENSITIVE_TOOLS}.
+ *
+ * @task T12958
+ */
+export declare function captureEnvFingerprint(root: string, canonical: string): string;
+/**
+ * The V8 heap flags in effect for a `NODE_OPTIONS` value, as `--name=value`
+ * sorted by name and joined with a space; `''` when none is set.
+ *
+ * V8 reads flags left to right and a later value replaces an earlier one, so
+ * the LAST occurrence of each flag is the effective one. Underscores in a flag
+ * name read as dashes, as they do to V8. The space-separated spelling
+ * (`--max-old-space-size 4096`) is read too, because `mergeNodeOptions` treats
+ * it as an explicit setting.
+ *
+ * @param nodeOptions - A `NODE_OPTIONS` value, if any.
+ * @returns The effective heap flags, e.g. `--max-old-space-size=6144`.
+ *
+ * @example
+ * ```ts
+ * effectiveHeapFlags('--enable-source-maps --max-old-space-size=3072 --max_old_space_size=6144');
+ * // → '--max-old-space-size=6144'
+ * effectiveHeapFlags('--enable-source-maps'); // → ''
+ * ```
+ *
+ * @task T12989
+ */
+export declare function effectiveHeapFlags(nodeOptions: string | undefined): string;
+/**
+ * The resource limits a tool run is spawned with, as readable `NAME=value`
+ * pairs sorted by name and joined with `;` (T12989). Part of the tool-cache key
+ * and recorded on the entry, so a cached result says which heap and worker
+ * count produced it, and a retry with different limits is a different run.
+ *
+ * Reads the EFFECTIVE environment — `env` with the heavy-tool `overlay`
+ * applied, exactly as `spawnCmd` merges it — so a limit the caller exported
+ * and one `heavyToolEnv` supplied key the same way. Covers:
+ *
+ *   - `NODE_OPTIONS`, reduced to its heap flags ({@link effectiveHeapFlags}),
+ *     for every tool;
+ *   - for heavy tools only, every variable `heavyToolEnv` can set (derived by
+ *     asking it what it sets for an empty environment) plus the cgroup
+ *     ceiling overrides `CLEO_TOOL_MEMORY_MAX_MB` and `CLEO_NO_TOOL_CGROUP`.
+ *
+ * A variable outside this set does not move the key; force a fresh run with
+ * `CLEO_EVIDENCE_FRESH=1` when one matters.
+ *
+ * @param canonical - Canonical tool name.
+ * @param env - The environment the child inherits.
+ * @param overlay - The heavy-tool overlay the child is spawned with; defaults
+ *   to `heavyToolEnv(canonical, env)`. `runToolCached` passes the overlay it
+ *   spawns with, so the key and the spawn read one value.
+ * @returns e.g. `NODE_OPTIONS=--max-old-space-size=4096;VITEST_MAX_WORKERS=6;…`
+ *
+ * @task T12989
+ */
+export declare function captureResourceEnv(canonical: CanonicalTool, env?: NodeJS.ProcessEnv, overlay?: HeavyToolEnv): string;
+//# sourceMappingURL=tool-cache-env.d.ts.map

package/dist/tasks/tool-cache-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-cache-env.d.ts","sourceRoot":"","sources":["../../src/tasks/tool-cache-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAMH,OAAO,EAAE,KAAK,YAAY,EAA6B,MAAM,qBAAqB,CAAC;AAEnF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAA2C,CAAC;AAEhG,mDAAmD;AACnD,eAAO,MAAM,oBAAoB,SAAS,CAAC;AAE3C,2EAA2E;AAC3E,eAAO,MAAM,cAAc,SAAU,CAAC;AAqDtC;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAsC7E;AAiBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAqB1E;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,aAAa,EACxB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,YAA2C,GACnD,MAAM,CAYR"}

package/dist/tasks/tool-cache-env.js

@@ -0,0 +1,287 @@
+/**
+ * Environment fingerprint for the evidence tool cache (T12958, review of #1774).
+ *
+ * The tree hash identifies the SOURCE a run measured. Tools that read build
+ * output or installed dependencies also depend on per-checkout state git does
+ * not see: `node_modules`, gitignored `dist/` directories that workspace
+ * packages resolve through, and `.env*` files. Two worktrees with identical
+ * source but a stale `dist/` in one of them must not share a `test` result.
+ *
+ * The fingerprint is cheap and content-shaped, so two checkouts that were
+ * installed and built from the same source compare EQUAL (sharing works) while
+ * a missing install, a different install or a stale build compares different:
+ *
+ *   - the installed-lockfile snapshot the package manager keeps inside
+ *     `node_modules` (`.pnpm/lock.yaml`, `.package-lock.json`,
+ *     `.yarn-state.yml`, `.yarn-integrity`) — hashed by content, because
+ *     pnpm's `.modules.yaml` carries a per-install timestamp;
+ *   - for every workspace package (each tracked `package.json`), the
+ *     relative path and SIZE of every file under its `dist/` — sizes rather
+ *     than mtimes, which differ between two equally fresh builds;
+ *   - the content of untracked `.env*` files at the execution root.
+ *
+ * Sizes are a heuristic: a rebuild from different source that produces
+ * byte-for-byte equal sizes everywhere would collide. When the `dist/` walk
+ * exceeds {@link MAX_DIST_FILES} the fingerprint falls back to the execution
+ * root itself, which disables cross-worktree sharing rather than guessing.
+ *
+ * Only {@link ENV_SENSITIVE_TOOLS} pay for this; other tools get a constant.
+ *
+ * ## Resource environment (T12989)
+ *
+ * {@link captureResourceEnv} is a second, separate key input: the resource
+ * limits the run is spawned with. A run that fits in a 6 GB heap and one that
+ * does not fit in 3 GB are different runs of the same code, and keying only on
+ * source and installed state let a retry with a larger heap replay the cached
+ * 3 GB result (axiom field report, T963). It covers only what decides whether a
+ * run fits, never the whole environment, so an unrelated variable or
+ * `NODE_OPTIONS` flag never moves the key:
+ *
+ *   - the V8 heap flags in `NODE_OPTIONS` ({@link effectiveHeapFlags}), for
+ *     every tool, because every Node process a tool starts inherits them;
+ *   - for heavy tools, every variable `heavyToolEnv` manages (the per-runner
+ *     worker counts, `npm_config_workspace_concurrency`, `MAKEFLAGS`) and the
+ *     cgroup ceiling overrides (`CLEO_TOOL_MEMORY_MAX_MB`, `CLEO_NO_TOOL_CGROUP`).
+ *
+ * The heavy variable list is derived from `heavyToolEnv` itself, so a lever
+ * added there is keyed with no second list to keep in step.
+ *
+ * @task T12958
+ * @task T12989
+ */
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { heavyToolEnv, isHeavyTool } from './heavy-tool-env.js';
+import { DISABLE_ENV, MEMORY_MAX_ENV } from './heavy-tool-limit.js';
+/** Canonical tools whose result depends on installed deps or build output. */
+export const ENV_SENSITIVE_TOOLS = new Set(['test', 'build', 'typecheck']);
+/** Fingerprint for tools that read only source. */
+export const ENV_FINGERPRINT_NONE = 'none';
+/** Most `dist/` files walked before falling back to the execution root. */
+export const MAX_DIST_FILES = 100_000;
+const INSTALL_SNAPSHOTS = [
+    'node_modules/.pnpm/lock.yaml',
+    'node_modules/.package-lock.json',
+    'node_modules/.yarn-state.yml',
+    'node_modules/.yarn-integrity',
+];
+/** Directories of every tracked `package.json`, relative to `root`. */
+function workspacePackageDirs(root) {
+    try {
+        const out = execFileSync('git', ['ls-files', '-z', '--', 'package.json', '**/package.json'], {
+            cwd: root,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        return out
+            .split('\0')
+            .filter(Boolean)
+            .map((f) => dirname(f))
+            .sort();
+    }
+    catch {
+        return ['.'];
+    }
+}
+/**
+ * Append `relpath:size` for every file under `dir` to `out`, without following
+ * symlinks. Returns `false` once `out` exceeds {@link MAX_DIST_FILES}.
+ */
+function walkSizes(dir, rel, out) {
+    let names;
+    try {
+        names = readdirSync(dir).sort();
+    }
+    catch {
+        return true;
+    }
+    for (const name of names) {
+        const abs = join(dir, name);
+        const st = lstatSync(abs, { throwIfNoEntry: false });
+        if (!st)
+            continue;
+        if (st.isDirectory()) {
+            if (!walkSizes(abs, `${rel}/${name}`, out))
+                return false;
+        }
+        else {
+            out.push(`${rel}/${name}:${st.isSymbolicLink() ? 'link' : st.size}`);
+            if (out.length > MAX_DIST_FILES)
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * Fingerprint the per-checkout environment a tool run depends on.
+ *
+ * @param root - The execution root.
+ * @param canonical - Canonical tool name.
+ * @returns 32 hex chars, or {@link ENV_FINGERPRINT_NONE} for tools outside
+ *   {@link ENV_SENSITIVE_TOOLS}.
+ *
+ * @task T12958
+ */
+export function captureEnvFingerprint(root, canonical) {
+    if (!ENV_SENSITIVE_TOOLS.has(canonical))
+        return ENV_FINGERPRINT_NONE;
+    const hash = createHash('sha256');
+    const snapshot = INSTALL_SNAPSHOTS.find((p) => existsSync(join(root, p)));
+    hash.update(`install:${snapshot ?? 'none'}\n`);
+    if (snapshot)
+        hash.update(readFileSync(join(root, snapshot)));
+    const files = [];
+    for (const pkg of workspacePackageDirs(root)) {
+        if (!walkSizes(join(root, pkg, 'dist'), `${pkg}/dist`, files)) {
+            // Too large to fingerprint cheaply: do not share across checkouts.
+            let real = root;
+            try {
+                real = realpathSync(root);
+            }
+            catch {
+                // keep the lexical root
+            }
+            return createHash('sha256').update(`root:${real}`).digest('hex').slice(0, 32);
+        }
+    }
+    hash.update(files.join('\n'));
+    let entries = [];
+    try {
+        entries = readdirSync(root)
+            .filter((n) => n.startsWith('.env'))
+            .sort();
+    }
+    catch {
+        // unreadable root: no env files
+    }
+    for (const name of entries) {
+        const st = lstatSync(join(root, name), { throwIfNoEntry: false });
+        if (!st?.isFile())
+            continue;
+        hash.update(`\nenv:${name}\n`);
+        hash.update(readFileSync(join(root, name)));
+    }
+    return hash.digest('hex').slice(0, 32);
+}
+/**
+ * `NODE_OPTIONS` flags that set a V8 heap limit — the only part of
+ * `NODE_OPTIONS` that decides whether a run fits in memory. Every other flag
+ * (`--enable-source-maps`, `--experimental-*`, `--require`, …) is left out of
+ * the key: it does not change whether the run fits, and keying it would make
+ * every harness that sets one miss every other's results.
+ *
+ * @task T12989
+ */
+const HEAP_FLAG_NAMES = new Set([
+    'max-old-space-size',
+    'max-old-space-size-percentage',
+    'max-semi-space-size',
+]);
+/**
+ * The V8 heap flags in effect for a `NODE_OPTIONS` value, as `--name=value`
+ * sorted by name and joined with a space; `''` when none is set.
+ *
+ * V8 reads flags left to right and a later value replaces an earlier one, so
+ * the LAST occurrence of each flag is the effective one. Underscores in a flag
+ * name read as dashes, as they do to V8. The space-separated spelling
+ * (`--max-old-space-size 4096`) is read too, because `mergeNodeOptions` treats
+ * it as an explicit setting.
+ *
+ * @param nodeOptions - A `NODE_OPTIONS` value, if any.
+ * @returns The effective heap flags, e.g. `--max-old-space-size=6144`.
+ *
+ * @example
+ * ```ts
+ * effectiveHeapFlags('--enable-source-maps --max-old-space-size=3072 --max_old_space_size=6144');
+ * // → '--max-old-space-size=6144'
+ * effectiveHeapFlags('--enable-source-maps'); // → ''
+ * ```
+ *
+ * @task T12989
+ */
+export function effectiveHeapFlags(nodeOptions) {
+    const tokens = (nodeOptions ?? '').trim().split(/\s+/).filter(Boolean);
+    const values = new Map();
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i] ?? '';
+        if (!token.startsWith('--'))
+            continue;
+        const eq = token.indexOf('=');
+        const name = (eq === -1 ? token.slice(2) : token.slice(2, eq)).replace(/_/g, '-');
+        if (!HEAP_FLAG_NAMES.has(name))
+            continue;
+        let value = eq === -1 ? '' : token.slice(eq + 1);
+        const next = tokens[i + 1];
+        if (eq === -1 && next !== undefined && /^\d+(\.\d+)?$/.test(next)) {
+            value = next;
+            i++;
+        }
+        values.set(name, value);
+    }
+    return [...values.keys()]
+        .sort()
+        .map((name) => `--${name}=${values.get(name)}`)
+        .join(' ');
+}
+/** The keyed form of one resource variable's value. */
+function resourceValue(name, raw) {
+    const value = (raw ?? '').trim();
+    if (name === 'NODE_OPTIONS')
+        return effectiveHeapFlags(value);
+    // Inside a `make` recipe, MAKEFLAGS carries the parent's jobserver handle
+    // (`--jobserver-auth=fifo:/tmp/GMfifo<pid>`), which names the invocation,
+    // not a limit.
+    if (name === 'MAKEFLAGS') {
+        return value
+            .split(/\s+/)
+            .filter((t) => t !== '' && !t.startsWith('--jobserver-'))
+            .join(' ');
+    }
+    return value;
+}
+/**
+ * The resource limits a tool run is spawned with, as readable `NAME=value`
+ * pairs sorted by name and joined with `;` (T12989). Part of the tool-cache key
+ * and recorded on the entry, so a cached result says which heap and worker
+ * count produced it, and a retry with different limits is a different run.
+ *
+ * Reads the EFFECTIVE environment — `env` with the heavy-tool `overlay`
+ * applied, exactly as `spawnCmd` merges it — so a limit the caller exported
+ * and one `heavyToolEnv` supplied key the same way. Covers:
+ *
+ *   - `NODE_OPTIONS`, reduced to its heap flags ({@link effectiveHeapFlags}),
+ *     for every tool;
+ *   - for heavy tools only, every variable `heavyToolEnv` can set (derived by
+ *     asking it what it sets for an empty environment) plus the cgroup
+ *     ceiling overrides `CLEO_TOOL_MEMORY_MAX_MB` and `CLEO_NO_TOOL_CGROUP`.
+ *
+ * A variable outside this set does not move the key; force a fresh run with
+ * `CLEO_EVIDENCE_FRESH=1` when one matters.
+ *
+ * @param canonical - Canonical tool name.
+ * @param env - The environment the child inherits.
+ * @param overlay - The heavy-tool overlay the child is spawned with; defaults
+ *   to `heavyToolEnv(canonical, env)`. `runToolCached` passes the overlay it
+ *   spawns with, so the key and the spawn read one value.
+ * @returns e.g. `NODE_OPTIONS=--max-old-space-size=4096;VITEST_MAX_WORKERS=6;…`
+ *
+ * @task T12989
+ */
+export function captureResourceEnv(canonical, env = process.env, overlay = heavyToolEnv(canonical, env)) {
+    const effective = { ...env, ...overlay };
+    const names = new Set(['NODE_OPTIONS']);
+    if (isHeavyTool(canonical)) {
+        for (const name of Object.keys(heavyToolEnv(canonical, {})))
+            names.add(name);
+        names.add(MEMORY_MAX_ENV);
+        names.add(DISABLE_ENV);
+    }
+    return [...names]
+        .sort()
+        .map((name) => `${name}=${resourceValue(name, effective[name])}`)
+        .join(';');
+}
+//# sourceMappingURL=tool-cache-env.js.map

package/dist/tasks/tool-cache-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-cache-env.js","sourceRoot":"","sources":["../../src/tasks/tool-cache-env.ts"],"names":[],"mappings":"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"}

package/dist/tasks/tool-cache-failed-first.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Failed-first reruns for `tool:test` (T12961).
+ *
+ * When a test run fails, the failing test FILES are parsed out of the runner's
+ * output and remembered per execution root. The next test run in that root —
+ * normally after an attempted fix, so on a different tree and a cache miss —
+ * runs only those files first:
+ *
+ *   - still failing (with a parseable FAIL line) → the caller gets that red
+ *     result at once and the full run is skipped. It is NOT cached under the
+ *     full command's key — the suite did not run — and the pointer moves to
+ *     the current tree, so the next run on this same tree runs the normal
+ *     command, which decides;
+ *   - passing, or no FAIL line (a startup crash) → the normal run (full or
+ *     affected) proceeds as before.
+ *
+ * Everything here is best-effort and fails OPEN to today's behaviour: when the
+ * failing files cannot be parsed, resolved to tracked files, or mapped to a
+ * runnable vitest binary and config, no focused run is planned and the normal
+ * command runs unchanged. `CLEO_EVIDENCE_FRESH=1` skips failed-first. A
+ * focused run can only ever *shorten* a red result; it can never produce or
+ * cache a pass, because a pass always falls through to the normal command.
+ *
+ * The flake retry lives in `runToolCached`: a failing normal run is re-run in
+ * FULL once, never through a focused run.
+ *
+ * ## Why the default reporter's text, not a JSON reporter
+ *
+ * The resolved test command is the project's own (`pnpm run test`, a pinned
+ * `testing.command`, an affected-packages command). Injecting
+ * `--reporter=json --outputFile=…` into it would change the command — and
+ * therefore the cache key and the evidence identity — and does not compose
+ * with scripts that fan out (`pnpm -r test`). The `FAIL <file>` lines of the
+ * vitest and jest default reporters sit in the closing summary, which is
+ * exactly the part the 64 KiB stream tail retains.
+ *
+ * ## Why the pointer is keyed on (tool, execution root), not on the command
+ *
+ * A failing test file is a failing test file whichever command found it: a
+ * full run's failures are just as worth re-running first before an affected
+ * run, whose command (and therefore cache key) differs. Scoping by execution
+ * root keeps one agent's red files out of another worktree's runs. Even if
+ * they did cross, a focused failure is a genuine failure of THIS tree's tests.
+ *
+ * @task T12961
+ */
+/** Canonical tools that record failing files and get failed-first reruns. */
+export declare const FAILED_FIRST_TOOLS: ReadonlySet<string>;
+/**
+ * Most failing files remembered. A larger red set means the tree is broadly
+ * broken; the full run is the right next step and the pointer is dropped.
+ */
+export declare const MAX_FAILED_TEST_FILES = 100;
+/** How a failed-first stage ended. */
+export type FailedFirstOutcome = 'failed' | 'passed' | 'inconclusive';
+/**
+ * Report of the failed-first stage of one run, attached to the result (and,
+ * when the focused run decided the result, to the cache entry).
+ *
+ * @task T12961
+ */
+export interface FailedFirstReport {
+    /** Repo-relative test files that were run first. */
+    files: string[];
+    /** `failed` stops the run; `passed`/`inconclusive` continue to the normal command. */
+    outcome: FailedFirstOutcome;
+}
+/** The remembered failing files for one (tool, execution root). */
+export interface FailedFirstPointer {
+    schemaVersion: 1;
+    canonical: string;
+    executionRoot: string;
+    /** Test files relative to `executionRoot`, forward slashes. */
+    files: string[];
+    /** Tree hash of the run that failed. */
+    treeHash: string | null;
+    capturedAt: string;
+}
+/** One focused vitest invocation. */
+export interface FocusedRun {
+    /** Directory holding the vitest config the files belong to. */
+    cwd: string;
+    /** Absolute path of the vitest binary. */
+    cmd: string;
+    args: string[];
+}
+/**
+ * Raw `{base, file}` references to failing test files in runner output.
+ *
+ * @internal exported for tests
+ */
+export declare function extractFailingTestRefs(output: string): Array<{
+    base: string | null;
+    file: string;
+}>;
+/**
+ * Parse the failing test files out of a run's output and resolve each to a
+ * path relative to `executionRoot`.
+ *
+ * A reported path is tried against the `pnpm -r` package prefix, the
+ * execution root itself, and `searchBase` (the cwd of a focused run). A path
+ * none of those resolve is looked up among tracked files by suffix and kept
+ * only when exactly one matches. Unresolvable references are dropped; an empty
+ * result means "unknown" and disables failed-first for the next run.
+ *
+ * @param output - stdout and stderr of the run (ANSI allowed).
+ * @param executionRoot - Tree the run executed in.
+ * @param trackedFiles - Lazily supplied tracked-file list for suffix lookup.
+ * @param searchBase - Extra directory paths may be relative to.
+ * @returns Sorted, de-duplicated repo-relative paths; `[]` when unknown or
+ *   when more than {@link MAX_FAILED_TEST_FILES} failed.
+ *
+ * @task T12961
+ */
+export declare function parseFailingTestFiles(output: string, executionRoot: string, trackedFiles?: () => readonly string[], searchBase?: string): string[];
+/** `true` when vitest reported that the filters matched no test file. */
+export declare function reportsNoTestFiles(output: string): boolean;
+/**
+ * Plan the focused invocations that re-run `files` in `executionRoot`.
+ *
+ * Each file runs under the vitest config nearest to it — the same config a
+ * `cd <package> && vitest run <file>` would use — with the nearest
+ * `node_modules/.bin/vitest`. Files are grouped per config directory.
+ *
+ * @returns The runs, or `null` when any file is gone or has no vitest config
+ *   or binary (failed-first is then skipped; the normal command runs).
+ *
+ * @task T12961
+ */
+export declare function planFocusedRuns(files: readonly string[], executionRoot: string): FocusedRun[] | null;
+/**
+ * Path of the failed-first pointer for one (tool, execution root). Lives in
+ * the evidence cache directory, so `clearToolCache` removes it too.
+ *
+ * @param storeRoot - CLEO store root holding `.cleo/cache/evidence/`.
+ * @param canonical - Canonical tool name.
+ * @param executionRoot - Normalised execution root.
+ *
+ * @task T12961
+ */
+export declare function failedFirstPointerPath(storeRoot: string, canonical: string, executionRoot: string): string;
+/**
+ * Read the failed-first pointer, or `null` when absent or malformed.
+ *
+ * @task T12961
+ */
+export declare function readFailedFirstPointer(storeRoot: string, canonical: string, executionRoot: string): FailedFirstPointer | null;
+/**
+ * Remember `files` as the failing set, or forget it when `files` is empty.
+ * The cache directory must already exist.
+ *
+ * @task T12961
+ */
+export declare function writeFailedFirstPointer(storeRoot: string, canonical: string, executionRoot: string, files: readonly string[], treeHash: string | null): void;
+//# sourceMappingURL=tool-cache-failed-first.d.ts.map

package/dist/tasks/tool-cache-failed-first.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-cache-failed-first.d.ts","sourceRoot":"","sources":["../../src/tasks/tool-cache-failed-first.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAMH,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAqB,CAAC;AAEzE;;;GAGG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,sCAAsC;AACtC,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,QAAQ,GAAG,cAAc,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,sFAAsF;IACtF,OAAO,EAAE,kBAAkB,CAAC;CAC7B;AAED,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,CAAC,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qCAAqC;AACrC,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAqBD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,GACb,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAc9C;AAaD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,YAAY,GAAE,MAAM,SAAS,MAAM,EAAa,EAChD,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,EAAE,CAwBV;AAED,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE1D;AAsBD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,aAAa,EAAE,MAAM,GACpB,UAAU,EAAE,GAAG,IAAI,CAuBrB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,MAAM,CAMR;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,kBAAkB,GAAG,IAAI,CAmB3B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,IAAI,CAqBN"}