@cleocode/core 2026.9.3 → 2026.9.5

package/dist/tasks/tool-cache.js

@@ -31,13 +31,13 @@
  */
 import { execFileSync, spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { ExitCode } from '@cleocode/contracts';
 import { CleoError } from '../errors.js';
 import { withLock } from '../store/lock.js';
 import { heavyToolEnv } from './heavy-tool-env.js';
-import { withMemoryLimit } from './heavy-tool-limit.js';
+import { confinementStartupFailure, isSystemdRunCommand, withMemoryLimit, } from './heavy-tool-limit.js';
 import { acquireGlobalSlot } from './tool-semaphore.js';
 // ---------------------------------------------------------------------------
 // Wall-clock deadline resolution (T12105 / gh#1193)
@@ -156,30 +156,152 @@ export function resolveSpawnTimeoutMs(canonical, env = process.env) {
 // ---------------------------------------------------------------------------
 // Cache key derivation
 // ---------------------------------------------------------------------------
+/**
+ * The fields that establish WHICH RUN a cache entry describes.
+ *
+ * This list is the single source of truth for three things that must agree
+ * and previously did not, because each was maintained by hand:
+ *
+ *   1. what {@link computeCacheKey} hashes,
+ *   2. what {@link readCacheEntry} requires before serving an entry,
+ *   3. what `runToolCached` requires before persisting one.
+ *
+ * ## Why this exists rather than a fourth guard clause
+ *
+ * Three defects in three releases, each invisible to the detector written for
+ * the one before it:
+ *
+ * | | gh#1380 (2026.9.2) | gh#1404 (2026.9.3) | gh#1419 (this) |
+ * |---|---|---|---|
+ * | signature | `exitCode: null` | real code, `head: null` | well-formed, genuinely succeeded |
+ * | wrong how | never ran | key cannot rotate | ran, on the wrong tree |
+ * | detector | all-null | real code + null head | neither matches |
+ *
+ * Each fix added one `if` naming one field, to two separate guards — the read
+ * path and the write path — that encode the same rule in different code with
+ * nothing asserting they agree. A fourth defect means a fourth pair of `if`s,
+ * and the pair for defect five is the one somebody edits only half of.
+ *
+ * The recurring mistake is not any of the three fields. It is that a field
+ * could be added to {@link ToolCacheEntry} without being added to the key:
+ * `executionRoot` was threaded all the way through execution by T12112 and
+ * never reached `computeCacheKey`, so the tool correctly ran in worktree A
+ * and its result was then served to worktree B under an identical key. The
+ * execution half of that fix landed; the caching half did not.
+ *
+ * Deriving all three consumers from this one array makes that specific
+ * mistake unavailable: a field added here is keyed, required on read, and
+ * required on write, together or not at all.
+ *
+ * ## What is deliberately NOT here
+ *
+ * `exitCode` is a RESULT, not an identity — it is what the run produced, not
+ * which run it was. It has its own non-null requirement in
+ * {@link isEntryUsable} (gh#1380: an unknown outcome must never be cached).
+ * Putting it here would key the cache on its own answer.
+ *
+ * @task T12190 (gh#1419)
+ */
+export const TOOL_RUN_IDENTITY_FIELDS = [
+    'canonical',
+    'cmd',
+    'args',
+    'head',
+    'dirtyFingerprint',
+    'executionRoot',
+];
+/**
+ * Normalise an execution root to a stable, comparable absolute path.
+ *
+ * Symlinks are resolved so that two spellings of one directory produce one
+ * key — the safe direction, since collapsing an alias can only merge entries
+ * that genuinely describe the same tree, while failing to collapse it would
+ * split one tree's cache across spellings. A path that cannot be resolved
+ * (it has been deleted) falls back to lexical resolution rather than
+ * throwing: callers of {@link computeCacheKey} must be able to compute the
+ * key of a run whose directory is already gone, precisely so
+ * {@link readCacheEntry} can then refuse it.
+ *
+ * @task T12190 (gh#1419)
+ */
+function normalizeExecutionRoot(executionRoot) {
+    try {
+        return realpathSync(executionRoot);
+    }
+    catch {
+        return resolve(executionRoot);
+    }
+}
 /**
  * Compute the cache key for a resolved tool command + repo state.
  *
- * Key includes:
- *   - Canonical tool name
- *   - Resolved command + args (sensitive to project-context updates)
- *   - Git HEAD sha (so a new commit invalidates everything)
- *   - Dirty-tree fingerprint (so an uncommitted edit invalidates everything)
+ * 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.
+ *
+ * `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.
  *
  * Using `createHash('sha256')` makes the key collision-resistant and bounded
- * to 64 hex chars regardless of input size.
+ * to 32 hex chars regardless of input size.
  *
  * @task T1534
+ * @task T12190 (gh#1419)
  */
-export function computeCacheKey(command, head, dirtyFingerprint) {
-    const payload = JSON.stringify({
+export function computeCacheKey(command, head, dirtyFingerprint, executionRoot) {
+    const identity = {
         canonical: command.canonical,
         cmd: command.cmd,
         args: command.args,
         head,
         dirtyFingerprint,
-    });
+        executionRoot: normalizeExecutionRoot(executionRoot),
+    };
+    // Projected through TOOL_RUN_IDENTITY_FIELDS rather than written as an
+    // object literal: the literal is what drifted from the entry shape before.
+    const payload = JSON.stringify(TOOL_RUN_IDENTITY_FIELDS.map((f) => identity[f]));
     return createHash('sha256').update(payload).digest('hex').slice(0, 32);
 }
+/**
+ * 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:
+ *
+ *   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).
+ *
+ * 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
+ * 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
+ * debugs a passing gate.
+ *
+ * The cost is stated rather than hidden: a project whose CLEO root is not a
+ * git checkout gets no tool-result caching at all. Such projects are not
+ * getting valid caching today — they are getting one answer forever.
+ *
+ * @task T12190 (gh#1419)
+ */
+export function isEntryUsable(entry) {
+    for (const field of TOOL_RUN_IDENTITY_FIELDS) {
+        const value = entry[field];
+        if (value === null || value === undefined)
+            return false;
+    }
+    return entry.exitCode !== null && entry.exitCode !== undefined;
+}
 /**
  * Maximum bytes retained from a child's stdout / stderr stream during
  * spawn. The tool-evidence atom only needs the trailing 512 bytes for
@@ -322,18 +444,29 @@ function spawnCmd(cmd, args, cwd, spawnTimeoutMs, envOverlay) {
             if (forceKillTimer !== undefined)
                 clearTimeout(forceKillTimer);
         };
+        let spawnError = null;
         const finalise = (exitCode, signal) => {
             clearTimers();
+            const stderr = stderrBuf.toString();
             resolve({
                 exitCode,
                 signal,
                 stdout: stdoutBuf.toString(),
-                stderr: stderrBuf.toString(),
+                // gh#1397: a child that never started wrote nothing to stderr, so the
+                // spawn error IS the only diagnostic that exists. Folding it in here
+                // means every downstream consumer gets the reason without each one
+                // having to remember a second field.
+                stderr: spawnError !== null && stderr === '' ? spawnError : stderr,
                 timedOut,
+                spawnError,
             });
         };
         // A genuine pre-start failure: ENOENT, EACCES, EAGAIN. No signal, no code.
-        child.on('error', () => {
+        // gh#1397: keep the reason. `(null, null)` says only "nothing ran"; the
+        // error object says which of missing / not-executable / out-of-resources
+        // it was, and the caller has no other source for that fact.
+        child.on('error', (err) => {
+            spawnError = err.code ? `${err.code}: ${err.message}` : err.message;
             finalise(null, null);
         });
         // gh#1381: `close` passes `(code, signal)` and exactly one is non-null.
@@ -373,7 +506,8 @@ export async function captureHead(projectRoot) {
 }
 /**
  * Capture a fingerprint of the uncommitted TRACKED tree by sha256-hashing
- * `git status --porcelain=v1 --untracked-files=no`. Returns `null` for
+ * `git diff HEAD` over tracked paths (gh#1452 — see the note on the body for
+ * why NOT `git status --porcelain`). Returns `null` for
  * non-git roots.
  *
  * Two repos with identical tracked content but different uncommitted edits
@@ -409,31 +543,82 @@ export async function captureHead(projectRoot) {
  * @task T1534
  * @task T12112 (gh#1221)
  */
+/**
+ * Pathspec shared by the fingerprint command.
+ *
+ * CLEO's own runtime state is excluded so a tracked-and-modified CLEO file
+ * cannot self-invalidate the cache it is the key for.
+ */
+const FINGERPRINT_PATHSPEC = [
+    '--',
+    '.',
+    ':(exclude).cleo/cache',
+    ':(exclude).cleo/cache/**',
+    ':(exclude).cleo/audit',
+    ':(exclude).cleo/audit/**',
+    ':(exclude).cleo/backups',
+    ':(exclude).cleo/backups/**',
+    ':(exclude).cleo/session-journals',
+    ':(exclude).cleo/session-journals/**',
+    ':(exclude).cleo/*.db',
+    ':(exclude).cleo/*.db-wal',
+    ':(exclude).cleo/*.db-shm',
+];
+/**
+ * Run `git` and hash its stdout as it arrives, without ever holding the whole
+ * output in memory.
+ *
+ * gh#1452: this exists instead of `spawnCmd` because `spawnCmd` accumulates
+ * stdout in a {@link TailBuffer} capped at {@link STREAM_TAIL_CAP_BYTES}
+ * (64 KiB) and **keeps only the tail**. That is correct for an error tail and
+ * catastrophic for a fingerprint: a diff longer than the cap would be hashed
+ * from its last 64 KiB only, so a change earlier in the diff would not move the
+ * key. Measured: 200 small changed files produce ~30 KB of diff, so a shared
+ * working tree reaches the cap at roughly 430 — precisely the large-dirty-tree
+ * case gh#1452 was reported from. A fix built on `spawnCmd` would pass on a
+ * small repo and fail exactly where it matters.
+ *
+ * @param args - argv after `git`.
+ * @param cwd - directory to run in.
+ * @returns 32 hex chars of sha256 over stdout, or `null` if git exited non-zero
+ *   or could not be spawned.
+ *
+ * @task T12218 (gh#1452)
+ */
+function hashGitStdout(args, cwd) {
+    return new Promise((resolve) => {
+        const hash = createHash('sha256');
+        const child = spawn('git', [...args], { cwd, stdio: ['ignore', 'pipe', 'ignore'] });
+        child.stdout?.on('data', (chunk) => hash.update(chunk));
+        child.on('error', () => resolve(null));
+        child.on('close', (code) => {
+            resolve(code === 0 ? hash.digest('hex').slice(0, 32) : null);
+        });
+    });
+}
 export async function captureDirtyFingerprint(projectRoot) {
-    const r = await spawnCmd('git', [
-        'status',
-        '--porcelain=v1',
-        // gh#1221: untracked files are the tool's own output as often as they
-        // are the operator's input; including them made every tool invalidate
-        // its own cache entry. See the docblock TRADEOFF note.
-        '--untracked-files=no',
-        '--',
-        '.',
-        ':(exclude).cleo/cache',
-        ':(exclude).cleo/cache/**',
-        ':(exclude).cleo/audit',
-        ':(exclude).cleo/audit/**',
-        ':(exclude).cleo/backups',
-        ':(exclude).cleo/backups/**',
-        ':(exclude).cleo/session-journals',
-        ':(exclude).cleo/session-journals/**',
-        ':(exclude).cleo/*.db',
-        ':(exclude).cleo/*.db-wal',
-        ':(exclude).cleo/*.db-shm',
-    ], projectRoot);
-    if (r.exitCode !== 0)
-        return null;
-    return createHash('sha256').update(r.stdout).digest('hex').slice(0, 32);
+    // gh#1452: `git diff HEAD`, NOT `git status --porcelain`.
+    //
+    // Porcelain reports WHICH paths are dirty and never WHAT is in them, so it is
+    // a summary of dirtiness rather than an identity for it. Measured in a
+    // scratch repo — a broken edit and its fix to the same tracked file both
+    // produce ` M src.ts`, hashing to the identical fingerprint. The key
+    // therefore could not rotate when a failure's cause was fixed, and the stale
+    // FAILED entry was replayed indefinitely: the reported symptom was an
+    // identical error text with `(cached)` in ~700 ms across four task ids, with
+    // the only cure being to delete the cache file by hand.
+    //
+    // `--raw` is NOT an alternative, though it looks like one: for an UNSTAGED
+    // edit git reports the destination blob as `0000000`, so
+    // `:100644 100644 4b48dee 0000000 M\ta.txt` is byte-identical before and
+    // after the fix. It is the same summary defect one layer down.
+    //
+    // Still TRACKED-only (`diff HEAD` ignores untracked), so the deliberate
+    // gh#1221 tradeoff documented above is unchanged — including its escape
+    // hatch, `CLEO_EVIDENCE_FRESH=1`. Widening this to untracked content would
+    // trade a stale-FAILED bug for the every-tool-invalidates-its-own-cache bug
+    // that tradeoff exists to prevent.
+    return hashGitStdout(['diff', 'HEAD', ...FINGERPRINT_PATHSPEC], projectRoot);
 }
 // ---------------------------------------------------------------------------
 // Cache directory + entry IO
@@ -467,47 +652,37 @@ export function readCacheEntry(projectRoot, key) {
         return null;
     try {
         const parsed = JSON.parse(readFileSync(path, 'utf-8'));
-        if (parsed.schemaVersion !== 1 || parsed.key !== key)
+        // Schema gate. Bumped to 2 by gh#1419; every entry written before
+        // `executionRoot` was part of a run's identity is refused here, on this
+        // one line. gh#1380 and gh#1404 each needed exactly this and each
+        // reimplemented it as a bespoke null-check on their own field, while this
+        // counter sat unused at 1 through both.
+        if (parsed.schemaVersion !== 2 || parsed.key !== key)
             return null;
         // A placeholder written by `runToolCached` to satisfy proper-lockfile's
         // "file must exist" requirement. It carries no real result — treat as
-        // a miss until the lock holder writes the entry.
+        // a miss until the lock holder writes the entry. Checked before the
+        // identity gate below because a placeholder legitimately has none.
         if (parsed.pending === true)
             return null;
-        // gh#1380: an entry whose run produced no exit code is not a result — it
-        // records that we do not know what happened. Refusing it on READ as well
-        // as declining to write it retires the entries already persisted by
-        // <= 2026.9.1, which cannot clean themselves up: when the tool ran off a
-        // non-git root, `head` and `dirtyFingerprint` are both null, they are part
-        // of the cache key, and a key that cannot change can never be invalidated
-        // by a commit or an edit. One signal-killed run would otherwise serve a
-        // cached "binary missing" forever, without ever spawning again — a
-        // permanent red that no amount of correct work clears.
-        if (parsed.exitCode === null || parsed.exitCode === undefined)
+        // The identity + result gate (gh#1380, gh#1404, gh#1419), derived from
+        // TOOL_RUN_IDENTITY_FIELDS rather than written out field by field, and
+        // shared verbatim with the persist guard in `runToolCached`.
+        if (!isEntryUsable(parsed))
             return null;
-        // gh#1404: an entry whose `head` is null was keyed on the command ALONE —
-        // `computeCacheKey` hashes {canonical, cmd, args, head, dirtyFingerprint},
-        // so with both git fields null nothing a developer does to the SOURCE can
-        // change the key. Editing does not. Committing does not. Only editing the
-        // tool command itself does, which is a config change, not a code change.
-        //
-        // That is not a cache; it is a hardcoded answer with a filename. And
-        // unlike gh#1380's `exitCode: null` — which fails closed and is therefore
-        // loud — this holds a REAL exit code of either sign. A cached PASS is not
-        // self-announcing: nobody debugs a passing gate.
+        // gh#1419: refuse a hit whose originating tree is GONE.
         //
-        // Measured 2026-09-14 on a project whose CLEO root sits ABOVE its git root
-        // (a supported layout — the repo was a subdirectory, so both fields were
-        // null for EVERY run, always): four entries, all `exitCode: 0`, the `test`
-        // one recording `122 files / 2557 tests` from 2026-08-07 against a suite
-        // that is now 856 files / 13,621 tests. It had stayed inert only because
-        // the tool command was later rewritten, changing `args` and therefore the
-        // key. Revert that command and `tool:test` returns 0 without spawning.
+        // Keying on `executionRoot` stops one live worktree from being served
+        // another live worktree's result. It does not address the worse case the
+        // field survey actually found: 8 entries produced in worktrees that had
+        // since been deleted, all `exitCode: 0`, all still servable. A stale
+        // result is merely wrong; a result whose tree no longer exists is
+        // UNFALSIFIABLE — there is nowhere left to go and check what ran.
         //
-        // Refused on READ as well as declining to write, because entries already
-        // on disk in every consumer's `.cleo/cache/evidence/` cannot rotate
-        // themselves out — that is the defect itself.
-        if (parsed.head === null || parsed.head === undefined)
+        // This is the one rule that is genuinely read-only. At write time the
+        // directory exists by construction, so it cannot live in `isEntryUsable`
+        // alongside the rules both paths share.
+        if (!existsSync(parsed.executionRoot))
             return null;
         return parsed;
     }
@@ -574,7 +749,7 @@ export async function runToolCached(command, projectRoot, opts = {}) {
     const bypassCache = opts.bypassCache ?? process.env['CLEO_EVIDENCE_FRESH'] === '1';
     const head = await captureHead(executionRoot);
     const dirtyFingerprint = await captureDirtyFingerprint(executionRoot);
-    const key = computeCacheKey(command, head, dirtyFingerprint);
+    const key = computeCacheKey(command, head, dirtyFingerprint, executionRoot);
     // Fast path — fresh cache hit
     if (!bypassCache) {
         const existing = readCacheEntry(projectRoot, key);
@@ -588,6 +763,7 @@ export async function runToolCached(command, projectRoot, opts = {}) {
                 cacheHit: true,
                 timedOut: false,
                 lockBusy: false,
+                harnessFailure: null,
                 executionRoot,
                 entry: existing,
             };
@@ -609,7 +785,7 @@ export async function runToolCached(command, projectRoot, opts = {}) {
     ensureCacheDir(projectRoot);
     const cachePath = cacheEntryPath(projectRoot, key);
     if (!existsSync(cachePath)) {
-        writeFileSync(cachePath, JSON.stringify({ schemaVersion: 1, key, pending: true }), 'utf-8');
+        writeFileSync(cachePath, JSON.stringify({ schemaVersion: 2, key, pending: true }), 'utf-8');
     }
     const releaseSemaphore = opts.skipGlobalSemaphore
         ? undefined
@@ -630,6 +806,7 @@ export async function runToolCached(command, projectRoot, opts = {}) {
                         cacheHit: true,
                         timedOut: false,
                         lockBusy: false,
+                        harnessFailure: null,
                         executionRoot,
                         entry: fresh,
                     };
@@ -644,7 +821,12 @@ export async function runToolCached(command, projectRoot, opts = {}) {
             // see. Denying swap is the point: the failure this guards against was
             // a throttle-and-thrash host freeze, not an OOM kill. Degrades to an
             // unwrapped spawn off Linux or without a user systemd manager.
-            const limited = withMemoryLimit(command.canonical, command.cmd, command.args);
+            const limited = withMemoryLimit(command.canonical, command.cmd, command.args, {
+                // The scope name's rootHash8 comes off the SAME execution root the
+                // cache key uses (T12112 / gh#1220), so the scope and the cache agree
+                // on what "the tree under test" means.
+                executionRoot,
+            });
             const startedAt = Date.now();
             const result = await spawnCmd(limited.cmd, [...limited.args], executionRoot, spawnTimeoutMs, heavyToolEnv(command.canonical));
             const durationMs = Date.now() - startedAt;
@@ -662,9 +844,10 @@ export async function runToolCached(command, projectRoot, opts = {}) {
                     cacheHit: false,
                     timedOut: true,
                     lockBusy: false,
+                    harnessFailure: null,
                     executionRoot,
                     entry: {
-                        schemaVersion: 1,
+                        schemaVersion: 2,
                         key,
                         canonical: command.canonical,
                         displayName: command.displayName,
@@ -673,6 +856,7 @@ export async function runToolCached(command, projectRoot, opts = {}) {
                         source: command.source,
                         head,
                         dirtyFingerprint,
+                        executionRoot,
                         exitCode: null,
                         signal: result.signal,
                         stdoutTail: '',
@@ -682,8 +866,51 @@ export async function runToolCached(command, projectRoot, opts = {}) {
                     },
                 };
             }
+            // gh#1397: CLEO wrapped this spawn itself (T12116), so a failure of
+            // the WRAPPER is CLEO's own fault and not a verdict on the project's
+            // tool. Checked before the cache entry is built because, like the
+            // `timedOut` branch above, this run produced no result to cache — and
+            // caching one would serve a fabricated "your tests failed" from a
+            // key that cannot rotate until the tree changes.
+            // `limited.confined` OR the project's own pinned wrapper: post-detection
+            // (gh#1396) CLEO declines to wrap a command that is already
+            // `systemd-run`, so `confined` is false for exactly the project whose
+            // harness failures prompted gh#1397.
+            const harnessFailure = confinementStartupFailure(result.stderr, limited.confined || isSystemdRunCommand(command.cmd));
+            if (harnessFailure !== null) {
+                return {
+                    exitCode: result.exitCode,
+                    signal: result.signal,
+                    stdoutTail: tailString(result.stdout, tailBytes),
+                    stderrTail: tailString(result.stderr, tailBytes),
+                    durationMs,
+                    cacheHit: false,
+                    timedOut: false,
+                    lockBusy: false,
+                    executionRoot,
+                    harnessFailure,
+                    entry: {
+                        schemaVersion: 2,
+                        key,
+                        canonical: command.canonical,
+                        displayName: command.displayName,
+                        cmd: command.cmd,
+                        args: command.args,
+                        source: command.source,
+                        head,
+                        dirtyFingerprint,
+                        executionRoot,
+                        exitCode: null,
+                        signal: result.signal,
+                        stdoutTail: '',
+                        stderrTail: tailString(result.stderr, tailBytes),
+                        durationMs,
+                        capturedAt: new Date().toISOString(),
+                    },
+                };
+            }
             const entry = {
-                schemaVersion: 1,
+                schemaVersion: 2,
                 key,
                 canonical: command.canonical,
                 displayName: command.displayName,
@@ -692,6 +919,7 @@ export async function runToolCached(command, projectRoot, opts = {}) {
                 source: command.source,
                 head,
                 dirtyFingerprint,
+                executionRoot,
                 exitCode: result.exitCode,
                 signal: result.signal,
                 stdoutTail: tailString(result.stdout, tailBytes),
@@ -699,27 +927,32 @@ export async function runToolCached(command, projectRoot, opts = {}) {
                 durationMs,
                 capturedAt: new Date().toISOString(),
             };
-            // gh#1380: `exitCode === null` means the process produced no exit code —
-            // it was killed by a signal, or never started. Either way we do not know
-            // whether the tool would have passed, and an unknown must never be
-            // cached. The `timedOut` branch above already returns without writing
-            // for exactly this reason; a signal kill that is NOT a CLEO timeout —
-            // the memory-scope OOM in gh#1381 — had no equivalent guard and fell
-            // through to here.
-            // gh#1380: `exitCode === null` means we do not know what happened.
-            // gh#1404: `head === null` means the key cannot rotate, so whatever is
-            // stored becomes permanent regardless of any later source change.
+            // Persist only a usable entry. `isEntryUsable` is the SAME predicate
+            // `readCacheEntry` applies, which is the point: these two guards used
+            // to be independent transcriptions of one rule — `exitCode !== null
+            // && head !== null`, written out twice — so a field added to one had
+            // to be remembered into the other. gh#1380 and gh#1404 each edited
+            // both, and nothing checked that they still agreed.
             //
-            // The second costs a project whose CLEO root is not a git checkout all
-            // tool-result caching. That is the right trade and worth stating
-            // rather than hiding: such projects are not getting valid caching
-            // today, they are getting ONE answer forever. A slow correct answer
-            // beats a fast fabricated one.
+            // What the shared predicate refuses, and why none of it is an
+            // overcorrection:
+            //   - unknown outcome (`exitCode: null`) — a signal kill, or a
+            //     failure to start. The `timedOut` branch above already returns
+            //     without writing for this reason; an OOM kill that is not a CLEO
+            //     timeout (gh#1381) had no equivalent guard and fell through here.
+            //   - unrotatable key (`head: null`) — costs a non-git CLEO root all
+            //     caching. Stated rather than hidden: those projects are not
+            //     getting valid caching today, they are getting ONE answer
+            //     forever, and a slow correct answer beats a fast fabricated one.
+            //   - unattributable run (`executionRoot` absent) — cannot occur on
+            //     this path, and is required here anyway so that read and write
+            //     stay ONE rule rather than two that happen to match today.
             //
-            // Deliberately narrow. A guard that also refused, say, non-zero exits
-            // would trade a fabricated pass for a permanent cache miss on healthy
-            // projects — the same overcorrection pointed the other way.
-            if (entry.exitCode !== null && entry.head !== null) {
+            // Deliberately narrow in the other direction too: refusing, say, all
+            // non-zero exits would trade a fabricated pass for a permanent cache
+            // miss on healthy projects — the same overcorrection pointed the
+            // other way.
+            if (isEntryUsable(entry)) {
                 writeCacheEntry(projectRoot, entry);
             }
             return {
@@ -732,6 +965,7 @@ export async function runToolCached(command, projectRoot, opts = {}) {
                 timedOut: false,
                 lockBusy: false,
                 executionRoot,
+                harnessFailure: null,
                 entry,
             };
         }, { stale: lockStaleMs, retries: 3 });
@@ -755,9 +989,10 @@ export async function runToolCached(command, projectRoot, opts = {}) {
                     cacheHit: false,
                     timedOut: false,
                     lockBusy: true,
+                    harnessFailure: null,
                     executionRoot,
                     entry: {
-                        schemaVersion: 1,
+                        schemaVersion: 2,
                         key,
                         canonical: command.canonical,
                         displayName: command.displayName,
@@ -766,6 +1001,7 @@ export async function runToolCached(command, projectRoot, opts = {}) {
                         source: command.source,
                         head,
                         dirtyFingerprint,
+                        executionRoot,
                         exitCode: null,
                         stdoutTail: '',
                         stderrTail: '',