@cleocode/core 2026.9.20 → 2026.9.21

package/dist/tasks/gate-runner.js

@@ -12,20 +12,26 @@
  *
  * Design constraints:
  *   - Each gate is self-contained (no cross-gate state).
- *   - Gates run sequentially under the original shared deadline (two seconds by default).
- *   - Per-gate timeouts can only tighten the shared deadline. Long work needs runtime admission.
+ *   - Gates run sequentially under ONE captured operation deadline. The caller admits it
+ *     with {@link typedGateAdmissionMs}: the ADR-061 tool deadline of every executing gate
+ *     plus {@link TYPED_GATE_BOOKKEEPING_MS} for the surrounding bookkeeping (T12516).
+ *   - Per-gate timeouts can only tighten the captured deadline, never renew it.
+ *   - Passing process gates can be served from the ADR-061 evidence cache
+ *     (`options.cache`, see `gate-result-cache.ts`); failures are never cached (T12621).
  *   - Structured test-count evidence and HTTP service startup require separate capabilities.
  *   - Results are observations; this module does not persist completion authority.
  *
  * @epic T760
  * @task T781
  */
-import { createHash, randomUUID } from 'node:crypto';
-import { constants } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { constants, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync, } from 'node:fs';
 import { lstat, open, realpath, stat } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { acceptanceGateResultSchema, acceptanceGateSchema, testCountReportSchema, } from '@cleocode/contracts';
+import { gitToplevel } from '../git/work-tree.js';
 import { getProjectRoot } from '../paths.js';
 import { captureProjectScope, worktreeScope } from '../project-scope.js';
 import { truncateString } from '../render/helpers.js';
@@ -33,14 +39,237 @@ import { captureWrapped } from '../resources/spawn-wrapper.js';
 import { createAttachmentStore } from '../store/attachment-store.js';
 import { registerTeardownAbort } from '../teardown-signal.js';
 import { acItemToText, acTextHash } from './ac-table.js';
+import { resolveCanonicalProjectRoot } from './evidence.js';
+import { buildGateCacheEntryBody, captureGateCacheState, evidenceCacheKeyPath, gateCacheEntryPath, readGateCacheEntry, sealGateCacheEntry, } from './gate-result-cache.js';
 import { heavyToolEnv } from './heavy-tool-env.js';
+import { resolveSpawnTimeoutMs } from './tool-cache.js';
 // ─── Constants ────────────────────────────────────────────────────────────────
-/** Default gate timeout in milliseconds. Overridden by env or per-gate `timeoutMs`. */
-const DEFAULT_TIMEOUT_MS = Number(process.env['CLEO_GATE_TIMEOUT_MS'] ?? 60_000);
+/**
+ * Shared budget for the bookkeeping around typed gates: task and criterion
+ * reads, input snapshots, result binding and the persisting transaction.
+ *
+ * It is the same two seconds the maintenance paths use, and it is ADDED to the
+ * tool deadlines rather than bounding them. Before T12516 it was the whole
+ * lifetime of a typed verification, so any gate whose tool ran longer than two
+ * seconds — every real test suite — stopped with `E_OPERATION_DEADLINE`.
+ *
+ * @task T12516
+ */
+export const TYPED_GATE_BOOKKEEPING_MS = 2000;
+/** Gate kinds that execute a tool (a process or a request) and so carry an ADR-061 deadline. */
+const TOOL_GATE_KINDS = new Set([
+    'test',
+    'command',
+    'lint',
+    'http',
+]);
 /** Maximum evidence string character count retained per gate result. */
 const MAX_EVIDENCE_CHARS = 2_000;
 /** Agent identifier written into `checkedBy`. */
 const CHECKED_BY = process.env['CLEO_AGENT_ID'] ?? 'cleo-verify';
