@cleocode/core 2026.10.1 → 2026.10.2

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

@@ -8,15 +8,27 @@
  *
  * This module wraps tool execution with:
  *
- *   1. **Content-addressed cache** — keyed on `(canonical, cmd, args, head,
- *      dirtyFingerprint)`. Cache hits return the prior `exitCode + stdoutTail`
- *      without spawning the tool.
+ *   1. **Content-addressed cache** — keyed on `(canonical, cmd, args,
+ *      treeHash)`, where `treeHash` is the git tree of the tracked content as
+ *      it sits in the working tree (T12958, see {@link captureTreeHash}).
+ *      Cache hits return the prior `exitCode + stdoutTail` without spawning
+ *      the tool. Two worktrees holding the same content, or a commit, rebase
+ *      or amend that leaves the tree unchanged, share one result.
  *   2. **Cross-process semaphore** — when N processes simultaneously miss the
  *      cache, only one runs the tool; the rest block on a `proper-lockfile`
  *      and read the freshly-written cache entry.
- *   3. **Automatic invalidation** — entries become stale when `git HEAD`
- *      changes or when uncommitted-tree fingerprint changes. Stale entries
- *      are discarded on access (no GC daemon required).
+ *   3. **Automatic invalidation** — entries become unreachable as soon as the
+ *      tracked content changes, because the key moves with it. Nothing is
+ *      deleted on access (no GC daemon required).
+ *   4. **Failed-first reruns** — a failing `test` run remembers its failing
+ *      test files; the next run re-runs those first and stops if they still
+ *      fail (T12961, see `tool-cache-failed-first.ts`). A failing run is
+ *      re-run in full once; a pass then is recorded as `flaky`.
+ *   5. **Resource kills are not results** — a run killed by a signal, an
+ *      exit of 128 + a kill signal, or a heap OOM is returned but never
+ *      cached, and the key includes the heap and worker limits the run was
+ *      given, so a retry with more memory always runs (T12989, see
+ *      {@link resourceKillReason}).
  *
  * Cache layout (under `<projectRoot>/.cleo/cache/evidence/`):
  *
@@ -29,6 +41,7 @@
  * @task T1534
  * @adr ADR-061
  */
+import { type FailedFirstReport } from './tool-cache-failed-first.js';
 import type { ResolvedToolCommand } from './tool-resolver.js';
 import { type AcquireSlotOptions } from './tool-semaphore.js';
 /**
@@ -41,20 +54,18 @@ export interface ToolCacheEntry {
      * Schema version for forwards compatibility.
      *
      * Bumped 1 -> 2 by gh#1419, which added {@link ToolCacheEntry.executionRoot}
-     * to the run's identity. Every entry written before that field existed is
-     * refused wholesale by {@link readCacheEntry} on this one comparison.
-     *
-     * That is the mechanism gh#1380 and gh#1404 each rebuilt by hand. Both
-     * needed to retire entries already on disk in consumers' caches, and both
-     * did it with a bespoke null-check on the field they had just added —
-     * `exitCode === null`, then `head === null` — while this field, whose entire
-     * purpose is to retire incompatible entries, stayed at 1 through both.
-     * Two defects, two hand-written retirement clauses, one unused version
-     * counter sitting between them.
+     * to the run's identity, 2 -> 3 by T12958, which replaced HEAD + dirty
+     * fingerprint + execution root with the tree hash, and 3 -> 4 by T12989,
+     * which added {@link ToolCacheEntry.resourceEnv}. Every entry written under
+     * an older identity is refused wholesale by {@link readCacheEntry} on this
+     * one comparison — the retirement mechanism gh#1380 and gh#1404 each rebuilt
+     * by hand with a bespoke null-check on the field they had just added.
      *
      * @task T12190 (gh#1419)
+     * @task T12958
+     * @task T12989
      */
-    schemaVersion: 2;
+    schemaVersion: typeof TOOL_CACHE_SCHEMA_VERSION;
     /** Cache key (also encoded in the filename). */
     key: string;
     /** Canonical tool name from the resolver. */
