@cleocode/core 2026.9.7 → 2026.9.9

package/dist/tasks/gate-runner.js

@@ -12,27 +12,33 @@
  *
  * Design constraints:
  *   - Each gate is self-contained (no cross-gate state).
- *   - Gates run sequentially unless the caller sets `parallel` options.
- *   - Default timeout is 60 000 ms per gate (overridable via `timeoutMs`
- *     on the gate or the `CLEO_GATE_TIMEOUT_MS` env variable).
+ *   - 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.
+ *   - 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 { execFile } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { readFile, stat } from 'node:fs/promises';
-import { isAbsolute, join } from 'node:path';
-import { promisify } from 'node:util';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } 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 } from '@cleocode/contracts';
 import { getProjectRoot } from '../paths.js';
+import { captureProjectScope, worktreeScope } from '../project-scope.js';
 import { truncateString } from '../render/helpers.js';
+import { captureWrapped } from '../resources/spawn-wrapper.js';
 import { createAttachmentStore } from '../store/attachment-store.js';
-const execFileAsync = promisify(execFile);
+import { registerTeardownAbort } from '../teardown-signal.js';
+import { acItemToText, acTextHash } from './ac-table.js';
+import { heavyToolEnv } from './heavy-tool-env.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);
-/** Maximum evidence string length stored per gate result. */
-const MAX_EVIDENCE_BYTES = 2_000;
+/** 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';
 /**
@@ -44,166 +50,578 @@ const CHECKED_BY = process.env['CLEO_AGENT_ID'] ?? 'cleo-verify';
  * @param gates   - Typed gate objects (strings pre-filtered by caller).
  * @param options - Execution options.
  * @returns       Ordered `AcceptanceGateResult[]`, one per gate.
+ * @throws If explicit project authority conflicts, metadata is invalid, or admission options are invalid.
+ * @remarks Results retain the original gate requirement ID. Process outcomes include target,
+ * transport and cleanup observations; they do not by themselves authorize task completion.
+ * Declared operation bytes reserve the per-gate capture ceiling before admission. Filesystem
+ * calls and regular-expression CPU work are cooperatively checked, not synchronously preempted.
+ * Canonical attachment retrieval validates its declared size but is not a streaming read API.
+ * @example
+ * ```typescript
+ * const results = await runGates([{ kind: 'command', description: 'check', cmd: 'node', args: ['check.mjs'] }], { projectRoot: '/project' });
+ * ```
  *
  * @epic T760
  * @task T781
  */
 export async function runGates(gates, options = {}) {
-    const projectRoot = options.projectRoot ?? getProjectRoot();
-    const skipManual = options.skipManual ?? true;
+    const inherited = worktreeScope.getStore();
+    if (inherited?.execution && options.execution && inherited.execution !== options.execution)
+        throw new Error('Gate execution cannot replace an active captured operation');
+    const execution = options.execution ?? inherited?.execution;
+    const projectRoot = resolve(options.projectRoot ?? execution?.identity.projectRoot ?? getProjectRoot());
+    if (execution && resolve(execution.identity.projectRoot) !== projectRoot)
+        throw new Error('Gate execution project does not match captured operation authority');
+    const scope = captureProjectScope(projectRoot, {
+        ...captureProjectScope(projectRoot, inherited),
+        execution,
+    });
+    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');
+    const snapshot = structuredClone(gates);
+    const controller = new AbortController();
+    const deregister = registerTeardownAbort(controller);
+    const batch = {
+        cwd: projectRoot,
+        env: { ...(options.env ?? process.env) },
+        execution: {
+            deadlineAt: execution?.deadlineAt ?? Date.now() + 2000,
+            signal: execution
+                ? AbortSignal.any([execution.signal, controller.signal])
+                : controller.signal,
+        },
+        maxOutputBytes,
+        memoryMaxMb: options.memoryMaxMb,
+        tasksMax: options.tasksMax,
+        systemdControl: options.systemdControl,
+    };
+    const checkedBy = execution?.identity.actor ?? batch.env['CLEO_AGENT_ID'] ?? CHECKED_BY;
     const results = [];
-    for (let i = 0; i < gates.length; i++) {
-        const gate = gates[i];
-        const startMs = Date.now();
-        let result;
+    try {
+        return await worktreeScope.run(scope, async () => {
+            for (let i = 0; i < snapshot.length; i++) {
+                const gate = snapshot[i];
+                const startMs = Date.now();
+                try {
+                    execution?.assertActive();
+                    execution?.consume({
+                        items: 1,
+                        bytes: gate.kind === 'manual' ? 0 : maxOutputBytes,
+                    });
+                    assertGateActive(batch);
+                    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));
+                }
+                catch (error) {
+                    results.push(makeResult(i, gate, 'error', Date.now() - startMs, undefined, error instanceof Error ? error.message : String(error)));
+                }
+            }
+            return results.map((result) => ({ ...result, checkedBy }));
+        });
+    }
+    finally {
+        deregister();
+    }
+}
+/**
+ * Run task requirements with their canonical AC and bounded input snapshots.
+ * @param task - Captured task, including its complete mixed acceptance array.
+ * @param criteria - Current normalized acceptance rows from the same task snapshot.
+ * @param options - Existing explicitly admitted verification lifetime and process limits.
+ * @returns Results bound to original mixed-array indexes, identities and input bytes.
+ * @remarks This function never writes a result. The canonical verifier must compare
+ * task/criterion freshness again and persist results plus receipt in one transaction.
+ * Untracked harnesses are included; undeclared runtime dependencies are not inferred.
+ * @example
+ * ```typescript
+ * const results = await runTaskGates(task, rows, { projectRoot, execution });
+ * ```
+ */
+export async function runTaskGates(task, criteria, options) {
+    const execution = options.execution ?? worktreeScope.getStore()?.execution;
+    if (!execution || execution.identity.operation !== 'check.gate.verify')
+        throw new Error('Typed verification requires an explicitly admitted check.gate.verify lifetime');
+    const root = resolve(options.projectRoot ?? execution.identity.projectRoot);
+    const scope = captureProjectScope(root, {
+        ...captureProjectScope(root, worktreeScope.getStore()),
+        execution,
+    });
+    const snapshot = structuredClone(task);
+    const rows = structuredClone([...criteria]).sort((a, b) => a.ordinal - b.ordinal);
+    assertCriterionProjection(snapshot, rows);
+    const env = { ...(options.env ?? process.env) };
+    const verificationId = randomUUID();
+    return worktreeScope.run(scope, async () => {
+        const results = [];
+        for (const [index, gate] of (snapshot.acceptance ?? []).entries()) {
+            if (typeof gate === 'string')
+                continue;
+            execution.assertActive();
+            const capturedAt = new Date().toISOString();
+            const invocation = executableInvocation(gate, root, env);
+            const artifacts = await snapshotGateInputs(snapshot, gate, invocation, execution);
+            const binding = {
+                version: 1,
+                verificationId,
+                identity: { ...execution.identity },
+                taskId: snapshot.id,
+                criterionId: rows[index].id,
+                criterionHash: acTextHash(rows[index].text),
+                gateHash: createHash('sha256').update(acItemToText(gate)).digest('hex'),
+                capturedAt,
+                deadlineAt: execution.deadlineAt,
+                ...(invocation ? { invocation } : {}),
+                artifacts,
+            };
+            const observed = (await runGates([gate], { ...options, projectRoot: root, env, execution }))[0];
+            let result = { ...observed, index, binding };
+            try {
+                const after = await snapshotGateInputs(snapshot, gate, invocation, execution);
+                if (!isDeepStrictEqual(after, artifacts))
+                    throw new Error('Verification inputs changed during execution');
+            }
+            catch (error) {
+                result = {
+                    ...result,
+                    result: 'error',
+                    errorMessage: error instanceof Error ? error.message : String(error),
+                };
+            }
+            results.push(acceptanceGateResultSchema.parse(result));
+        }
+        return results;
+    });
+}
+/**
+ * Build the existing audit detail payload for one validated typed-result batch.
+ * @param results - Exact result array that is persisted alongside this receipt.
+ * @param passed - Overall verification outcome at the time of recording.
+ * @returns The canonical receipt detail shape with deterministic result-byte hash.
+ * @throws Error when results are absent, unbound, duplicated or belong to different batches.
+ * @remarks This serializer establishes shape and byte identity, not execution authority.
+ * The caller must persist the receipt and results in the same owning transaction.
+ * @example
+ * ```ts
+ * const details = createTaskGateReceipt(results, verification.passed);
+ * await transaction.appendLog({ action: 'gate.verify.typed', taskId, details });
+ * ```
+ */
+export function createTaskGateReceipt(results, passed) {
+    const first = results[0]?.binding;
+    if (!first)
+        throw new Error('Typed receipt requires a bound result batch');
+    const indexes = new Set();
+    const criteria = new Set();
+    for (const candidate of results) {
+        const result = acceptanceGateResultSchema.parse(candidate);
+        const binding = result.binding;
+        if (!binding ||
+            binding.verificationId !== first.verificationId ||
+            binding.taskId !== first.taskId ||
+            !isDeepStrictEqual(binding.identity, first.identity) ||
+            binding.deadlineAt !== first.deadlineAt ||
+            indexes.has(result.index) ||
+            criteria.has(binding.criterionId))
+            throw new Error('Typed receipt requires one batch owner and unique criterion results');
+        indexes.add(result.index);
+        criteria.add(binding.criterionId);
+    }
+    return {
+        verificationId: first.verificationId,
+        resultHash: createHash('sha256').update(JSON.stringify(results)).digest('hex'),
+        operation: 'check.gate.verify',
+        passed,
+    };
+}
+/**
+ * Revalidate persisted typed results against current canonical task and input state.
+ * @param task - Current task read under the caller's transaction ownership.
+ * @param criteria - Current normalized AC rows from that transaction.
+ * @param results - Authentic stored results, never caller-submitted verdicts.
+ * @param options - Current captured lifetime bounding revalidation work.
+ * @param requirePassing - True for completion; false only when recording actual unmet verification outcomes.
+ * @returns Resolves when bound inputs are current and the requested verdict policy holds.
+ * @remarks Historical unbound results and generic text-AC evidence cannot substitute.
+ * Filesystem checks are cooperative and cannot make external file writes atomic with SQLite.
+ * @example
+ * ```typescript
+ * await revalidateTaskGateResults(task, rows, task.verification?.gateResults ?? [], { execution });
+ * ```
+ */
+export async function revalidateTaskGateResults(task, criteria, results, options, requirePassing = true) {
+    const execution = options.execution ?? worktreeScope.getStore()?.execution;
+    if (!execution)
+        throw new Error('Typed result revalidation requires a captured execution lifetime');
+    const root = resolve(options.projectRoot ?? execution.identity.projectRoot);
+    const scope = captureProjectScope(root, {
+        ...captureProjectScope(root, worktreeScope.getStore()),
+        execution,
+    });
+    const rows = [...criteria].sort((a, b) => a.ordinal - b.ordinal);
+    assertCriterionProjection(task, rows);
+    const env = { ...(options.env ?? process.env) };
+    await worktreeScope.run(scope, async () => {
+        for (const [index, gate] of (task.acceptance ?? []).entries()) {
+            if (typeof gate === 'string' || (requirePassing && gate.advisory))
+                continue;
+            execution.assertActive();
+            const matches = results.filter((result) => result.index === index);
+            if (matches.length !== 1)
+                throw new Error(`Typed requirement ${gate.req ?? index} has no unique verified result`);
+            const result = acceptanceGateResultSchema.parse(matches[0]);
+            const binding = result.binding;
+            if ((requirePassing && result.result !== 'pass') ||
+                !binding ||
+                result.kind !== gate.kind ||
+                result.req !== gate.req)
+                throw new Error(`Typed requirement ${gate.req ?? index} lacks a passing bound result`);
+            if (binding.taskId !== task.id ||
+                binding.identity.projectId !== execution.identity.projectId ||
+                binding.identity.projectRoot !== root ||
+                binding.criterionId !== rows[index].id ||
+                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);
+            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`);
+        }
+    });
+}
+/**
+ * Validate completion authority from current typed inputs and the canonical verification receipt.
+ * @param task - Task snapshot owned by the caller's write transaction.
+ * @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.
+ * @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
+ * committing. Advisory gates retain their existing semantics; generic evidence cannot replace
+ * hard typed proof. Filesystem hashing is cooperative, not atomic with external file writes.
+ * @example
+ * ```typescript
+ * await validateTaskGateCompletion(task, rows, { execution }, accessor);
+ * ```
+ */
+export async function validateTaskGateCompletion(task, criteria, options, accessor) {
+    const results = task.verification?.gateResults ?? [];
+    await revalidateTaskGateResults(task, criteria, results, options);
+    if (!(task.acceptance ?? []).some((item) => typeof item !== 'string' && !item.advisory))
+        return;
+    const passingDetails = JSON.stringify(createTaskGateReceipt(results, true));
+    const failingDetails = JSON.stringify(createTaskGateReceipt(results, false));
+    const receipts = await accessor.queryAuditLog({
+        taskIds: [task.id],
+        actions: ['gate.verify.typed'],
+        limit: 100,
+    });
+    if (!receipts.some((receipt) => receipt.actor === results[0].binding.identity.actor &&
+        (receipt.detailsJson === passingDetails || receipt.detailsJson === failingDetails)))
+        throw new Error('Typed requirement result has no authentic matching canonical receipt');
+    (options.execution ?? worktreeScope.getStore()?.execution)?.assertActive();
+}
+/** Require the stored mixed acceptance array and ordered normalized rows to agree. */
+function assertCriterionProjection(task, rows) {
+    const acceptance = task.acceptance ?? [];
+    if (rows.length !== acceptance.length ||
+        rows.some((row, index) => row.taskId !== task.id ||
+            row.text !== acItemToText(acceptance[index]) ||
+            (row.kind === 'evidence_bound') !== (typeof acceptance[index] !== 'string') ||
+            (row.kind !== 'child_task' &&
+                row.contentHash !== null &&
+                row.contentHash !== acTextHash(row.text))))
+        throw new Error('Typed verification refused inconsistent acceptance JSON and normalized AC rows');
+}
+/** Effective child environment shared by launch and verification input hashing. */
+function gateEnvironment(env, overlay) {
+    const merged = { ...env, ...overlay };
+    return { ...merged, ...heavyToolEnv('test', merged) };
+}
+/** Resolve the actual executable inputs once using the same rules as process launch. */
+function executableInvocation(gate, root, env) {
+    if (gate.kind !== 'test' && gate.kind !== 'command' && gate.kind !== 'lint')
+        return undefined;
+    const [testCommand, ...testArgs] = gate.kind === 'test' ? gate.command.trim().split(/\s+/) : [];
+    const command = gate.kind === 'test'
+        ? testCommand
+        : gate.kind === 'command'
+            ? gate.cmd
+            : LINT_TOOL_DEFAULTS[gate.tool].cmd;
+    const args = gate.args ??
+        (gate.kind === 'test'
+            ? testArgs
+            : gate.kind === 'lint'
+                ? LINT_TOOL_DEFAULTS[gate.tool].defaultArgs
+                : []);
+    const effective = gateEnvironment(env, gate.kind === 'lint' ? undefined : gate.env);
+    return {
+        command,
+        args: [...args],
+        cwd: resolveCwd(root, gate.cwd),
+        environmentHash: createHash('sha256')
+            .update(JSON.stringify(Object.entries(effective)
+            .filter(([, value]) => value !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b))))
+            .digest('hex'),
+    };
+}
+/** Capture declared task inputs and an interpreter's explicit harness argument. */
+async function snapshotGateInputs(task, gate, invocation, execution) {
+    const root = resolve(execution.identity.projectRoot);
+    if (invocation) {
+        const cwdRelative = relative(root, invocation.cwd);
+        if (cwdRelative === '..' || cwdRelative.startsWith('../') || isAbsolute(cwdRelative))
+            throw new Error('Typed invocation working directory escapes the captured project');
+        if ((await realpath(invocation.cwd)) !== invocation.cwd)
+            throw new Error('Typed invocation working directory has ambiguous symlink ownership');
+    }
+    const paths = new Set((task.files ?? []).map((path) => resolve(root, path)));
+    if (gate.kind === 'file' && gate.path)
+        paths.add(resolve(root, gate.path));
+    if (invocation &&
+        /^(node(?:\.exe)?|python[0-9.]*(?:\.exe)?|bun|deno|tsx|ts-node|bash|sh|ruby|perl)$/.test(basename(invocation.command))) {
+        if (!invocation.args.some((arg) => ['-e', '--eval', '-c', '--print', '-p'].includes(arg))) {
+            const script = invocation.args.find((arg) => !arg.startsWith('-'));
+            if (script)
+                paths.add(resolve(invocation.cwd, script));
+            for (const arg of invocation.args) {
+                if (!arg.startsWith('-') &&
+                    (arg.includes('/') || /\.(?:[cm]?[jt]sx?|py|sh|rb|pl)$/.test(arg)))
+                    paths.add(resolve(invocation.cwd, arg));
+            }
+        }
+    }
+    const artifacts = [];
+    for (const path of [...paths].sort()) {
+        execution.assertActive();
+        execution.consume({ items: 1 });
+        if (/[?*[\]{}]/.test(path))
+            throw new Error(`Typed input requires an explicit file path: ${path}`);
+        const rel = relative(root, path);
+        if (!rel || rel === '..' || rel.startsWith('../') || isAbsolute(rel))
+            throw new Error(`Typed input escapes the captured project: ${path}`);
+        // Refuse redirected parents even for absent files; absence must belong to this project.
+        let parent = dirname(path);
+        for (;;) {
+            try {
+                if ((await realpath(parent)) !== parent)
+                    throw new Error(`Typed input has an ambiguous symlink parent: ${path}`);
+                break;
+            }
+            catch (error) {
+                if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+                    throw error;
+                if (parent === root)
+                    throw error;
+                parent = dirname(parent);
+            }
+        }
+        let before;
         try {
-            result = await runOneGate(gate, i, projectRoot, skipManual);
+            before = await lstat(path);
         }
-        catch (err) {
-            const durationMs = Date.now() - startMs;
-            result = {
-                index: i,
-                req: gate.req,
-                kind: gate.kind,
-                result: 'error',
-                durationMs,
-                errorMessage: err instanceof Error ? err.message : String(err),
-                checkedAt: new Date().toISOString(),
-                checkedBy: CHECKED_BY,
-            };
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+                artifacts.push({ path, sha256: null, bytes: null });
+                continue;
+            }
+            throw error;
+        }
+        if (!before.isFile() || before.isSymbolicLink())
+            throw new Error(`Typed input is not an unambiguous regular file: ${path}`);
+        const ceiling = execution.resources.maxBytes ?? 1_048_576;
+        if (before.size > ceiling)
+            throw new Error(`Typed input exceeds admitted byte limit: ${path}`);
+        const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const opened = await file.stat();
+            if (opened.dev !== before.dev || opened.ino !== before.ino)
+                throw new Error(`Typed input replaced while opening: ${path}`);
+            const hash = createHash('sha256');
+            const buffer = Buffer.alloc(65_536);
+            let bytes = 0;
+            for (;;) {
+                execution.assertActive();
+                const chunk = await file.read(buffer, 0, buffer.length, null);
+                if (chunk.bytesRead === 0)
+                    break;
+                bytes += chunk.bytesRead;
+                if (bytes > ceiling)
+                    throw new Error(`Typed input grew beyond admitted byte limit: ${path}`);
+                execution.consume({ bytes: chunk.bytesRead });
+                hash.update(buffer.subarray(0, chunk.bytesRead));
+            }
+            const after = await file.stat();
+            const named = await lstat(path);
+            if (bytes !== before.size ||
+                after.size !== before.size ||
+                after.mtimeMs !== before.mtimeMs ||
+                after.ctimeMs !== before.ctimeMs ||
+                named.dev !== before.dev ||
+                named.ino !== before.ino)
+                throw new Error(`Typed input changed while hashing: ${path}`);
+            execution.assertActive();
+            artifacts.push({ path, sha256: hash.digest('hex'), bytes });
+        }
+        finally {
+            await file.close();
         }
-        results.push(result);
     }
-    return results;
+    return artifacts;
+}
+/** Check the shared boundary without pretending to preempt synchronous operations. */
+function assertGateActive(context) {
+    context.execution.signal?.throwIfAborted();
+    if (Date.now() >= context.execution.deadlineAt)
+        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) {
+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');
     switch (gate.kind) {
         case 'test':
-            return runTestGate(gate, index, projectRoot, timeout);
+            return runTestGate(gate, index, projectRoot, timeout, context);
         case 'file':
-            return runFileGate(gate, index, projectRoot);
+            return runFileGate(gate, index, projectRoot, context);
         case 'command':
-            return runCommandGate(gate, index, projectRoot, timeout);
+            return runCommandGate(gate, index, projectRoot, timeout, context);
         case 'lint':
-            return runLintGate(gate, index, projectRoot, timeout);
+            return runLintGate(gate, index, projectRoot, timeout, context);
         case 'http':
-            return runHttpGate(gate, index, projectRoot, timeout);
+            return runHttpGate(gate, index, projectRoot, timeout, context);
         case 'manual':
             return runManualGate(gate, index, skipManual);
     }
 }
 // ─── Test gate ────────────────────────────────────────────────────────────────
-async function runTestGate(gate, index, projectRoot, timeoutMs) {
-    const startMs = Date.now();
-    const cwd = resolveCwd(projectRoot, gate.cwd);
-    // Split command string into binary + args if no explicit args provided
-    const [bin, ...defaultArgs] = gate.command.split(' ');
-    const args = gate.args ?? defaultArgs;
-    let stdout = '';
-    let stderr = '';
-    let exitCode = 0;
-    let timedOut = false;
-    try {
-        const out = await execFileAsync(bin, args, {
-            cwd,
-            env: { ...process.env, ...gate.env },
-            timeout: timeoutMs,
-        });
-        stdout = out.stdout;
-        stderr = out.stderr;
-    }
-    catch (err) {
-        const e = err;
-        stdout = e.stdout ?? '';
-        stderr = e.stderr ?? '';
-        exitCode = typeof e.status === 'number' ? e.status : 1;
-        if (e.killed || e.code === 'ETIMEDOUT') {
-            timedOut = true;
-        }
-    }
-    const durationMs = Date.now() - startMs;
-    const combined = truncateString(`${stdout}\n${stderr}`.trim(), MAX_EVIDENCE_BYTES);
-    if (timedOut) {
-        // T12137 (gh#1270): 'error', NOT 'fail'. A gate that was killed produced no
-        // verdict — it did not find a problem, it never finished looking. Recording
-        // it as 'fail' makes a false red indistinguishable from a real one, which
-        // costs an agent the work it actually completed. The distinction already
-        // existed in `AcceptanceGateResult['result']` and was simply unused here.
-        return makeResult(index, gate, 'error', durationMs, combined, `Gate did not finish: killed after ${timeoutMs}ms. This is NOT a failure — the check never produced a verdict. Re-run it, or raise the timeout.`);
-    }
-    if (exitCode !== 0) {
-        return makeResult(index, gate, 'fail', durationMs, combined, `Exit code ${exitCode}`);
-    }
-    // For 'pass' mode, check for obvious failure indicators in stdout
-    if (gate.expect === 'pass') {
-        const failPattern = /\bFAIL\b|failing|Error:/i;
-        if (failPattern.test(stdout)) {
-            return makeResult(index, gate, 'fail', durationMs, combined, 'Failure pattern detected in output');
-        }
-    }
-    return makeResult(index, gate, 'pass', durationMs, combined);
+/** Execute a process gate through the existing captured resource service. */
+async function captureGateCommand(command, args, cwd, timeoutMs, context, overlay) {
+    const env = gateEnvironment(context.env ?? process.env, overlay);
+    return captureWrapped(command, args, {
+        ...context,
+        cwd,
+        env,
+        execution: {
+            ...context.execution,
+            deadlineAt: Math.min(context.execution.deadlineAt, Date.now() + timeoutMs),
+        },
+    });
+}
+/** Preserve target failure independently from launch, cancellation and cleanup failures. */
+function processGateResult(index, gate, captured, verdict, reason) {
+    const incomplete = !captured.started ||
+        !captured.targetCloseObserved ||
+        captured.exitCode === null ||
+        captured.signal !== null ||
+        captured.error !== null ||
+        captured.stopped !== null ||
+        captured.outputTruncated ||
+        captured.cleanupErrors.length > 0;
+    return {
+        ...makeResult(index, gate, incomplete ? 'error' : verdict, captured.durationMs, truncateString(`${captured.stdout}\n${captured.stderr}`.trim(), MAX_EVIDENCE_CHARS), incomplete
+            ? `Gate did not finish: ${captured.error ?? captured.stopped ?? captured.signal ?? (captured.cleanupErrors.join('; ') || 'target outcome missing')}. This is NOT a failure verdict.`
+            : reason),
+        execution: captured,
+    };
+}
+async function runTestGate(gate, index, projectRoot, timeoutMs, context) {
+    if (gate.minCount !== undefined && gate.minCount > 0)
+        throw new Error('Minimum test count requires a supported structured count result; exit0 alone cannot prove it');
+    const invocation = executableInvocation(gate, projectRoot, context.env ?? process.env);
+    const captured = await captureGateCommand(invocation.command, invocation.args, invocation.cwd, timeoutMs, context, gate.env);
+    const passed = captured.exitCode === 0 &&
+        (gate.expect === 'exit0' || !/\bFAIL\b|failing|Error:/i.test(captured.stdout));
+    return processGateResult(index, gate, captured, passed ? 'pass' : 'fail', captured.exitCode === 0
+        ? 'Failure pattern detected in output'
+        : `Exit code ${captured.exitCode}`);
 }
 // ─── File gate ────────────────────────────────────────────────────────────────
-async function runFileGate(gate, index, projectRoot) {
+async function runFileGate(gate, index, projectRoot, context) {
     const startMs = Date.now();
-    // Resolve file path: either from gate.path or via AttachmentStore by sha256.
+    let attachmentBytes;
     let filePath;
     if (gate.attachmentSha256) {
-        // Resolve via AttachmentStore — fail fast if the attachment is missing.
         const store = createAttachmentStore();
-        const result = await store.get(gate.attachmentSha256);
-        if (!result) {
-            const durationMs = Date.now() - startMs;
-            return makeResult(index, gate, 'fail', durationMs, `attachment sha256=${gate.attachmentSha256} not found`, `Attachment not found: ${gate.attachmentSha256}`);
-        }
-        // Derive the on-disk path from AttachmentStore internals via the metadata.
-        const mime = 'mime' in result.metadata.attachment
-            ? result.metadata.attachment.mime
-            : 'application/octet-stream';
-        // Reconstruct path: .cleo/attachments/sha256/<prefix>/<rest>.<ext>
-        const { getCleoDirAbsolute } = await import('../paths.js');
-        const { join: pathJoin } = await import('node:path');
-        const cleoDir = getCleoDirAbsolute(projectRoot);
-        const sha256 = gate.attachmentSha256;
-        const extMap = {
-            'text/markdown': '.md',
-            'text/plain': '.txt',
-            'application/json': '.json',
-            'application/pdf': '.pdf',
-            'text/html': '.html',
-        };
-        const ext = extMap[mime] ?? '.bin';
-        filePath = pathJoin(cleoDir, 'attachments', 'sha256', sha256.slice(0, 2), `${sha256.slice(2)}${ext}`);
+        const metadata = await store.getMetadata(gate.attachmentSha256, projectRoot);
+        assertGateActive(context);
+        if (!metadata)
+            return makeResult(index, gate, 'fail', Date.now() - startMs, undefined, 'Attachment not found');
+        const attachment = metadata.attachment;
+        if (!('size' in attachment) || !Number.isSafeInteger(attachment.size) || attachment.size < 0)
+            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);
+        assertGateActive(context);
+        if (!result)
+            throw new Error('Attachment metadata exists but authenticated bytes are unavailable');
+        if (result.bytes.length > (context.maxOutputBytes ?? 1_048_576))
+            throw new Error('Attachment bytes exceed declared limit');
+        attachmentBytes = result.bytes;
+        filePath = `sha256:${gate.attachmentSha256}`;
     }
     else if (gate.path) {
         filePath = isAbsolute(gate.path) ? gate.path : join(projectRoot, gate.path);
     }
-    else {
-        const durationMs = Date.now() - startMs;
-        return makeResult(index, gate, 'fail', durationMs, 'FileGate requires either path or attachmentSha256', 'FileGate missing path and attachmentSha256');
-    }
+    else
+        throw new Error('FileGate requires path or attachmentSha256');
     const failures = [];
-    const fileContent = null;
+    let fileContent = attachmentBytes;
     let fileSize = 0;
     let fileExists = false;
     // Check existence first
     try {
-        const st = await stat(filePath);
+        const st = attachmentBytes ? { size: attachmentBytes.length } : await stat(filePath);
         fileExists = true;
         fileSize = st.size;
     }
-    catch {
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+            throw error;
         fileExists = false;
     }
     for (const assertion of gate.assertions) {
-        const failure = await checkFileAssertion(assertion, filePath, fileExists, fileSize, () => {
-            if (fileContent === null) {
-                return readFile(filePath, 'utf-8').catch(() => '');
+        assertGateActive(context);
+        if (['contains', 'matches', 'sha256'].includes(assertion.type) &&
+            fileSize > (context.maxOutputBytes ?? 1_048_576))
+            throw new Error('File gate content exceeds declared byte limit');
+        const failure = await checkFileAssertion(assertion, filePath, fileExists, fileSize, async () => {
+            if (fileContent === undefined) {
+                const limit = context.maxOutputBytes ?? 1_048_576;
+                const handle = await open(filePath, 'r');
+                try {
+                    const chunks = [];
+                    let bytes = 0;
+                    for (;;) {
+                        assertGateActive(context);
+                        const chunk = Buffer.alloc(Math.min(65536, limit - bytes + 1));
+                        const read = await handle.read(chunk, 0, chunk.length, null);
+                        assertGateActive(context);
+                        if (read.bytesRead === 0)
+                            break;
+                        bytes += read.bytesRead;
+                        if (bytes > limit)
+                            throw new Error('File content exceeds declared byte limit');
+                        chunks.push(chunk.subarray(0, read.bytesRead));
+                    }
+                    fileContent = Buffer.concat(chunks);
+                }
+                finally {
+                    await handle.close();
+                }
             }
-            return Promise.resolve(fileContent);
+            return fileContent;
         });
+        assertGateActive(context);
         if (failure) {
             failures.push(failure);
         }
@@ -211,7 +629,7 @@ async function runFileGate(gate, index, projectRoot) {
     const durationMs = Date.now() - startMs;
     if (failures.length > 0) {
         const evidence = `path=${filePath}\n${failures.join('\n')}`;
-        return makeResult(index, gate, 'fail', durationMs, truncateString(evidence, MAX_EVIDENCE_BYTES), failures[0]);
+        return makeResult(index, gate, 'fail', durationMs, truncateString(evidence, MAX_EVIDENCE_CHARS), failures[0]);
     }
     return makeResult(index, gate, 'pass', durationMs, `path=${filePath} — all assertions passed`);
 }
@@ -245,7 +663,7 @@ async function checkFileAssertion(assertion, filePath, fileExists, fileSize, get
         case 'contains': {
             if (!fileExists)
                 return `File does not exist: ${filePath}`;
-            const content = await getContent();
+            const content = (await getContent()).toString('utf8');
             return content.includes(assertion.value)
                 ? null
                 : `File does not contain: ${JSON.stringify(assertion.value)}`;
@@ -253,7 +671,7 @@ async function checkFileAssertion(assertion, filePath, fileExists, fileSize, get
         case 'matches': {
             if (!fileExists)
                 return `File does not exist: ${filePath}`;
-            const content = await getContent();
+            const content = (await getContent()).toString('utf8');
             const re = new RegExp(assertion.regex, assertion.flags);
             return re.test(content)
                 ? null
@@ -262,7 +680,7 @@ async function checkFileAssertion(assertion, filePath, fileExists, fileSize, get
         case 'sha256': {
             if (!fileExists)
                 return `File does not exist: ${filePath}`;
-            const raw = await readFile(filePath);
+            const raw = await getContent();
             const hash = createHash('sha256').update(raw).digest('hex');
             return hash === assertion.value
                 ? null
@@ -276,60 +694,19 @@ async function checkFileAssertion(assertion, filePath, fileExists, fileSize, get
     }
 }
 // ─── Command gate ─────────────────────────────────────────────────────────────
-async function runCommandGate(gate, index, projectRoot, timeoutMs) {
-    const startMs = Date.now();
-    const cwd = resolveCwd(projectRoot, gate.cwd);
-    const expectedExitCode = gate.exitCode ?? 0;
-    let stdout = '';
-    let stderr = '';
-    let actualExitCode = 0;
-    let timedOut = false;
-    try {
-        const out = await execFileAsync(gate.cmd, gate.args ?? [], {
-            cwd,
-            env: { ...process.env, ...gate.env },
-            timeout: timeoutMs,
-        });
-        stdout = out.stdout;
-        stderr = out.stderr;
-    }
-    catch (err) {
-        const e = err;
-        stdout = e.stdout ?? '';
-        stderr = e.stderr ?? '';
-        actualExitCode = typeof e.status === 'number' ? e.status : 1;
-        if (e.killed || e.code === 'ETIMEDOUT') {
-            timedOut = true;
-        }
-    }
-    const durationMs = Date.now() - startMs;
-    const combined = truncateString(`${stdout}\n${stderr}`.trim(), MAX_EVIDENCE_BYTES);
-    if (timedOut) {
-        // T12137 (gh#1270): 'error', NOT 'fail'. A gate that was killed produced no
-        // verdict — it did not find a problem, it never finished looking. Recording
-        // it as 'fail' makes a false red indistinguishable from a real one, which
-        // costs an agent the work it actually completed. The distinction already
-        // existed in `AcceptanceGateResult['result']` and was simply unused here.
-        return makeResult(index, gate, 'error', durationMs, combined, `Gate did not finish: killed after ${timeoutMs}ms. This is NOT a failure — the check never produced a verdict. Re-run it, or raise the timeout.`);
-    }
-    if (actualExitCode !== expectedExitCode) {
-        return makeResult(index, gate, 'fail', durationMs, combined, `Exit code ${actualExitCode} (expected ${expectedExitCode})`);
-    }
-    if (gate.stdoutMatches) {
-        const re = new RegExp(gate.stdoutMatches);
-        if (!re.test(stdout)) {
-            return makeResult(index, gate, 'fail', durationMs, combined, `stdout did not match /${gate.stdoutMatches}/`);
-        }
-    }
-    if (gate.stderrMatches) {
-        const re = new RegExp(gate.stderrMatches);
-        if (!re.test(stderr)) {
-            return makeResult(index, gate, 'fail', durationMs, combined, `stderr did not match /${gate.stderrMatches}/`);
-        }
-    }
-    return makeResult(index, gate, 'pass', durationMs, combined);
+async function runCommandGate(gate, index, projectRoot, timeoutMs, context) {
+    const invocation = executableInvocation(gate, projectRoot, context.env ?? process.env);
+    const captured = await captureGateCommand(invocation.command, invocation.args, invocation.cwd, timeoutMs, context, gate.env);
+    const expected = gate.exitCode ?? 0;
+    let reason = captured.exitCode === expected
+        ? undefined
+        : `Exit code ${captured.exitCode} (expected ${expected})`;
+    if (!reason && gate.stdoutMatches && !new RegExp(gate.stdoutMatches).test(captured.stdout))
+        reason = 'stdout pattern did not match';
+    if (!reason && gate.stderrMatches && !new RegExp(gate.stderrMatches).test(captured.stderr))
+        reason = 'stderr pattern did not match';
+    return processGateResult(index, gate, captured, reason ? 'fail' : 'pass', reason);
 }
-// ─── Lint gate ────────────────────────────────────────────────────────────────
 /** Tool-specific CLI arguments and failure patterns. */
 const LINT_TOOL_DEFAULTS = {
     biome: { cmd: 'biome', defaultArgs: ['check', '.'] },
@@ -343,81 +720,57 @@ const LINT_TOOL_DEFAULTS = {
         errorPattern: /^error/m,
     },
 };
-async function runLintGate(gate, index, projectRoot, timeoutMs) {
-    const startMs = Date.now();
-    const cwd = resolveCwd(projectRoot, gate.cwd);
-    const toolDef = LINT_TOOL_DEFAULTS[gate.tool];
-    const args = gate.args ?? toolDef.defaultArgs;
-    let stdout = '';
-    let stderr = '';
-    let exitCode = 0;
-    let timedOut = false;
-    try {
-        const out = await execFileAsync(toolDef.cmd, args, { cwd, timeout: timeoutMs });
-        stdout = out.stdout;
-        stderr = out.stderr;
-    }
-    catch (err) {
-        const e = err;
-        stdout = e.stdout ?? '';
-        stderr = e.stderr ?? '';
-        exitCode = typeof e.status === 'number' ? e.status : 1;
-        if (e.killed || e.code === 'ETIMEDOUT') {
-            timedOut = true;
-        }
-    }
-    const durationMs = Date.now() - startMs;
-    const combined = truncateString(`${stdout}\n${stderr}`.trim(), MAX_EVIDENCE_BYTES);
-    if (timedOut) {
-        // T12137 (gh#1270): 'error', NOT 'fail'. A gate that was killed produced no
-        // verdict — it did not find a problem, it never finished looking. Recording
-        // it as 'fail' makes a false red indistinguishable from a real one, which
-        // costs an agent the work it actually completed. The distinction already
-        // existed in `AcceptanceGateResult['result']` and was simply unused here.
-        return makeResult(index, gate, 'error', durationMs, combined, `Gate did not finish: killed after ${timeoutMs}ms. This is NOT a failure — the check never produced a verdict. Re-run it, or raise the timeout.`);
-    }
-    // For 'noErrors' mode, exit code 0 = pass (warnings tolerated)
-    if (gate.expect === 'noErrors') {
-        const passed = exitCode === 0;
-        return makeResult(index, gate, passed ? 'pass' : 'fail', durationMs, combined, passed ? undefined : `${gate.tool} reported errors (exit ${exitCode})`);
-    }
-    // For 'clean' mode, check exit code AND optional error pattern
-    if (exitCode !== 0) {
-        return makeResult(index, gate, 'fail', durationMs, combined, `${gate.tool} exited with ${exitCode}`);
-    }
-    if (toolDef.errorPattern?.test(combined)) {
-        return makeResult(index, gate, 'fail', durationMs, combined, `${gate.tool} output matched error pattern`);
-    }
-    return makeResult(index, gate, 'pass', durationMs, combined);
+async function runLintGate(gate, index, projectRoot, timeoutMs, context) {
+    const tool = LINT_TOOL_DEFAULTS[gate.tool];
+    const invocation = executableInvocation(gate, projectRoot, context.env ?? process.env);
+    const captured = await captureGateCommand(invocation.command, invocation.args, invocation.cwd, timeoutMs, context);
+    const passed = captured.exitCode === 0 &&
+        (gate.expect === 'noErrors' || !tool.errorPattern?.test(captured.stdout + captured.stderr));
+    return processGateResult(index, gate, captured, passed ? 'pass' : 'fail', `${gate.tool} reported errors (exit ${captured.exitCode})`);
 }
 // ─── HTTP gate ────────────────────────────────────────────────────────────────
-async function runHttpGate(gate, index, _projectRoot, timeoutMs) {
+async function runHttpGate(gate, index, _projectRoot, timeoutMs, context) {
     const startMs = Date.now();
-    let serverProcess = null;
-    // Start the server if configured
-    if (gate.startCommand) {
-        const { spawn } = await import('node:child_process');
-        const [cmd, ...args] = gate.startCommand.split(' ');
-        serverProcess = spawn(cmd, args, { detached: true, stdio: 'ignore' });
-        serverProcess.unref();
-        // Wait for startup delay
-        const delayMs = gate.startupDelayMs ?? 2_000;
-        await new Promise((resolve) => setTimeout(resolve, delayMs));
-    }
+    if (gate.startCommand)
+        throw new Error('HTTP server startup requires an admitted owned service lifetime; unowned detached startup is unavailable');
     let statusCode = 0;
     let body = '';
     let errorMsg;
     try {
         const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        const timer = setTimeout(() => controller.abort(), Math.max(0, Math.min(timeoutMs, context.execution.deadlineAt - Date.now())));
         try {
             const response = await fetch(gate.url, {
                 method: gate.method ?? 'GET',
                 headers: gate.headers,
-                signal: controller.signal,
+                signal: context.execution.signal
+                    ? AbortSignal.any([controller.signal, context.execution.signal])
+                    : controller.signal,
             });
             statusCode = response.status;
-            body = await response.text();
+            if (response.body) {
+                const reader = response.body.getReader();
+                const chunks = [];
+                let bytes = 0;
+                try {
+                    for (;;) {
+                        assertGateActive(context);
+                        const next = await reader.read();
+                        if (next.done)
+                            break;
+                        bytes += next.value.byteLength;
+                        if (bytes > (context.maxOutputBytes ?? 1_048_576))
+                            throw new Error('HTTP body exceeds declared byte limit');
+                        chunks.push(next.value);
+                    }
+                    body = Buffer.concat(chunks).toString('utf8');
+                }
+                finally {
+                    await reader.cancel();
+                    reader.releaseLock();
+                }
+            }
+            assertGateActive(context);
         }
         finally {
             clearTimeout(timer);
@@ -426,19 +779,9 @@ async function runHttpGate(gate, index, _projectRoot, timeoutMs) {
     catch (err) {
         errorMsg = err instanceof Error ? err.message : String(err);
     }
-    finally {
-        if (serverProcess) {
-            try {
-                serverProcess.kill();
-            }
-            catch {
-                // Best-effort cleanup
-            }
-        }
-    }
     const durationMs = Date.now() - startMs;
     if (errorMsg) {
-        return makeResult(index, gate, 'fail', durationMs, errorMsg, errorMsg);
+        return makeResult(index, gate, 'error', durationMs, errorMsg, `HTTP gate did not finish: ${errorMsg}`);
     }
     if (statusCode !== gate.status) {
         return makeResult(index, gate, 'fail', durationMs, `HTTP ${statusCode}`, `Expected status ${gate.status}, got ${statusCode}`);