+/**
+ * Resolve the wall-clock deadline for one gate's tool execution.
+ *
+ * Precedence: the gate's own `timeoutMs`; then the legacy blanket
+ * `CLEO_GATE_TIMEOUT_MS`; then the ADR-061 tool deadline for the gate kind,
+ * resolved by {@link resolveSpawnTimeoutMs} — `CLEO_TOOL_TIMEOUT_<KIND>`, else
+ * 1,800,000 ms for `test` and 300,000 ms for every other kind.
+ *
+ * @param gate - Gate whose tool deadline is needed.
+ * @param env - Environment to read the overrides from.
+ * @returns Deadline in milliseconds.
+ * @throws When a declared or configured deadline is not a positive safe integer.
+ * @example
+ * ```typescript
+ * resolveGateTimeoutMs({ kind: 'test', description: 'suite', command: 'npm', args: ['test'], expect: 'exit0' }); // 1_800_000
+ * ```
+ * @task T12516
+ */
+export function resolveGateTimeoutMs(gate, env = process.env) {
+    const legacy = env['CLEO_GATE_TIMEOUT_MS']?.trim();
+    const timeout = gate.timeoutMs ??
+        (legacy ? Number(legacy) : undefined) ??
+        resolveSpawnTimeoutMs(gate.kind, env);
+    if (!Number.isSafeInteger(timeout) || timeout < 1)
+        throw new Error('Gate timeout must be a positive safe integer');
+    return timeout;
+}
+/**
+ * Wall-clock lifetime to admit for running a set of typed gates.
+ *
+ * The sum of every tool-executing gate's ADR-061 deadline plus
+ * {@link TYPED_GATE_BOOKKEEPING_MS}. Callers that own the operation lifetime
+ * create it with this budget so the two-second shared budget covers the
+ * bookkeeping only and never bounds a tool (T12516).
+ *
+ * @param gates - Gates that will run.
+ * @param env - Environment to read deadline overrides from.
+ * @returns Budget in milliseconds, clamped to the safe-integer range.
+ * @throws When a gate deadline override is invalid (see {@link resolveGateTimeoutMs}).
+ * @example
+ * ```typescript
+ * const execution = createOperationExecutionContext(identity, { budgetMs: typedGateAdmissionMs(gates) });
+ * ```
+ * @task T12516
+ */
+export function typedGateAdmissionMs(gates, env = process.env) {
+    const total = gates.reduce((sum, gate) => sum + (TOOL_GATE_KINDS.has(gate.kind) ? resolveGateTimeoutMs(gate, env) : 0), TYPED_GATE_BOOKKEEPING_MS);
+    return Math.min(total, Number.MAX_SAFE_INTEGER);
+}
+/**
+ * Actionable refusal for `cache: 'only'` (`cleo verify --no-run`) when a gate
+ * would have to execute. Names the gate and the command that fills the cache.
+ */
+function gateNotCachedMessage(gate, cacheable, keyAvailable) {
+    const name = gate.req ?? gate.description;
+    if (gate.kind === 'http')
+        return `${GATE_NOT_CACHED_PREFIX} http gate "${name}" observes a live service and is never cached; drop --no-run to execute it`;
+    if (!cacheable)
+        return `${GATE_NOT_CACHED_PREFIX} gate "${name}" has no cached result because the project root is not a git checkout (results are keyed by HEAD + dirty-tree fingerprint); drop --no-run to execute it`;
+    if (!keyAvailable)
+        return `${GATE_NOT_CACHED_PREFIX} gate "${name}" cannot use the cache because the machine key ${evidenceCacheKeyPath()} is unreadable; drop --no-run to execute it`;
+    return (`${GATE_NOT_CACHED_PREFIX} gate "${name}" has no cached pass for the current HEAD, working tree and inputs. ` +
+        'Run `cleo verify <taskId> --run` first (it caches passing results), or drop --no-run to execute it now');
+}
+/**
+ * Prefix of the `errorMessage` a gate carries when `cache: 'only'` refused to
+ * execute it. The verifier matches it to refuse the whole write with
+ * `E_GATE_NOT_CACHED` instead of recording an `error` result.
+ * @task T12621
+ */
+export const GATE_NOT_CACHED_PREFIX = '--no-run:';
+/**
+ * Prefix of the `errorMessage` a gate carries when `cache: 'only'` found an
+ * entry that failed authentication. The verifier refuses the write with
+ * `E_GATE_CACHE_INVALID`: a forged or tampered pass is never recorded.
+ * @task T12621
+ */
+export const GATE_CACHE_INVALID_PREFIX = '--no-run [invalid cache entry]:';
+/**
+ * Load (creating on first use, mode 0600) the per-machine key that seals
+ * evidence cache entries. Deliberately NOT exported: a caller that could load
+ * the key through core could seal any result it liked, which is the forgery
+ * this key exists to stop. Returns `null` when the key cannot be established;
+ * the cache is then simply not used.
+ */
+function loadEvidenceCacheKey() {
+    const path = evidenceCacheKeyPath();
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        try {
+            writeFileSync(path, randomBytes(32).toString('hex'), { flag: 'wx', mode: 0o600 });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        const hex = readFileSync(path, 'utf-8').trim();
+        return /^[0-9a-f]{64}$/.test(hex) ? Buffer.from(hex, 'hex') : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Seal and store a pass this runner EXECUTED itself. Module-private for the same
+ * reason as {@link loadEvidenceCacheKey}: only an observed execution is cached.
+ */
+function writeExecutedGatePass(projectRoot, gate, state, inputsHash, observed, key) {
+    const body = buildGateCacheEntryBody(gate, state, inputsHash, observed);
+    if (!body)
+        return;
+    try {
+        const path = gateCacheEntryPath(projectRoot, gate, state, inputsHash);
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(sealGateCacheEntry(body, key), null, 2), 'utf-8');
+        renameSync(tmp, path);
+    }
+    catch {
+        // A cache is an optimisation: failing to persist one never fails the gate.
+    }
+}
+/**
+ * Digest of a gate's captured invocation and input artifacts: the part of its
+ * cache key that the git fingerprint cannot see (untracked harness scripts,
+ * task files, the environment hash).
+ */
+function gateInputsHash(invocation, artifacts) {
+    return createHash('sha256')
+        .update(JSON.stringify({ invocation: invocation ?? null, artifacts }))
+        .digest('hex');
+}
+/**
+ * Compute a gate's cache inputs digest the same way the attesting verifier does.
+ * @param task - Task that owns the gate; its `files` are verifier inputs.
+ * @param gate - Gate whose invocation and inputs are captured.
+ * @param execution - Admitted lifetime whose project root scopes the capture.
+ * @param env - Environment the gate will launch with.
+ * @returns Digest to pass as `cacheInputsHash` to {@link runGates}.
+ * @example
+ * ```typescript
+ * const cacheInputsHash = await captureGateInputsHash(task, gate, execution);
+ * ```
+ * @task T12621
+ */
+export async function captureGateInputsHash(task, gate, execution, env = process.env) {
+    const tree = resolveTypedGateRoot(resolve(execution.identity.projectRoot));
+    const invocation = executableInvocation(gate, tree, { ...env });
+    return gateInputsHash(invocation, await snapshotGateInputs(task, gate, invocation, execution, tree));
+}
+/**
+ * The tree a typed gate runs in and is fingerprinted against.
+ *
+ * `projectRoot` is the CLEO store root, which for a git worktree is the MAIN
+ * checkout (all worktrees share one `.cleo/`). Evidence tools already run in the
+ * caller's own worktree (gh#1220); typed gates ran in the store root, so from a
+ * worktree `cleo done` measured the task's code with its tools and the main
+ * checkout with its typed gates (T12625 review). The caller's git toplevel is
+ * used only when it is a linked worktree OF THIS project — any other cwd
+ * (an unrelated repo, a test harness, a declared child repo in a multi-repo
+ * root) keeps `projectRoot`, so typed-gate paths written against the CLEO root
+ * keep resolving exactly as before.
+ *
+ * Known limit (documented, accepted): "linked worktree of this project" is read
+ * from the `.git` gitlink, so a plain directory carrying a forged gitlink that
+ * points into this project's `.git/worktrees/` is treated as a worktree. That
+ * grants nothing a copy of the checkout would not: its typed results are only
+ * carried to another tree by content (tracked inputs must hash identically and
+ * the recorded HEAD must be merged there).
+ *
+ * @param projectRoot - CLEO store root (the typed gate's authority).
+ * @param cwd - Invocation directory. Defaults to `process.cwd()`.
+ * @returns The realpath of the tree typed gates execute in.
+ * @task T12625
+ */
+export function resolveTypedGateRoot(projectRoot, cwd = process.cwd()) {
+    const real = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return resolve(p);
+        }
+    };
+    const root = real(projectRoot);
+    const top = gitToplevel(cwd);
+    if (top === null || real(top) === root)
+        return projectRoot;
+    return real(resolveCanonicalProjectRoot(top)) === root ? real(top) : projectRoot;
+}
+/**
+ * Admission for a batch run without a caller-owned lifetime.
+ * An invalid deadline override is not swallowed: {@link runOneGate} resolves it
+ * again and reports it as that gate's `error` result, as it always has.
+ */
+function unownedAdmissionMs(gates, env) {
+    try {
+        return typedGateAdmissionMs(gates, env);
+    }
+    catch {
+        return TYPED_GATE_BOOKKEEPING_MS;
+    }
+}
 /**
  * Execute all typed `AcceptanceGate` entries and return results.
  *
@@ -79,14 +308,16 @@ export async function runGates(gates, options = {}) {
     const maxOutputBytes = options.maxOutputBytes ?? 1_048_576;
     if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 1)
         throw new RangeError('Gate capture byte limit must be a positive safe integer');
+    // T12625: execute and fingerprint in the caller's worktree of this project.
+    const treeRoot = resolveTypedGateRoot(projectRoot);
     const snapshot = structuredClone(gates);
     const controller = new AbortController();
     const deregister = registerTeardownAbort(controller);
     const batch = {
-        cwd: projectRoot,
+        cwd: treeRoot,
         env: { ...(options.env ?? process.env) },
         execution: {
-            deadlineAt: execution?.deadlineAt ?? Date.now() + 2000,
+            deadlineAt: execution?.deadlineAt ?? Date.now() + unownedAdmissionMs(snapshot, options.env),
             signal: execution
                 ? AbortSignal.any([execution.signal, controller.signal])
                 : controller.signal,
@@ -97,6 +328,15 @@ export async function runGates(gates, options = {}) {
         systemdControl: options.systemdControl,
     };
     const checkedBy = execution?.identity.actor ?? batch.env['CLEO_AGENT_ID'] ?? CHECKED_BY;
+    const cacheMode = options.cache ?? 'off';
+    const cacheInputsHash = options.cacheInputsHash;
+    if (cacheMode !== 'off' && (snapshot.length !== 1 || !cacheInputsHash))
+        throw new Error('Typed gate caching requires one gate per batch and its inputs digest');
+    // T12621: the repo state is captured only when the policy reads or writes.
+    const cacheState = cacheMode !== 'off' && TOOL_GATE_KINDS.has(snapshot[0].kind)
+        ? await captureGateCacheState(treeRoot)
+        : null;
+    const cacheKey = cacheState ? loadEvidenceCacheKey() : null;
     const results = [];
     try {
         return await worktreeScope.run(scope, async () => {
@@ -113,7 +353,34 @@ export async function runGates(gates, options = {}) {
                     const parsed = acceptanceGateSchema.parse(gate);
                     if (!isDeepStrictEqual(parsed, gate))
                         throw new Error('Gate includes unsupported or noncanonical fields');
-                    results.push(await runOneGate(parsed, i, projectRoot, options.skipManual ?? true, batch));
+                    if (cacheState && cacheKey && (cacheMode === 'use' || cacheMode === 'only')) {
+                        const lookup = readGateCacheEntry(projectRoot, parsed, cacheState, cacheInputsHash, cacheKey);
+                        if (lookup.status === 'hit') {
+                            // Re-dated to now (the reuse is this run's check; a bound result
+                            // may not precede its input capture) and marked, never disguised.
+                            results.push({
+                                ...lookup.observation,
+                                index: i,
+                                checkedAt: new Date().toISOString(),
+                                source: 'cache',
+                                cachedAt: lookup.createdAt,
+                            });
+                            continue;
+                        }
+                        // `use` treats an unauthenticated entry as a miss and overwrites it.
+                        if (lookup.status === 'invalid' && cacheMode === 'only')
+                            throw new Error(`${GATE_CACHE_INVALID_PREFIX} gate "${parsed.req ?? parsed.description}": ${lookup.reason}. ` +
+                                'It was not used. Drop --no-run to execute the gate (a pass replaces the entry)');
+                    }
+                    if (cacheMode === 'only' && TOOL_GATE_KINDS.has(parsed.kind))
+                        throw new Error(gateNotCachedMessage(parsed, cacheState !== null, cacheKey !== null));
+                    const observed = {
+                        ...(await runOneGate(parsed, i, treeRoot, options.skipManual ?? true, batch, projectRoot)),
+                        source: 'executed',
+                    };
+                    if (cacheState && cacheKey && cacheMode !== 'only')
+                        writeExecutedGatePass(projectRoot, parsed, cacheState, cacheInputsHash, observed, cacheKey);
+                    results.push(observed);
                 }
                 catch (error) {
                     results.push(makeResult(i, gate, 'error', Date.now() - startMs, undefined, error instanceof Error ? error.message : String(error)));
@@ -126,6 +393,151 @@ export async function runGates(gates, options = {}) {
         deregister();
     }
 }
+/** `git` read in `cwd`; `null` on a non-zero exit or when git is unavailable. */
+function gitOut(cwd, args) {
+    try {
+        return execFileSync('git', args, {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** Digest of a gate's inputs with every path made relative to `tree` (T12625). */
+function treeInputsHash(tree, invocation, artifacts) {
+    const rel = (path) => relative(tree, path) || '.';
+    return createHash('sha256')
+        .update(JSON.stringify({
+        invocation: invocation ? { ...invocation, cwd: rel(invocation.cwd) } : null,
+        artifacts: artifacts.map((a) => ({ ...a, path: rel(a.path) })),
+    }))
+        .digest('hex');
+}
+/**
+ * Content binding for a result verified in `tree`, or `undefined` when the tree
+ * is not a git checkout (the result then keeps exact path-bound revalidation).
+ */
+function captureTreeBinding(tree, invocation, artifacts) {
+    const headSha = gitOut(tree, ['rev-parse', 'HEAD']);
+    if (headSha === null || !/^[0-9a-f]{40}$/.test(headSha))
+        return undefined;
+    const dirty = gitOut(tree, ['status', '--porcelain', '--untracked-files=no']);
+    const base = originDefault(tree);
+    const baseSha = base ? gitOut(tree, ['merge-base', base, headSha]) : null;
+    return {
+        headSha,
+        clean: dirty === '',
+        cwd: invocation ? relative(tree, invocation.cwd) || '.' : '.',
+        inputsHash: treeInputsHash(tree, invocation, artifacts),
+        ...(baseSha && /^[0-9a-f]{40}$/.test(baseSha) ? { baseSha } : {}),
+    };
+}
+/** `origin/<default>` from `origin/HEAD`, else origin/main or origin/master. */
+function originDefault(tree) {
+    const symbolic = gitOut(tree, ['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD']);
+    if (symbolic)
+        return symbolic.replace(/^refs\/remotes\//, '');
+    for (const ref of ['origin/main', 'origin/master']) {
+        if (gitOut(tree, ['rev-parse', '--verify', '--quiet', `refs/remotes/${ref}`]) !== null)
+            return ref;
+    }
+    return null;
+}
+/**
+ * A typed result was verified in another tree of this project and cannot be
+ * accepted from the completing tree. Carries the exact re-verify command.
+ *
+ * @task T12625
+ */
+export class TypedRevalidationError extends Error {
+    /** The command that re-verifies the task's typed gates in the completing tree. */
+    fix;
+    constructor(message, fix) {
+        super(message);
+        this.name = 'TypedRevalidationError';
+        this.fix = fix;
+    }
+}
+/** Exact command that re-records testsPassed (re-running typed gates) in `tree`. */
+function reverifyCommand(task, tree) {
+    const atoms = (task.verification?.evidence?.testsPassed?.atoms ?? []).flatMap((atom) => {
+        switch (atom.kind) {
+            case 'tool':
+                return [`tool:${atom.tool}`];
+            case 'test-run':
+                return [`test-run:${atom.path}`];
+            case 'satisfies':
+                return [
+                    `satisfies:${atom.targetTaskId}#${atom.targetAcAlias ?? atom.resolvedAcUuid ?? ''}`,
+                ];
+            default:
+                return [];
+        }
+    });
+    const evidence = atoms.length > 0 ? atoms.join(';') : 'tool:test';
+    return `cd '${tree.replace(/'/g, `'\\''`)}' && cleo verify ${task.id} --gate testsPassed --evidence '${evidence}'`;
+}
+/**
+ * Accept a result bound in ANOTHER tree of this project (T12625): the verified
+ * tree was clean, its HEAD is an ancestor of the completing HEAD (the verified
+ * commit has been merged here), and the inputs recompute to the same
+ * tree-relative digest. The recorded tree itself is never entered — worktrees
+ * are auto-cleaned after merge.
+ */
+function assertTreeEquivalent(task, gateLabel, bound, tree, projectRoot, invocation, artifacts) {
+    const fix = reverifyCommand(task, tree);
+    const real = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return resolve(p);
+        }
+    };
+    if (real(resolveCanonicalProjectRoot(tree)) !== real(projectRoot))
+        throw new TypedRevalidationError(`Typed requirement ${gateLabel}: ${tree} is not a checkout of this project`, fix);
+    if (!bound.clean)
+        throw new TypedRevalidationError(`Typed requirement ${gateLabel} was verified on a dirty tree at ${bound.headSha.slice(0, 12)}; its result cannot be carried to ${tree}`, fix);
+    if (gitOut(tree, ['merge-base', '--is-ancestor', bound.headSha, 'HEAD']) === null)
+        throw new TypedRevalidationError(`Typed requirement ${gateLabel} was verified at ${bound.headSha.slice(0, 12)}, which is not in ${tree}'s HEAD — merge the verified commit first, or re-verify here`, fix);
+    if (treeInputsHash(tree, invocation, artifacts) !== bound.inputsHash)
+        throw new TypedRevalidationError(`Typed requirement ${gateLabel} inputs changed since verification (${tree})`, fix);
+    // Round 3: the merge being an ancestor proves the change ARRIVED, not that it
+    // is still there — a later revert leaves the ancestry and the declared gate
+    // inputs intact. Every path the verified change touched must still hold the
+    // verified bytes here. Without a recorded fork point the change set is
+    // unknown, so the result is not carried across trees at all.
+    if (!bound.baseSha)
+        throw new TypedRevalidationError(`Typed requirement ${gateLabel} has no recorded fork point, so the verified change cannot be compared in ${tree}`, fix);
+    // --no-renames: a rename is listed as the old path's deletion AND the new
+    // path's addition, so a renamed-away path later re-added here is caught.
+    const changed = gitOut(tree, [
+        'diff',
+        '--name-only',
+        '--no-renames',
+        bound.baseSha,
+        bound.headSha,
+    ]);
+    if (changed === null)
+        throw new TypedRevalidationError(`Typed requirement ${gateLabel}: cannot read the verified change ${bound.baseSha.slice(0, 12)}..${bound.headSha.slice(0, 12)} in ${tree}`, fix);
+    const paths = changed.split('\n').filter(Boolean);
+    if (paths.length > 0) {
+        const drift = gitOut(tree, [
+            'diff',
+            '--name-only',
+            '--no-renames',
+            bound.headSha,
+            'HEAD',
+            '--',
+            ...paths,
+        ]);
+        if (drift === null || drift !== '')
+            throw new TypedRevalidationError(`Typed requirement ${gateLabel}: the verified change was changed on ${tree} since verification: ${(drift ?? 'unreadable').split('\n').join(', ')}`, fix);
+    }
+}
 /**
  * Run task requirements with their canonical AC and bounded input snapshots.
  * @param task - Captured task, including its complete mixed acceptance array.
@@ -154,6 +566,7 @@ export async function runTaskGates(task, criteria, options) {
     assertCriterionProjection(snapshot, rows);
     const env = { ...(options.env ?? process.env) };
     const verificationId = randomUUID();
+    const tree = resolveTypedGateRoot(root);
     return worktreeScope.run(scope, async () => {
         const results = [];
         for (const [index, gate] of (snapshot.acceptance ?? []).entries()) {
@@ -161,8 +574,8 @@ export async function runTaskGates(task, criteria, options) {
                 continue;
             execution.assertActive();
             const capturedAt = new Date().toISOString();
-            const invocation = executableInvocation(gate, root, env);
-            const artifacts = await snapshotGateInputs(snapshot, gate, invocation, execution);
+            const invocation = executableInvocation(gate, tree, env);
+            const artifacts = await snapshotGateInputs(snapshot, gate, invocation, execution, tree);
             const binding = {
                 version: 1,
                 verificationId,
@@ -176,10 +589,21 @@ export async function runTaskGates(task, criteria, options) {
                 ...(invocation ? { invocation } : {}),
                 artifacts,
             };
-            const observed = (await runGates([gate], { ...options, projectRoot: root, env, execution }))[0];
+            const treeBinding = captureTreeBinding(tree, invocation, artifacts);
+            if (treeBinding)
+                binding.tree = treeBinding;
+            const observed = (await runGates([gate], {
+                ...options,
+                projectRoot: root,
+                env,
+                execution,
+                ...(options.cache && options.cache !== 'off'
+                    ? { cacheInputsHash: gateInputsHash(invocation, artifacts) }
+                    : {}),
+            }))[0];
             let result = { ...observed, index, binding };
             try {
-                const after = await snapshotGateInputs(snapshot, gate, invocation, execution);
+                const after = await snapshotGateInputs(snapshot, gate, invocation, execution, tree);
                 if (!isDeepStrictEqual(after, artifacts))
                     throw new Error('Verification inputs changed during execution');
             }
@@ -229,11 +653,16 @@ export function createTaskGateReceipt(results, passed) {
         indexes.add(result.index);
         criteria.add(binding.criterionId);
     }
+    const cached = results
+        .filter((result) => result.source === 'cache')
+        .map((result) => ({ index: result.index, cachedAt: result.cachedAt }));
     return {
         verificationId: first.verificationId,
         resultHash: createHash('sha256').update(JSON.stringify(results)).digest('hex'),
         operation: 'check.gate.verify',
         passed,
+        // T12621: omitted when nothing was reused, so earlier receipts still match.
+        ...(cached.length > 0 ? { cached } : {}),
     };
 }
 /**
@@ -263,6 +692,7 @@ export async function revalidateTaskGateResults(task, criteria, results, options
     const rows = [...criteria].sort((a, b) => a.ordinal - b.ordinal);
     assertCriterionProjection(task, rows);
     const env = { ...(options.env ?? process.env) };
+    const tree = resolveTypedGateRoot(root);
     await worktreeScope.run(scope, async () => {
         for (const [index, gate] of (task.acceptance ?? []).entries()) {
             if (typeof gate === 'string' || (requirePassing && gate.advisory))
@@ -285,12 +715,22 @@ export async function revalidateTaskGateResults(task, criteria, results, options
                 binding.criterionHash !== acTextHash(rows[index].text) ||
                 binding.gateHash !== createHash('sha256').update(acItemToText(gate)).digest('hex'))
                 throw new Error(`Typed requirement ${gate.req ?? index} binding is stale or belongs to another owner`);
-            const invocation = executableInvocation(gate, root, env);
+            const invocation = executableInvocation(gate, tree, env);
+            const artifacts = await snapshotGateInputs(task, gate, invocation, execution, tree);
+            const exact = isDeepStrictEqual(binding.invocation, invocation) &&
+                isDeepStrictEqual(binding.artifacts, artifacts);
+            if (exact)
+                continue;
+            // T12625: a result bound in another tree of this project (a worker's
+            // worktree) is accepted by CONTENT, not by path. Pre-T12625 receipts carry
+            // no tree binding and keep the exact path-bound refusals below.
+            if (binding.tree) {
+                assertTreeEquivalent(task, gate.req ?? String(index), binding.tree, tree, root, invocation, artifacts);
+                continue;
+            }
             if (!isDeepStrictEqual(binding.invocation, invocation))
                 throw new Error(`Typed requirement ${gate.req ?? index} invocation or environment changed`);
-            const artifacts = await snapshotGateInputs(task, gate, invocation, execution);
-            if (!isDeepStrictEqual(binding.artifacts, artifacts))
-                throw new Error(`Typed requirement ${gate.req ?? index} input bytes changed after verification`);
+            throw new Error(`Typed requirement ${gate.req ?? index} input bytes changed after verification`);
         }
     });
 }
@@ -300,6 +740,7 @@ export async function revalidateTaskGateResults(task, criteria, results, options
  * @param criteria - Normalized criteria from that same transaction.
  * @param options - Captured original execution lifetime and project scope.
  * @param accessor - Canonical receipt reader bound to the same project store.
+ * @param policy - Project evidence policy; `allowCachedGates: false` refuses cached passes (T12621).
  * @returns Resolves only when every hard typed requirement has current authentic proof.
  * @throws When typed representations, results, inputs or canonical receipts disagree.
  * @remarks Callers retain transaction ownership and must check their execution context before
@@ -310,8 +751,20 @@ export async function revalidateTaskGateResults(task, criteria, results, options
  * await validateTaskGateCompletion(task, rows, { execution }, accessor);
  * ```
  */
-export async function validateTaskGateCompletion(task, criteria, options, accessor) {
+export async function validateTaskGateCompletion(task, criteria, options, accessor, policy = {}) {
     const results = task.verification?.gateResults ?? [];
+    // T12621: `evidence.allowCachedGates: false` — a hard typed requirement must
+    // have been executed, not reused from the evidence cache.
+    if (policy.allowCachedGates === false) {
+        for (const [index, gate] of (task.acceptance ?? []).entries()) {
+            if (typeof gate === 'string' || gate.advisory)
+                continue;
+            const reused = results.find((result) => result.index === index && result.source === 'cache');
+            if (reused)
+                throw new Error(`Typed requirement ${gate.req ?? index} passed from the evidence cache (cached ${reused.cachedAt}) ` +
+                    'and this project sets evidence.allowCachedGates to false; re-verify so the gate executes');
+        }
+    }
     await revalidateTaskGateResults(task, criteria, results, options);
     if (!(task.acceptance ?? []).some((item) => typeof item !== 'string' && !item.advisory))
         return;
@@ -373,8 +826,10 @@ function executableInvocation(gate, root, env) {
     };
 }
 /** Capture declared task inputs and an interpreter's explicit harness argument. */
-async function snapshotGateInputs(task, gate, invocation, execution) {
-    const root = resolve(execution.identity.projectRoot);
+async function snapshotGateInputs(task, gate, invocation, execution, 
+/** T12625: the tree the gate runs in ({@link resolveTypedGateRoot}). */
+treeRoot = resolve(execution.identity.projectRoot)) {
+    const root = resolve(treeRoot);
     if (invocation) {
         const cwdRelative = relative(root, invocation.cwd);
         if (cwdRelative === '..' || cwdRelative.startsWith('../') || isAbsolute(cwdRelative))
@@ -483,15 +938,15 @@ function assertGateActive(context) {
         throw new Error('Gate did not finish: original shared deadline expired. This is NOT a failure verdict.');
 }
 // ─── Internal dispatcher ──────────────────────────────────────────────────────
-async function runOneGate(gate, index, projectRoot, skipManual, context) {
-    const timeout = gate.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    if (!Number.isSafeInteger(timeout) || timeout < 1)
-        throw new Error('Gate timeout must be a positive safe integer');
+async function runOneGate(gate, index, projectRoot, skipManual, context, 
+/** CLEO store root for attachment lookups; defaults to `projectRoot`. */
+storeRoot = projectRoot) {
+    const timeout = resolveGateTimeoutMs(gate, context.env ?? process.env);
     switch (gate.kind) {
         case 'test':
             return runTestGate(gate, index, projectRoot, timeout, context);
         case 'file':
-            return runFileGate(gate, index, projectRoot, context);
+            return runFileGate(gate, index, projectRoot, context, storeRoot);
         case 'command':
             return runCommandGate(gate, index, projectRoot, timeout, context);
         case 'lint':
@@ -671,13 +1126,13 @@ async function runTestGate(gate, index, projectRoot, timeoutMs, context) {
         : `Exit code ${captured.exitCode}`);
 }
 // ─── File gate ────────────────────────────────────────────────────────────────
-async function runFileGate(gate, index, projectRoot, context) {
+async function runFileGate(gate, index, projectRoot, context, storeRoot = projectRoot) {
     const startMs = Date.now();
     let attachmentBytes;
     let filePath;
     if (gate.attachmentSha256) {
         const store = createAttachmentStore();
-        const metadata = await store.getMetadata(gate.attachmentSha256, projectRoot);
+        const metadata = await store.getMetadata(gate.attachmentSha256, storeRoot);
         assertGateActive(context);
         if (!metadata)
             return makeResult(index, gate, 'fail', Date.now() - startMs, undefined, 'Attachment not found');
@@ -686,7 +1141,7 @@ async function runFileGate(gate, index, projectRoot, context) {
             throw new Error('Attachment gate requires declared byte size for bounded retrieval');
         if (attachment.size > (context.maxOutputBytes ?? 1_048_576))
             throw new Error('Attachment gate exceeds declared byte limit');
-        const result = await store.get(gate.attachmentSha256, projectRoot);
+        const result = await store.get(gate.attachmentSha256, storeRoot);
         assertGateActive(context);
         if (!result)
             throw new Error('Attachment metadata exists but authenticated bytes are unavailable');