@@ -67,28 +78,61 @@ export interface ToolCacheEntry {
     args: string[];
     /** Resolution source from the resolver. */
     source: string;
-    /** Git HEAD sha at execution time. */
+    /**
+     * Git tree object of the tracked content the run measured — HEAD's tree with
+     * every uncommitted tracked change applied (see {@link captureTreeHash}).
+     *
+     * This is the run's content IDENTITY and the only repo-state input to the
+     * key (T12958). It replaced `head` + `dirtyFingerprint` + `executionRoot`,
+     * which named WHERE and AFTER WHICH COMMIT a run happened rather than WHAT it
+     * measured, so every worktree and every commit missed — including an empty
+     * commit or a rebase that left the content byte-identical.
+     *
+     * The tree object is written to the repository's (shared) object database,
+     * so a hit stays auditable after the worktree that produced it is deleted:
+     * `git ls-tree <treeHash>` shows exactly the content that ran.
+     *
+     * @task T12958
+     */
+    treeHash: string | null;
+    /**
+     * Fingerprint of the per-checkout environment the run depended on — the
+     * installed-lockfile snapshot, workspace `dist/` file sizes and `.env*`
+     * content (see `tool-cache-env.ts`). `'none'` for tools that read only
+     * source. Part of the key.
+     *
+     * @task T12958
+     */
+    envFingerprint: string;
+    /**
+     * The resource limits the run was spawned with, as readable `NAME=value`
+     * pairs: the heap flags in `NODE_OPTIONS` and, for heavy tools, every worker
+     * count and memory lever `heavyToolEnv` manages (see `captureResourceEnv` in
+     * `tool-cache-env.ts`). Part of the key, so a retry with a larger heap or
+     * fewer workers is a different run rather than a hit on the old result, and
+     * a cached result says which limits produced it.
+     *
+     * @task T12989
+     */
+    resourceEnv: string;
+    /** Git HEAD sha at execution time. Informational since T12958: NOT keyed. */
     head: string | null;
-    /** sha256 of `git diff HEAD` — CONTENT of the uncommitted tracked changes (gh#1452). */
-    dirtyFingerprint: string | null;
     /**
      * Absolute, symlink-resolved path of the tree the tool actually ran in.
      *
-     * Part of the run's IDENTITY (see {@link TOOL_RUN_IDENTITY_FIELDS}), so it
-     * is in the cache key: two clean worktrees at the same HEAD no longer
-     * collide. They used to by construction — a clean tree's
-     * `dirtyFingerprint` is the empty-input hash in every worktree, so the old
-     * key `{canonical, cmd, args, head, dirtyFingerprint}` was byte-identical
-     * across them.
+     * Recorded for audit, NOT part of the key since T12958. gh#1419 keyed it to
+     * stop two worktrees at one HEAD sharing a result while their content
+     * differed; the tree hash keys on the content itself, so two trees share a
+     * result exactly when they hold the same tracked content, which is the case
+     * sharing is correct for. Nothing the tool returns depends on the directory
+     * name: the command and args are keyed, and script resolution is a function
+     * of the tracked `package.json` content the tree hash covers.
      *
-     * Stored as well as keyed, so a hit can be AUDITED. Before this field,
-     * `ToolCacheEntry` carried no directory at all: a field survey of 259 tool
-     * entries found 0 that could say which tree produced them, and 8 that had
-     * been produced in worktrees since deleted — every one `exitCode: 0` and
-     * still servable, which makes the evidence unfalsifiable rather than merely
-     * stale. Nobody can go and look.
+     * The gh#1419 "unfalsifiable after the worktree is deleted" concern is met by
+     * {@link ToolCacheEntry.treeHash}: the content is a git object, not a path.
      *
      * @task T12190 (gh#1419)
+     * @task T12958
      */
     executionRoot: string;
     /** Process exit code. */
@@ -100,6 +144,15 @@ export interface ToolCacheEntry {
      * it; absent and `null` both mean "not killed by a signal".
      */
     signal?: NodeJS.Signals | null;
+    /**
+     * Why the run is not a verdict on the code: it was killed for resources
+     * ({@link resourceKillReason}). An entry that carries it is never served or
+     * persisted ({@link isEntryUsable}); it appears only on the `entry` of the
+     * result that reports the kill.
+     *
+     * @task T12989
+     */
+    resourceKill?: string;
     /** Last 512 bytes of stdout. */
     stdoutTail: string;
     /** Last 512 bytes of stderr. */
@@ -108,6 +161,50 @@ export interface ToolCacheEntry {
     durationMs: number;
     /** ISO 8601 wall-clock timestamp of the run. */
     capturedAt: string;
+    /**
+     * Test files (relative to the execution root) that failed in this run, when
+     * the tool is `test`, the run failed and the runner's output named them.
+     * Absent when unknown.
+     *
+     * @task T12961
+     */
+    failedTestFiles?: string[];
+    /**
+     * Present when a failed-first stage ran before this result. An entry whose
+     * `failedFirst.outcome` is `failed` was decided by the focused rerun alone:
+     * the previously failing files still failed, so the normal command was
+     * never spawned. A failing subset is a failing suite, which is why that
+     * result is cached under the normal command's key.
+     *
+     * @task T12961
+     */
+    failedFirst?: FailedFirstReport;
+    /**
+     * Test files that failed and then passed on their single retry (T12961).
+     * Present only on a PASSING entry: the run counts as a pass, but a flaky
+     * pass, which is visible here rather than indistinguishable from a clean
+     * one.
+     *
+     * @task T12961
+     */
+    flaky?: string[];
+    /**
+     * The tail of the first, failing run's output when the entry is a flaky
+     * pass — the audit trail of what failed before the rerun passed.
+     *
+     * @task T12961
+     */
+    flakyFailureTail?: string;
+    /**
+     * `focused`: this record describes a failed-first run of only
+     * {@link ToolCacheEntry.ranFiles}, not the recorded command. Such records
+     * are returned to the caller but never persisted under the command's key.
+     *
+     * @task T12961
+     */
+    scope?: 'focused';
+    /** The test files a `scope: 'focused'` run executed. */
+    ranFiles?: string[];
 }
 /**
  * Result of {@link runToolCached}. Mirrors the legacy `validateTool`
@@ -130,6 +227,11 @@ export interface ToolRunResult {
     durationMs: number;
     /** `true` when the result came from cache (no spawn occurred). */
     cacheHit: boolean;
+    /**
+     * Git tree of the source this result measured ({@link captureTreeHash});
+     * `null` off git. Exposed so evidence atoms can bind to it (T12958).
+     */
+    treeHash: string | null;
     /**
      * `true` when the wall-clock child-process deadline was exceeded and the
      * tool was terminated before producing a result. The lock + semaphore
@@ -179,6 +281,28 @@ export interface ToolRunResult {
      * @task T12116 (gh#1397)
      */
     harnessFailure: string | null;
+    /**
+     * Why the run was killed for resources ({@link resourceKillReason}), else
+     * `null`: a signal, an exit of 128 + a kill signal, or output reporting a
+     * heap OOM. Non-null means the exit code is not a verdict on the code and
+     * nothing was cached; a retry runs again, and a retry with a larger heap or
+     * fewer workers runs under a different key. `null` too when `timedOut` or
+     * `harnessFailure` already explains the non-result.
+     *
+     * @task T12989
+     */
+    resourceKill: string | null;
+    /**
+     * The failed-first stage of this run (T12961), when one ran: which files
+     * were re-run first and whether they decided the result.
+     */
+    failedFirst?: FailedFirstReport;
+    /**
+     * Test files from the first, failing run when its one full rerun passed
+     * (T12961). Set only on a pass: it marks a FLAKY pass, distinct from a
+     * clean one, for evidence atoms and gates to surface.
+     */
+    flaky?: string[];
     /** Full cache entry — useful for audit / debugging. */
     entry: ToolCacheEntry;
 }
@@ -193,10 +317,9 @@ export interface RunToolOptions {
      * written to cache for subsequent calls.
      *
      * When omitted, `CLEO_EVIDENCE_FRESH=1` in the environment turns this on.
-     * That is the documented escape hatch for the tracked-only fingerprint
-     * (see {@link captureDirtyFingerprint}): an uncommitted NEW file does not
-     * move the cache key, so this is how an operator forces a measured run
-     * without committing first.
+     * It is the escape hatch for anything the key cannot see — a change under
+     * an excluded or gitignored path, or environment state outside the
+     * fingerprint. It also skips failed-first reruns (T12961).
      *
      * @defaultValue `false` (or `CLEO_EVIDENCE_FRESH === '1'`)
      * @task T12112 (gh#1221)
@@ -264,7 +387,32 @@ export interface RunToolOptions {
      * @task T12112 (gh#1220, gh#1226, gh#1230)
      */
     executionRoot?: string;
+    /**
+     * How long a caller that finds this key's lock held waits for the holder's
+     * result before giving up with `lockBusy` (T12958). The holder is running
+     * the identical command on identical content, so waiting and reusing its
+     * result is always cheaper than running in parallel.
+     *
+     * @defaultValue 3 × the spawn deadline + 60 s (focused rerun + normal run
+     *   + one flake retry)
+     */
+    lockWaitMs?: number;
+    /**
+     * Poll interval while waiting on a held lock.
+     *
+     * @defaultValue `1_000`
+     * @internal
+     */
+    lockPollMs?: number;
 }
+/**
+ * Most failing test files a failed `test` run may name and still get its one
+ * full flake retry (T12961). More, or none named, is treated as a
+ * deterministic failure: no retry.
+ *
+ * @task T12961
+ */
+export declare const MAX_FLAKE_RETRY_FILES = 3;
 /**
  * Default wall-clock deadline for one evidence-tool child process, in ms.
  *
@@ -388,9 +536,32 @@ export declare function resolveSpawnTimeoutMs(canonical: string, env?: NodeJS.Pr
  * {@link isEntryUsable} (gh#1380: an unknown outcome must never be cached).
  * Putting it here would key the cache on its own answer.
  *
+ * `head` and `executionRoot` are recorded on every entry but are no longer
+ * identity (T12958). Both name a LOCATION — which commit, which directory —
+ * rather than the content measured, so keying on them made every worktree and
+ * every commit a miss even when the tracked content was byte-identical.
+ * `treeHash` is the content itself; it subsumes the old `dirtyFingerprint`.
+ * `envFingerprint` covers the per-checkout state git does not see (installed
+ * deps, gitignored build output, `.env*`), so sharing across worktrees
+ * happens only when BOTH the source and the environment match.
+ * `resourceEnv` (T12989) covers the limits the run was spawned with — heap
+ * flags and worker counts — which neither the tree nor the checkout shows: a
+ * 3 GB run that ran out of memory and a 6 GB retry of the same code are two
+ * runs, and keying them as one is what replayed the OOM.
+ *
  * @task T12190 (gh#1419)
+ * @task T12958
+ * @task T12989
  */
-export declare const TOOL_RUN_IDENTITY_FIELDS: readonly ["canonical", "cmd", "args", "head", "dirtyFingerprint", "executionRoot"];
+export declare const TOOL_RUN_IDENTITY_FIELDS: readonly ["canonical", "cmd", "args", "treeHash", "envFingerprint", "resourceEnv"];
+/**
+ * Current {@link ToolCacheEntry.schemaVersion}. Entries of any other version
+ * are refused on read.
+ *
+ * @task T12958
+ * @task T12989
+ */
+export declare const TOOL_CACHE_SCHEMA_VERSION = 4;
 /**
  * The identity half of a {@link ToolCacheEntry} — the inputs that determine
  * which run it is, independent of what that run produced.
@@ -399,43 +570,53 @@ export declare const TOOL_RUN_IDENTITY_FIELDS: readonly ["canonical", "cmd", "ar
  */
 export type ToolRunIdentity = Pick<ToolCacheEntry, (typeof TOOL_RUN_IDENTITY_FIELDS)[number]>;
 /**
- * Compute the cache key for a resolved tool command + repo state.
+ * Compute the cache key for a resolved tool command + tracked tree content.
  *
  * The key covers exactly {@link TOOL_RUN_IDENTITY_FIELDS} — canonical tool
- * name, resolved command and args, git HEAD, dirty-tree fingerprint, and the
- * normalised execution root. Fields are projected in the order that array
- * declares, so the hashed payload is a function of the array and adding a
- * field there changes every key by construction.
+ * name, resolved command and args, the tree hash, the environment
+ * fingerprint and the resource environment. Fields are projected in
+ * the order that array declares, so the hashed payload is a function of the
+ * array and adding a field there changes every key by construction.
  *
- * `executionRoot` is a REQUIRED parameter, deliberately. A defaulted one
- * would let every callsite that was not updated keep computing the old,
- * colliding key while the type-checker reported success — which is the exact
- * shape of the defect this fixes, since `executionRoot` already existed and
- * already reached this function's caller.
+ * There is deliberately no directory parameter (T12958): two checkouts with
+ * the same tracked content get the same key, which is what lets parallel
+ * worktrees and post-rebase re-verifies reuse one run.
  *
  * Using `createHash('sha256')` makes the key collision-resistant and bounded
  * to 32 hex chars regardless of input size.
  *
+ * @param command - Resolved tool command.
+ * @param treeHash - {@link captureTreeHash} of the execution root.
+ * @param envFingerprint - {@link captureEnvFingerprint} of the execution root.
+ * @param resourceEnv - {@link captureResourceEnv} of the spawn environment.
+ * @returns 32 hex chars.
+ *
  * @task T1534
  * @task T12190 (gh#1419)
+ * @task T12958
+ * @task T12989
  */
-export declare function computeCacheKey(command: ResolvedToolCommand, head: string | null, dirtyFingerprint: string | null, executionRoot: string): string;
+export declare function computeCacheKey(command: ResolvedToolCommand, treeHash: string | null, envFingerprint: string, resourceEnv: string): string;
 /**
  * Whether a cache entry may be SERVED or PERSISTED as a real result.
  *
  * One predicate, used by both {@link readCacheEntry} and the persist guard in
- * `runToolCached`, so the two cannot drift apart. Two rules:
+ * `runToolCached`, so the two cannot drift apart. Three rules:
  *
  *   1. every field in {@link TOOL_RUN_IDENTITY_FIELDS} is present and
  *      non-null — an entry that cannot say which run it describes is not
  *      evidence of anything;
  *   2. `exitCode` is non-null — a run that produced no exit code records that
  *      we do not know what happened, and an unknown must never be cached
- *      (gh#1380).
+ *      (gh#1380);
+ *   3. `resourceKill` is absent — a run killed for resources (an OOM, a heap
+ *      limit, exit 137) has a real exit code that says nothing about the code,
+ *      and caching it replays the kill to every retry, including one given
+ *      the memory it lacked (T12989).
  *
  * Rule 1 subsumes gh#1404's `head === null` clause without naming `head`:
- * when the tool runs off a non-git root both git fields are null on EVERY
- * run, so the key is a function of the command alone and nothing a developer
+ * when the tool runs off a non-git root `treeHash` is null on EVERY run, so
+ * the key is a function of the command alone and nothing a developer
  * does to the source can rotate it. That is not a cache, it is a hardcoded
  * answer with a filename — and unlike gh#1380 it holds a real exit code,
  * which can be a PASS. A poisoned red is investigated within minutes; nobody
@@ -446,8 +627,76 @@ export declare function computeCacheKey(command: ResolvedToolCommand, head: stri
  * getting valid caching today — they are getting one answer forever.
  *
  * @task T12190 (gh#1419)
+ * @task T12989
  */
 export declare function isEntryUsable(entry: Partial<ToolCacheEntry>): boolean;
+/**
+ * Why a finished run was killed for resources, or `null` when its outcome is
+ * a real result.
+ *
+ * Decides from the exit and the captured output, in order:
+ *
+ *   1. a terminating `signal` — the process did not exit on its own;
+ *   2. an exit code of `128 + n` for a {@link KILL_SIGNALS} signal — the same
+ *      kill, reported by a wrapper (`sh` exits 137 for a `SIGKILL`ed child);
+ *   3. a non-zero exit whose output carries a {@link RESOURCE_KILL_MARKERS}
+ *      marker — vitest catches a worker's heap OOM and exits 1.
+ *
+ * Exit 0 is always a result, and so is a plain non-zero exit such as a failing
+ * assertion's 1: that red stays cacheable for failed-first reruns. A run that
+ * never started (`exitCode` and `signal` both null) is not a kill; it is
+ * reported, and refused by {@link isEntryUsable}, as an unknown outcome.
+ *
+ * @param run - The finished run's exit code, signal and captured output.
+ * @returns A short reason, e.g. `exit 137 (128 + SIGKILL)`, or `null`.
+ *
+ * @example
+ * ```ts
+ * resourceKillReason({ exitCode: 1, signal: null, stdout: '', stderr: 'FAIL a.test.ts' }); // null
+ * resourceKillReason({ exitCode: 137, signal: null, stdout: '', stderr: '' });
+ * // → 'exit 137 (128 + SIGKILL)'
+ * ```
+ *
+ * @task T12989
+ */
+export declare function resourceKillReason(run: {
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+}): string | null;
+/** Signals whose default action would end cleo and orphan the tool groups it started. */
+declare const TERMINATION_SIGNALS: readonly ["SIGHUP", "SIGINT", "SIGTERM"];
+/** A signal {@link terminateToolGroupsOnSignal} handles. */
+type TerminationSignal = (typeof TERMINATION_SIGNALS)[number];
+/**
+ * SIGTERM every tool group this process started, then re-raise the signal to
+ * this process so it ends exactly as it would have without us (T12963).
+ *
+ * Tools run detached, in their own process group, so a signal that ends cleo
+ * (Ctrl-C reaches only the terminal's foreground group) never reaches them:
+ * the tool kept running, and the slot it held looked free once cleo was gone.
+ *
+ * Any listener at all suppresses a signal's default action, and
+ * `proper-lockfile` loads `signal-exit`, which re-raises only when its own
+ * listeners are the last ones left. So ours removes itself and re-raises:
+ * `signal-exit` then releases its locks and the process dies by the signal.
+ * Another listener of the signal sees it twice.
+ *
+ * @param signal - The signal received.
+ *
+ * @internal Exported for tests.
+ * @task T12963
+ */
+export declare function terminateToolGroupsOnSignal(signal: TerminationSignal): void;
+/**
+ * The `exit` listener: SIGTERM every tool group still running. `exit`
+ * listeners must be synchronous, and `process.kill` is.
+ *
+ * @internal Exported for tests.
+ * @task T12963
+ */
+export declare function terminateToolGroupsOnExit(): void;
 /**
  * Capture the repo's git HEAD sha. Returns `null` when the directory is not
  * a git checkout or the command fails.
@@ -456,6 +705,62 @@ export declare function isEntryUsable(entry: Partial<ToolCacheEntry>): boolean;
  */
 export declare function captureHead(projectRoot: string): Promise<string | null>;
 export declare function captureDirtyFingerprint(projectRoot: string): Promise<string | null>;
+/**
+ * Untracked files larger than this are left out of {@link captureTreeHash}
+ * rather than hashed into the object database on every call. Such files are
+ * rarely source; a change to one does not move the key (force a run with
+ * `CLEO_EVIDENCE_FRESH=1`).
+ */
+export declare const MAX_UNTRACKED_HASH_BYTES: number;
+/**
+ * Capture the git tree hash of the working tree's SOURCE content: HEAD's tree
+ * with every uncommitted change applied — staged or not, to tracked files and
+ * to untracked files that are not gitignored. Returns `null` for non-git
+ * roots or on any git failure (the entry is then unusable and nothing is
+ * cached).
+ *
+ * ## How (T12958)
+ *
+ * 1. Copy the checkout's own index to a private temporary file, preserving
+ *    its atime/mtime. The copy keeps the index's stat cache, so git re-hashes
+ *    only files whose stat changed. The preserved mtime matters: git's
+ *    racy-clean check compares each entry's mtime with the INDEX FILE's
+ *    mtime, and a fresh mtime on the copy would let a same-size edit made in
+ *    the same timestamp tick as the last index write read as clean. The real
+ *    index is never touched.
+ * 2. `GIT_INDEX_FILE=<copy> git add -u -- .` stages every modified or deleted
+ *    TRACKED path — all of them, including tracked files under `.cleo/`.
+ * 3. `git ls-files -o --exclude-standard -z` lists untracked, not-ignored
+ *    files; those that are not runtime output ({@link isUntrackedRuntimeOutput})
+ *    and not over {@link MAX_UNTRACKED_HASH_BYTES} are added with
+ *    `git update-index --add -z --stdin`.
+ * 4. `GIT_INDEX_FILE=<copy> git write-tree` prints the tree.
+ *
+ * A clean checkout yields exactly `HEAD^{tree}`. Two worktrees with the same
+ * source yield the same hash wherever they live, and an empty commit, an
+ * amend of only the message, or a rebase that reproduces the same content
+ * leave it unchanged.
+ *
+ * ## Untracked files (review of #1774, supersedes the gh#1221 tracked-only rule)
+ *
+ * An untracked, not-ignored file IS part of the hash. Tracked-only was safe
+ * while the key also carried the execution root; once the key is shared
+ * across worktrees it is a false pass: a worker's new, uncommitted module and
+ * failing test leave the tracked tree equal to main's, and main's cached pass
+ * would be served without the worker's tests ever running.
+ *
+ * Side effect: staging writes blob objects for dirty and new files into the
+ * repository's object database, and `write-tree` writes tree objects. Both
+ * are ordinary unreferenced loose objects: `git gc` prunes them after
+ * `gc.pruneExpire` (two weeks by default), so `git ls-tree <treeHash>` as an
+ * audit of an old entry is best-effort.
+ *
+ * @param root - Directory to fingerprint (the execution root).
+ * @returns 40/64 hex chars of the tree object id, or `null`.
+ *
+ * @task T12958
+ */
+export declare function captureTreeHash(root: string): Promise<string | null>;
 /**
  * Resolve the absolute path for a cache entry by key.
  *
@@ -483,12 +788,23 @@ export declare function writeCacheEntry(projectRoot: string, entry: ToolCacheEnt
  *
  * Flow:
  *
- *   1. Compute cache key (canonical+cmd+args+head+dirtyFingerprint).
+ *   1. Compute cache key (canonical+cmd+args+treeHash+envFingerprint+
+ *      resourceEnv).
  *   2. If a fresh entry exists → return it (no spawn).
- *   3. Acquire a `proper-lockfile` on the cache entry path.
+ *   3. Acquire a `proper-lockfile` on the cache entry path. When another
+ *      caller holds it (same command, same content — possibly another
+ *      worktree), wait for its result and reuse it (T12958).
  *   4. Re-check cache inside the lock (another process may have written it
  *      while we were waiting).
- *   5. Spawn the tool, capture stdout/stderr tails, write the entry, return.
+ *   5. For `test`, when the previous run in this execution root failed on a
+ *      different tree, re-run only its failing files first; if they still
+ *      fail, return that (uncached, `scope: 'focused'`) failure without the
+ *      normal run (T12961).
+ *   6. Spawn the tool, capture stdout/stderr tails. For a failing `test`,
+ *      re-run the FULL command once; a pass there is a pass marked `flaky`
+ *      (T12961). Write the entry, return. A run killed for resources is
+ *      returned with `resourceKill` set and is neither retried, recorded for
+ *      failed-first, nor written (T12989).
  *
  * Locks are auto-released on success or failure. Stale locks are reaped per
  * the `lockStaleMs` option (default 10 min — long enough to cover a full
@@ -500,6 +816,9 @@ export declare function writeCacheEntry(projectRoot: string, entry: ToolCacheEnt
  * @returns Result envelope with `exitCode`, `stdoutTail`, `cacheHit`, etc.
  *
  * @task T1534
+ * @task T12958
+ * @task T12961
+ * @task T12989
  * @adr ADR-061
  */
 export declare function runToolCached(command: ResolvedToolCommand, projectRoot: string, opts?: RunToolOptions): Promise<ToolRunResult>;
@@ -511,4 +830,5 @@ export declare function runToolCached(command: ResolvedToolCommand, projectRoot:
 export declare function clearToolCache(projectRoot: string): {
     removed: number;
 };
+export {};
 //# sourceMappingURL=tool-cache.d.ts.map

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

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