specrails-core 5.3.0 → 5.5.0

package/dist/installer/runtime/pipeline-state.js

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { spawn, spawnSync } from 'node:child_process';
 import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
 const PHASES = ['architect', 'developer', 'reviewer', 'archive', 'ship', 'ci'];
 // Session identity belongs to the agent transport, not the checked application.
 // Remove these from check subprocesses too, so ignored identity cannot become
@@ -290,15 +291,25 @@ function untrackedAgentMemory(relative) {
     // belong to the candidate. Do not hide arbitrary provider directory content.
     return ['.claude', '.codex', '.gemini', '.kimi-code', '.specrails'].some(provider => relative === provider + '/agent-memory' || relative.startsWith(provider + '/agent-memory/'));
 }
-export function fingerprintCandidate(state) {
+const GENERATED_OUTPUT_ROOTS = ['node_modules', 'coverage', '.nyc_output', '.jest-cache', '__pycache__', '.pytest_cache', '.mypy_cache', '.ruff_cache', '.venv', 'venv', '.tox', '.gradle', '.cache'];
+function untrackedGeneratedOutput(relative) {
+    // Dependency trees and test/coverage caches are never candidate content, yet
+    // a repository without a .gitignore (a greenfield scaffold) lists them as
+    // untracked: `npm test` then writes coverage/ mid-run, the fingerprint moves
+    // and every receipt reads "Candidate changed during verification" — green
+    // or not. Tracked files under these roots still count.
+    return relative.split('/').some(segment => GENERATED_OUTPUT_ROOTS.includes(segment));
+}
+export function candidateManifest(state) {
     const entries = state.context.repositories.map((repo) => ({
         id: repo.id, path: repo.path,
         files: trackedFiles(repo)
-            .filter(({ file, tracked }) => !excluded(state, repo, relativeUnix(file)) && (tracked || !untrackedAgentMemory(relativeUnix(file))))
+            .filter(({ file, tracked }) => !excluded(state, repo, relativeUnix(file)) && (tracked || (!untrackedAgentMemory(relativeUnix(file)) && !untrackedGeneratedOutput(relativeUnix(file)))))
             .map(({ file }) => [relativeUnix(file), fileFingerprint(path.join(repo.path, file))]),
     }));
-    return digest(canonical(entries));
+    return { schemaVersion: 1, scopeHash: state.scopeHash, repositories: entries };
 }
+export function fingerprintCandidate(state) { return digest(canonical(candidateManifest(state).repositories)); }
 function activeArtifactPath(state) { return state.archivePath ?? path.join(state.context.artifactRoot, 'openspec', 'changes', state.change); }
 function artifactFingerprint(state) {
     const root = activeArtifactPath(state);
@@ -349,9 +360,46 @@ function environmentHash(keys, overrides = {}, env = process.env) {
     const normalized = normalizeVerificationEnvironment(env);
     return digest(canonical(Object.fromEntries(keys.map((key) => [key, overrides[key] ?? normalized[key] ?? null]))));
 }
+/** Host-owned binding, including immutable harness bytes outside the candidate. */
+export function bindVerificationPlan(contextInput, hash, files) {
+    const context = validatePipelineContext(contextInput);
+    if (!/^[a-f0-9]{64}$/.test(hash) || files.length > 801)
+        fail('Invalid verification plan identity');
+    for (const file of files) {
+        const target = safeChild(pipelineStateDirectory(context), file.path);
+        if (!/^[a-f0-9]{64}$/.test(file.hash) || digest(readFileSync(target)) !== file.hash)
+            fail('Verification plan source changed');
+    }
+    locked(context, () => {
+        const state = readState(context);
+        const binding = { hash, files };
+        if (canonical(state.verificationPlan) === canonical(binding))
+            return;
+        if (state.phases.archive.status === 'done')
+            fail('Cannot change the archived verification plan');
+        state.verificationPlan = binding;
+        state.acceptance = undefined;
+        state.archiveApproval = undefined;
+        saveState(state);
+    });
+}
+function planReasons(state, hash) {
+    if (hash !== state.verificationPlan?.hash)
+        return ['Verification plan changed'];
+    try {
+        for (const file of state.verificationPlan?.files ?? []) {
+            if (digest(readFileSync(safeChild(pipelineStateDirectory(state.context), file.path))) !== file.hash)
+                return ['Verification plan or harness source changed'];
+        }
+    }
+    catch {
+        return ['Verification plan or harness source unavailable'];
+    }
+    return [];
+}
 function inspectReceipt(state, env = process.env) {
     const receipt = state.verification;
-    const reasons = [];
+    const reasons = planReasons(state, receipt?.planHash);
     if (!receipt)
         return { valid: false, reasons: ['No verification receipt'] };
     if (!receipt.valid || receipt.kind !== 'full')
@@ -361,6 +409,12 @@ function inspectReceipt(state, env = process.env) {
     if (receipt.candidateHash !== fingerprintCandidate(state))
         reasons.push('Candidate files changed');
     for (const command of receipt.commands) {
+        if (command.snapshot?.eligible) {
+            // The frozen logical command is recorded with each execution for inspection.
+            const snapshot = command.checkDefinition ? verificationSnapshot(state.context, command.checkDefinition) : undefined;
+            if (!snapshot?.eligible || snapshot.inputHash !== command.snapshot.inputHash || snapshot.toolchainHash !== command.snapshot.toolchainHash)
+                reasons.push('Verification inputs or toolchain changed');
+        }
         if (command.exitCode !== 0)
             reasons.push('Command failed: ' + command.command);
         if (command.environmentPolicy !== 'isolated-transport-v1')
@@ -478,6 +532,7 @@ function inspectAcceptance(state) {
     catch (error) {
         return { valid: false, status: 'blocked', reasons: [error instanceof Error ? error.message : String(error)] };
     }
+    reasons.push(...planReasons(state, receipt.planHash));
     if (receipt.scopeHash !== state.scopeHash || receipt.candidateHash !== fingerprintCandidate(state) || receipt.artifactHash !== artifactFingerprint(state))
         reasons.push('Acceptance evidence is stale');
     for (const row of receipt.criteria ?? [])
@@ -501,7 +556,7 @@ export function recordAcceptance(contextInput, input) {
         const state = readState(context);
         if (state.phases.developer.status !== 'done' || state.phases.archive.status === 'done')
             fail('Record acceptance after development and before archive');
-        state.acceptance = { ...report, scopeHash: state.scopeHash, candidateHash: fingerprintCandidate(state), artifactHash: artifactFingerprint(state), recordedAt: new Date().toISOString() };
+        state.acceptance = { ...report, ...(state.verificationPlan ? { planHash: state.verificationPlan.hash } : {}), scopeHash: state.scopeHash, candidateHash: fingerprintCandidate(state), artifactHash: artifactFingerprint(state), recordedAt: new Date().toISOString() };
         // Replacing even just an exception decision requires a new review/approval.
         for (const phase of PHASES.slice(2)) {
             if (phase === 'reviewer' && state.phases[phase].status === 'running')
@@ -651,7 +706,7 @@ export function inspectPipeline(contextInput) {
         delivery: context.ownership.git === 'host' ? 'pending-host' : state.phases.ship.status === 'done' && state.phases.ci.status === 'done' ? 'complete' : 'pending',
         reasons: [...verification.reasons, ...acceptance.reasons],
     };
-    return { schemaVersion: 1, runId: context.runId, change: state.change, context, stateDir: pipelineStateDirectory(context), resumePhase, phases: state.phases, verification, acceptance, completion };
+    return { schemaVersion: 1, runId: context.runId, change: state.change, context, stateDir: pipelineStateDirectory(context), planHash: state.verificationPlan?.hash, candidateHash: fingerprintCandidate(state), resumePhase, phases: state.phases, verification, acceptance, completion };
 }
 function validateCommand(context, raw) {
     const command = object(raw);
@@ -667,7 +722,26 @@ function validateCommand(context, raw) {
     const timeoutMs = command.timeoutMs === undefined ? 15 * 60_000 : Number(command.timeoutMs);
     if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2 * 60 * 60_000)
         fail('Invalid verification timeout');
-    return { repositoryId: repo.id, command: command.command, args: command.args, cwd, ...(env ? { env: env } : {}), timeoutMs };
+    if (command.policy !== undefined) {
+        const policy = object(command.policy);
+        if (Object.keys(policy).some(key => !['reuse', 'inputs', 'deterministic', 'readOnly', 'toolchainInputs', 'independentGroup', 'resources'].includes(key)))
+            fail('Invalid verification policy');
+        if (policy.reuse !== undefined && !['never', 'snapshot-local'].includes(String(policy.reuse)))
+            fail('Invalid verification reuse policy');
+        for (const key of ['deterministic', 'readOnly'])
+            if (policy[key] !== undefined && typeof policy[key] !== 'boolean')
+                fail('Invalid verification policy flag');
+        if (policy.independentGroup !== undefined && (typeof policy.independentGroup !== 'string' || !ID.test(policy.independentGroup)))
+            fail('Invalid verification independence group');
+        for (const key of ['inputs', 'toolchainInputs', 'resources'])
+            if (policy[key] !== undefined && (!Array.isArray(policy[key]) || policy[key].length > 256 || policy[key].some((value) => typeof value !== 'string' || !value.trim() || value.length > 4096 || value.includes('\0'))))
+                fail('Invalid verification policy inputs');
+    }
+    if (command.key !== undefined && (typeof command.key !== 'string' || !ID.test(command.key)))
+        fail('Invalid verification key');
+    if (command.label !== undefined && (typeof command.label !== 'string' || !command.label.trim() || command.label.length > 256 || command.label.includes('\0')))
+        fail('Invalid verification label');
+    return { ...(command.key === undefined ? {} : { key: command.key }), ...(command.label === undefined ? {} : { label: command.label }), ...(command.policy === undefined ? {} : { policy: command.policy }), repositoryId: repo.id, command: command.command, args: command.args, cwd, ...(env ? { env: env } : {}), timeoutMs };
 }
 /**
  * Native executables retain structured argv; Windows script shims need cmd.
@@ -702,7 +776,24 @@ export function verificationInvocation(command, args, cwd, platform = process.pl
     const quote = (value) => '"' + value + '"';
     return { command: env.ComSpec ?? env.COMSPEC ?? 'cmd.exe', args: ['/d', '/s', '/c', '"' + [resolved, ...args].map(quote).join(' ') + '"'], windowsVerbatimArguments: true };
 }
-async function executeCheck(command, log, signal) {
+/** Shared persisted-output/provider diagnostic redaction; preserves line structure. */
+export function redactRuntimeText(text, env = process.env) {
+    for (const [key, value] of Object.entries(env))
+        if (/(token|secret|password|api_?key|credential)/i.test(key) && value && value.length >= 4)
+            text = text.split(value).join('[redacted]');
+    return text.replace(/Bearer\s+[^\s"']+/gi, 'Bearer [redacted]')
+        .replace(/((?:api[_-]?key|(?:access[_-]?)?token|password|secret|authorization)["']?\s*[:=]\s*["']?)[^\s,"'}]+/gi, '$1[redacted]')
+        .replace(/https?:\/\/[^\s"'<>]+/gi, value => { try {
+        const url = new URL(value);
+        return url.origin + url.pathname;
+    }
+    catch {
+        return '[url]';
+    } });
+}
+/** Silence a verification command may keep before it counts as hung (env `SPECRAILS_VERIFY_IDLE_TIMEOUT_MS`, default 5 min). */
+function verificationIdleTimeoutMs() { const raw = Number(process.env.SPECRAILS_VERIFY_IDLE_TIMEOUT_MS); return Number.isFinite(raw) && raw >= 100 ? raw : 5 * 60_000; }
+async function executeCheck(command, log, signal, deadline, evidenceId = digest(randomUUID()), idleTimeoutOverrideMs) {
     const started = Date.now();
     const overrides = normalizeVerificationEnvironment(command.env ?? {});
     const overrideKeys = Object.keys(overrides).sort();
@@ -710,20 +801,41 @@ async function executeCheck(command, log, signal) {
     const hash = environmentHash(keys);
     const overridesHash = digest(canonical(overrides));
     const env = verificationEnvironment(process.env, overrides);
+    const configuredTimeoutMs = command.timeoutMs ?? 15 * 60_000;
+    const appliedTimeoutMs = Math.max(0, Math.min(configuredTimeoutMs, deadline === undefined ? Infinity : deadline - Date.now()));
+    // A test that never returns (a `while` that cannot exit) keeps a runner at
+    // 100 % CPU and silent until the wall-clock timeout; the silence is the
+    // signal. Bounded per command, never longer than the total timeout.
+    // 0 (a project that switched the `verify-idle-timeout` guardrail off) disables the silence bound; the wall-clock timeout still applies.
+    const idleTimeoutMs = idleTimeoutOverrideMs === 0 ? 0 : Math.min(idleTimeoutOverrideMs ?? verificationIdleTimeoutMs(), appliedTimeoutMs);
+    let lastOutputAt = Date.now();
+    let lastOutputLine = '';
+    let outcome;
     let output = '';
+    const streams = { stdout: '', stderr: '' };
+    let outputTruncated = false;
+    const redact = (text) => redactRuntimeText(text, { ...process.env, ...overrides });
     let exitCode = -1;
     await new Promise((resolve) => {
         let child;
         let timer;
+        let idleTimer;
         let done = false;
+        let stopping = false;
+        let termination;
         const finish = (code) => { if (done)
-            return; done = true; exitCode = code; if (timer)
-            clearTimeout(timer); signal?.removeEventListener('abort', abort); resolve(); };
+            return; done = true; exitCode = stopping ? -1 : code; outcome ??= code === 0 ? 'passed' : 'failed'; if (termination)
+            clearTimeout(termination); if (timer)
+            clearTimeout(timer); if (idleTimer)
+            clearInterval(idleTimer); signal?.removeEventListener('abort', abort); resolve(); };
         const stop = (reason) => {
-            output += '\n' + reason;
+            if (done || stopping)
+                return;
+            stopping = true;
+            output = (output + '\n' + reason).slice(-32_000);
             if (child?.pid) {
                 if (process.platform === 'win32')
-                    spawnSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true });
+                    spawnSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, timeout: 5000 });
                 else {
                     try {
                         process.kill(-child.pid, 'SIGKILL');
@@ -731,13 +843,22 @@ async function executeCheck(command, log, signal) {
                     catch { /* already exited */ }
                 }
             }
-            finish(-1);
+            // Never publish a receipt while a normally terminating child is alive.
+            if (!child?.pid)
+                finish(-1);
+            else
+                termination = setTimeout(() => { outcome = 'interrupted'; child.stdout?.destroy(); child.stderr?.destroy(); child.unref(); finish(-1); }, 5000);
         };
-        const abort = () => stop('Verification command cancelled');
+        const abort = () => { outcome = 'cancelled'; stop('Verification command cancelled'); };
         if (signal?.aborted) {
             abort();
             return;
         }
+        if (appliedTimeoutMs <= 0) {
+            outcome = 'timed-out';
+            stop('Workflow verification deadline exhausted');
+            return;
+        }
         try {
             const invocation = verificationInvocation(command.command, command.args, command.cwd, process.platform, env);
             child = spawn(invocation.command, invocation.args, { windowsVerbatimArguments: invocation.windowsVerbatimArguments, cwd: command.cwd, env, shell: false, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
@@ -747,45 +868,276 @@ async function executeCheck(command, log, signal) {
             finish(-1);
             return;
         }
-        const receive = (chunk) => { const text = chunk.toString('utf8'); output = (output + text).slice(-32_000); log(text); };
-        child.stdout?.on('data', receive);
-        child.stderr?.on('data', receive);
-        child.on('error', (error) => { output += error.message; finish(-1); });
+        for (const stream of ['stdout', 'stderr']) {
+            const decoder = new StringDecoder('utf8');
+            let liveLine = '', droppingLine = false;
+            const receive = (text) => {
+                const remaining = 1024 * 1024 - Buffer.byteLength(streams[stream]);
+                if (Buffer.byteLength(text) > remaining)
+                    outputTruncated = true;
+                if (remaining > 0) {
+                    let kept = text.slice(0, remaining);
+                    while (Buffer.byteLength(kept) > remaining || /[\uD800-\uDBFF]$/.test(kept))
+                        kept = kept.slice(0, -1);
+                    streams[stream] += kept;
+                }
+                output = (output + text).slice(-32_000);
+                lastOutputAt = Date.now();
+                const lastLine = text.trim().split('\n').pop()?.trim();
+                if (lastLine)
+                    lastOutputLine = lastLine.slice(0, 200);
+                // Redact whole bounded lines, so chunk boundaries cannot split credentials.
+                for (const part of text.match(/[^\n]*\n|[^\n]+$/g) ?? []) {
+                    if (!droppingLine)
+                        liveLine += part;
+                    if (liveLine.length > 16384) {
+                        liveLine = '';
+                        droppingLine = true;
+                    }
+                    if (part.endsWith('\n')) {
+                        try {
+                            log(droppingLine ? '[Long output line omitted; inspect bounded evidence]\n' : redact(liveLine));
+                        }
+                        catch { /* observer */ }
+                        liveLine = '';
+                        droppingLine = false;
+                    }
+                }
+            };
+            child[stream]?.on('data', (chunk) => receive(decoder.write(chunk)));
+            child[stream]?.on('end', () => { receive(decoder.end()); if (liveLine) {
+                try {
+                    log(redact(liveLine));
+                }
+                catch { /* observer */ }
+            } });
+        }
+        child.on('error', (error) => { output = (output + error.message).slice(-32_000); if (!child.pid)
+            finish(-1); });
         child.on('close', (code) => finish(code ?? -1));
         signal?.addEventListener('abort', abort, { once: true });
-        timer = setTimeout(() => stop('Verification command timed out'), command.timeoutMs);
+        timer = setTimeout(() => { outcome = 'timed-out'; stop('Verification command timed out'); }, appliedTimeoutMs);
+        if (idleTimeoutMs > 0)
+            idleTimer = setInterval(() => {
+                if (Date.now() - lastOutputAt < idleTimeoutMs)
+                    return;
+                outcome = 'timed-out';
+                stop(`Verification command produced no output for ${idleTimeoutMs >= 60_000 ? `${Math.round(idleTimeoutMs / 60_000)} min` : `${Math.round(idleTimeoutMs / 1000)} s`} and was stopped: a test is probably hanging (infinite loop or an open handle).${lastOutputLine ? ` Last output: ${lastOutputLine}` : ''}`);
+            }, Math.max(50, Math.min(5_000, Math.floor(idleTimeoutMs / 4))));
+        if (signal?.aborted)
+            abort();
     });
-    return { repositoryId: command.repositoryId, command: command.command, args: command.args, cwd: command.cwd, environmentPolicy: 'isolated-transport-v1', environmentHash: hash, environmentKeys: keys, environmentOverrideKeys: overrideKeys, environmentOverridesHash: overridesHash, exitCode, durationMs: Date.now() - started, output };
+    const persisted = (text) => {
+        const bytes = Buffer.from(redact(text));
+        if (bytes.length > 1024 * 1024)
+            outputTruncated = true;
+        return new StringDecoder('utf8').write(bytes.subarray(0, 1024 * 1024));
+    };
+    return { evidenceId, stdout: persisted(streams.stdout), stderr: persisted(streams.stderr), outputTruncated, ...(command.key ? { key: command.key } : {}), ...(command.label ? { label: command.label } : {}), configuredTimeoutMs, appliedTimeoutMs, ...(deadline === undefined ? {} : { deadline }), outcome, repositoryId: command.repositoryId, command: command.command, args: command.args, cwd: command.cwd, environmentPolicy: 'isolated-transport-v1', environmentHash: hash, environmentKeys: keys, environmentOverrideKeys: overrideKeys, environmentOverridesHash: overridesHash, exitCode, durationMs: Date.now() - started, output: redact(output) };
+}
+/** Host opt-in is a declaration of determinism, not inferred hermeticity. */
+export function verificationSnapshot(context, command) {
+    const policy = command.policy;
+    if (policy?.reuse !== 'snapshot-local')
+        return { eligible: false, reason: 'reuse-never' };
+    if (policy.resources?.length)
+        return { eligible: false, reason: 'reuse-ineligible-external-resources' };
+    if (!policy.deterministic || !policy.readOnly || !policy.inputs?.length || !policy.toolchainInputs?.length)
+        return { eligible: false, reason: 'reuse-ineligible-incomplete-declaration' };
+    const repository = context.repositories.find(repo => repo.id === command.repositoryId);
+    if (!repository || !path.isAbsolute(command.command))
+        return { eligible: false, reason: 'reuse-ineligible-executable-identity' };
+    try {
+        let count = 0, total = 0;
+        const inventory = (inputs, tools) => {
+            const entries = [];
+            const seen = new Set();
+            const visit = (file) => {
+                if (seen.has(file))
+                    return;
+                seen.add(file);
+                if (++count > 10000)
+                    fail('reuse-ineligible-inventory-limit');
+                const stat = lstatSync(file);
+                if (stat.isSymbolicLink() || realpathSync(file) !== path.resolve(file))
+                    fail('reuse-ineligible-symlink');
+                if (stat.isDirectory()) {
+                    entries.push([file, 'directory']);
+                    for (const name of readdirSync(file).sort())
+                        visit(path.join(file, name));
+                }
+                else if (stat.isFile()) {
+                    total += stat.size;
+                    if (total > 256 * 1024 * 1024 || stat.size > 128 * 1024 * 1024)
+                        fail('reuse-ineligible-inventory-limit');
+                    entries.push([file, digest(readFileSync(file)) + ':' + stat.mode]);
+                }
+                else
+                    fail('reuse-ineligible-nonfile-input');
+            };
+            for (const input of inputs) {
+                const file = path.resolve(repository.path, input);
+                if (!tools && !within(repository.path, file))
+                    fail('reuse-ineligible-input-scope');
+                visit(file);
+            }
+            return entries.sort(([left], [right]) => left.localeCompare(right));
+        };
+        const inputs = inventory(policy.inputs, false);
+        const tools = inventory(policy.toolchainInputs, true);
+        if (!tools.some(([file]) => file === path.resolve(command.command)))
+            return { eligible: false, reason: 'reuse-ineligible-executable-not-declared' };
+        // A lockfile alone cannot certify ignored dependency contents. Host manifests
+        // must include each installed dependency directory this convention exposes.
+        for (const directory of ['node_modules', '.venv', 'venv', 'vendor']) {
+            const file = path.join(repository.path, directory);
+            if (existsSync(file) && ![...inputs, ...tools].some(([item]) => item === file))
+                return { eligible: false, reason: 'reuse-ineligible-dependencies-not-declared' };
+        }
+        return { eligible: true, reason: 'snapshot-local-host-declaration', inputHash: digest(canonical(inputs)), toolchainHash: digest(canonical(tools)) };
+    }
+    catch (error) {
+        return { eligible: false, reason: error instanceof Error && error.message.startsWith('reuse-ineligible-') ? error.message : 'reuse-ineligible-input-unavailable' };
+    }
 }
-export async function verifyPipeline(contextInput, raw, log = () => { }, signal) {
+/** Contiguous waves preserve baseline order; an uncertain check is a barrier. */
+export function verificationWaves(commands, maxConcurrency = 1) {
+    if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4)
+        fail('Verification concurrency must be 1–4');
+    const waves = [];
+    let current = [];
+    for (const command of commands) {
+        const policy = command.policy;
+        const independent = Boolean(policy?.independentGroup && policy.resources !== undefined);
+        const fits = independent && current.length < maxConcurrency && current.every(previous => previous.repositoryId !== command.repositoryId && previous.policy?.independentGroup === policy.independentGroup && previous.policy?.resources !== undefined && !previous.policy.resources.some(resource => policy.resources.includes(resource)));
+        if (!fits && current.length) {
+            waves.push(current);
+            current = [];
+        }
+        current.push(command);
+        if (!independent || current.length === maxConcurrency) {
+            waves.push(current);
+            current = [];
+        }
+    }
+    if (current.length)
+        waves.push(current);
+    return waves;
+}
+export async function verifyPipeline(contextInput, raw, log = () => { }, signal, options = {}) {
     const context = validatePipelineContext(contextInput);
     const { request, commands, unverifiedRepositories } = verificationPlan(context, raw);
-    const state = readState(context);
+    let previous;
+    const state = locked(context, () => {
+        const current = readState(context);
+        const problems = planReasons(current, typeof request.planHash === 'string' ? request.planHash : undefined);
+        if (problems.length)
+            fail(problems.join('; '));
+        previous = current.verification;
+        if (current.verification)
+            current.verification = { ...current.verification, valid: false, reason: 'Verification started; previous receipt is no longer current' };
+        current.acceptance = undefined;
+        current.archiveApproval = undefined;
+        saveState(current);
+        return current;
+    });
+    const identityProblems = planReasons(state, typeof request.planHash === 'string' ? request.planHash : undefined);
+    if (identityProblems.length)
+        fail(identityProblems.join('; '));
     const candidateHash = fingerprintCandidate(state);
     const results = [];
-    for (const command of commands) {
-        results.push(await executeCheck(command, log, signal));
-        if (results[results.length - 1].exitCode !== 0)
-            break;
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    signal?.addEventListener('abort', abort, { once: true });
+    if (signal?.aborted)
+        abort();
+    try {
+        for (const wave of verificationWaves(commands, options.maxConcurrency)) {
+            if (controller.signal.aborted)
+                break;
+            const settled = await Promise.allSettled(wave.map(async (command) => {
+                try {
+                    const prefix = `[verification ${command.repositoryId}/${command.label ?? command.key ?? command.command}] `;
+                    const snapshot = verificationSnapshot(context, command);
+                    const old = previous?.valid && previous.kind === 'full' && previous.planHash === request.planHash && previous.candidateHash === candidateHash ? previous.commands.find(item => item.key === command.key && command.key !== undefined) : undefined;
+                    const reuse = snapshot.eligible && old?.snapshot?.eligible && old.exitCode === 0 && old.checkDefinitionHash === digest(canonical(command)) && old.snapshot.inputHash === snapshot.inputHash && old.snapshot.toolchainHash === snapshot.toolchainHash && old.environmentHash === environmentHash(verificationEnvironmentKeys(process.env, old.environmentOverrideKeys)) && old.environmentOverridesHash === digest(canonical(normalizeVerificationEnvironment(command.env ?? {})));
+                    const evidenceId = digest(randomUUID());
+                    if (!reuse) {
+                        const pending = { repositoryId: command.repositoryId, key: command.key, label: command.label, command: command.command, args: command.args, cwd: command.cwd, environmentHash: '', environmentKeys: [], environmentOverrideKeys: [], environmentOverridesHash: '', evidenceId, pending: true, disposition: 'executed', outcome: 'interrupted', exitCode: -1, durationMs: 0, output: '' };
+                        persistCheckEvidence(context, pending, request.planHash ?? digest(canonical(commands)), candidateHash);
+                        await options.onEvidence?.('check-started', { executionId: evidenceId, repositoryId: command.repositoryId, checkId: command.key ?? '', label: command.label ?? command.command });
+                    }
+                    const result = reuse ? { ...old, evidenceId, disposition: 'reused', reusedFrom: old.evidenceId, durationMs: 0, snapshot, reuseReason: 'snapshot-local-identities-match' } : { ...await executeCheck(command, text => log(prefix + text), controller.signal, options.deadline, evidenceId, options.idleTimeoutMs), disposition: 'executed', snapshot, reuseReason: snapshot.eligible ? 'snapshot-local-no-current-match' : snapshot.reason };
+                    const { env: _env, ...definition } = command;
+                    result.checkDefinition = definition;
+                    result.checkDefinitionHash = digest(canonical(command));
+                    const after = verificationSnapshot(context, command);
+                    if (snapshot.eligible && (!after.eligible || after.inputHash !== snapshot.inputHash || after.toolchainHash !== snapshot.toolchainHash)) {
+                        result.exitCode = -1;
+                        result.outcome = 'failed';
+                        result.reuseReason = 'snapshot-inputs-changed-during-verification';
+                    }
+                    if (result.exitCode !== 0)
+                        controller.abort();
+                    persistCheckEvidence(context, result, request.planHash ?? digest(canonical(commands)), candidateHash);
+                    await options.onEvidence?.(reuse ? 'check-reused' : 'check-finished', { executionId: evidenceId, repositoryId: command.repositoryId, checkId: command.key ?? '', label: command.label ?? command.command, exitCode: result.exitCode, durationMs: result.durationMs, reason: result.reuseReason ?? null });
+                    return result;
+                }
+                catch (error) {
+                    controller.abort();
+                    throw error;
+                }
+            }));
+            for (const result of settled) {
+                if (result.status === 'fulfilled')
+                    results.push(result.value);
+                else
+                    controller.abort();
+            }
+            const rejected = settled.find(result => result.status === 'rejected');
+            if (rejected?.status === 'rejected')
+                throw rejected.reason;
+            if (results.some(result => result.exitCode !== 0))
+                break;
+        }
     }
-    return locked(context, () => {
+    finally {
+        signal?.removeEventListener('abort', abort);
+    }
+    const notRunEvidenceIds = [];
+    for (const command of commands.slice(results.length)) {
+        const id = digest(randomUUID());
+        const skipped = { repositoryId: command.repositoryId, key: command.key, label: command.label, command: command.command, args: command.args, cwd: command.cwd, environmentHash: '', environmentKeys: [], environmentOverrideKeys: [], environmentOverridesHash: '', evidenceId: id, disposition: 'not-run', outcome: 'cancelled', exitCode: -1, durationMs: 0, output: 'Not run after cancellation or an earlier failed check' };
+        persistCheckEvidence(context, skipped, request.planHash ?? digest(canonical(commands)), candidateHash);
+        notRunEvidenceIds.push(id);
+    }
+    const receipt = locked(context, () => {
         const current = readState(context);
-        const changed = fingerprintCandidate(current) !== candidateHash || current.revision !== state.revision;
+        const changed = fingerprintCandidate(current) !== candidateHash || current.revision !== state.revision || planReasons(current, request.planHash).length > 0;
         const receipt = {
-            id: randomUUID(), kind: request.kind, scopeHash: state.scopeHash, candidateHash, commands: results,
-            completedAt: new Date().toISOString(), valid: !changed && results.length === commands.length && results.every((result) => result.exitCode === 0),
+            id: randomUUID(), ...(state.verificationPlan ? { planHash: state.verificationPlan.hash } : {}), kind: request.kind, scopeHash: state.scopeHash, candidateHash, commands: results, ...(notRunEvidenceIds.length ? { notRunEvidenceIds } : {}),
+            completedAt: new Date().toISOString(), valid: !changed && !signal?.aborted && (options.deadline === undefined || Date.now() <= options.deadline) && results.length === commands.length && results.every((result) => result.exitCode === 0),
             ...(changed ? { reason: 'Candidate changed during verification' } : results.some((result) => result.exitCode !== 0) ? { reason: 'A verification command failed' } : {}),
             ...(unverifiedRepositories.length ? { unverifiedRepositories } : {}),
         };
         atomicJson(safeChild(pipelineStateDirectory(context), 'receipts/' + receipt.id + '.json'), receipt);
         if (receipt.kind === 'full' || !receipt.valid || !current.verification)
             current.verification = receipt;
+        else if (previous?.valid && previous.candidateHash === candidateHash)
+            current.verification = previous;
         saveState(current);
         return receipt;
     });
+    if (!receipt.valid)
+        for (const result of results) {
+            await options.onEvidence?.('check-invalidated', { executionId: result.evidenceId ?? '', repositoryId: result.repositoryId, checkId: result.key ?? '', label: result.label ?? result.command, reason: receipt.reason ?? 'Verification did not complete successfully' });
+        }
+    return receipt;
 }
 function verificationPlan(context, raw) {
     const request = object(raw);
+    if (request.planHash !== undefined && (typeof request.planHash !== 'string' || !/^[a-f0-9]{64}$/.test(request.planHash)))
+        fail('Invalid verification plan hash');
     const unverified = request.unverified === true;
     if (request.unverified !== undefined && typeof request.unverified !== 'boolean')
         fail('Verification unverified flag must be boolean');
@@ -998,4 +1350,132 @@ export async function runPipelineCli(argv) {
         return 1;
     }
 }
+function evidenceSummary(document) {
+    const { stdout: _out, stderr: _err, sources, ...summary } = document;
+    return { ...summary, sources: sources.map(({ text: _text, ...source }) => source) };
+}
+function persistCheckEvidence(context, result, planHash, candidateHash) {
+    const id = result.evidenceId;
+    const planPath = safeChild(pipelineStateDirectory(context), 'verification/plan.json');
+    const plan = existsSync(planPath) ? object(readJson(planPath)) : undefined;
+    const entries = Array.isArray(plan?.entries) ? plan.entries : [];
+    const item = entries.find(entry => object(entry).id === result.key);
+    const sources = [];
+    for (const source of item?.harness?.sources ?? []) {
+        if (sources.length >= 8)
+            fail('Too many evidence sources');
+        const file = safeChild(pipelineStateDirectory(context), `verification/harnesses/${item.id}/${item.harness.hash}/${source.path}`);
+        if (lstatSync(file).size > 65536)
+            fail('Evidence source exceeds size limit');
+        const bytes = readFileSync(file);
+        if (digest(bytes) !== source.hash)
+            fail('Verification source changed during execution');
+        sources.push({ id: digest(id + '\0' + source.path), displayPath: source.path, hash: source.hash, byteCount: bytes.length, text: bytes.toString('utf8') });
+    }
+    const stdout = result.stdout ?? '', stderr = result.stderr ?? '';
+    const document = {
+        schemaVersion: 1, runId: context.runId, id, executionId: id, checkId: result.key ?? digest(canonical([result.repositoryId, result.command, result.args])), repositoryId: result.repositoryId,
+        label: result.label ?? result.command, origin: item?.origins ?? ['host'], required: true, disposition: result.disposition ?? 'executed', ...(result.reusedFrom ? { reusedFrom: result.reusedFrom } : {}),
+        status: result.outcome === 'cancelled' ? 'cancelled' : result.outcome === 'interrupted' ? 'interrupted' : result.exitCode === 0 ? 'passed' : 'failed',
+        ...(result.reuseReason === undefined ? {} : { reuseReason: result.reuseReason }), recordedAt: new Date().toISOString(),
+        execution: { command: redactRuntimeText(result.command), args: result.args.map(arg => redactRuntimeText(arg)), cwd: result.cwd, configuredTimeoutMs: result.configuredTimeoutMs ?? null, appliedTimeoutMs: result.appliedTimeoutMs ?? null, deadline: result.deadline ?? null, outcome: result.outcome ?? null },
+        planHash, candidateHash, exitCode: result.pending ? null : result.exitCode, durationMs: result.pending ? null : result.durationMs, outputTruncated: result.outputTruncated ?? false,
+        stdout, stderr, stdoutBytes: Buffer.byteLength(stdout), stderrBytes: Buffer.byteLength(stderr), stdoutHash: digest(stdout), stderrHash: digest(stderr), sources,
+    };
+    atomicJson(safeChild(pipelineStateDirectory(context), 'verification/evidence/' + id + '.json'), { document, integrity: digest(canonical(document)) });
+    const summary = evidenceSummary(document);
+    atomicJson(safeChild(pipelineStateDirectory(context), 'verification/evidence-index/' + id + '.json'), { summary, integrity: digest(canonical(summary)) });
+    // Receipt/status payloads carry references and short tails only.
+    delete result.stdout;
+    delete result.stderr;
+}
+/** Historical read: no live repository validation, source execution or lifecycle mutation. */
+export function readVerificationEvidence(context, query = {}) {
+    if (!ID.test(context.runId) || !path.isAbsolute(context.backlogRoot))
+        fail('Invalid evidence scope');
+    if (Object.keys(query).some(key => !['id', 'section', 'sourceId', 'cursor', 'limit'].includes(key)))
+        fail('Invalid evidence query');
+    const section = query.section ?? 'summary', limit = query.limit ?? 25;
+    if (!['summary', 'stdout', 'stderr', 'source'].includes(section) || !Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+        fail('Invalid evidence section or limit');
+    if ((section === 'source') !== (query.sourceId !== undefined) || (!query.id && section !== 'summary'))
+        fail('Source section requires a registered source ID and evidence ID');
+    for (const value of [query.id, query.sourceId])
+        if (value !== undefined && !/^[a-f0-9]{64}$/.test(value))
+            fail('Invalid opaque evidence ID');
+    const directory = safeChild(context.backlogRoot, '.specrails/pipeline/' + context.runId + '/verification/evidence');
+    const binding = digest(canonical({ runId: context.runId, id: query.id ?? null, section, sourceId: query.sourceId ?? null }));
+    let offset = 0;
+    if (query.cursor !== undefined) {
+        if (typeof query.cursor !== 'string' || query.cursor.length > 1024)
+            fail('Invalid evidence cursor');
+        try {
+            const cursor = JSON.parse(Buffer.from(query.cursor, 'base64url').toString('utf8'));
+            if (cursor.binding !== binding || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0)
+                fail('Invalid evidence cursor');
+            offset = cursor.offset;
+        }
+        catch {
+            fail('Invalid evidence cursor');
+        }
+    }
+    const cursor = (next) => Buffer.from(JSON.stringify({ binding, offset: next })).toString('base64url');
+    const load = (id) => {
+        const file = safeChild(directory, id + '.json');
+        if (lstatSync(file).size > 16 * 1024 * 1024)
+            fail('Evidence exceeds size limit');
+        const envelope = object(readJson(file)), document = envelope.document;
+        if (!document || document.schemaVersion !== 1 || document.runId !== context.runId || document.id !== id || digest(canonical(document)) !== envelope.integrity)
+            fail('Evidence integrity check failed');
+        return document;
+    };
+    if (!existsSync(directory) || (query.id && !existsSync(safeChild(directory, query.id + '.json'))))
+        return { schemaVersion: 1, available: false, items: [], truncated: false };
+    if (!query.id) {
+        const indexDirectory = safeChild(context.backlogRoot, '.specrails/pipeline/' + context.runId + '/verification/evidence-index');
+        if (!existsSync(indexDirectory))
+            return { schemaVersion: 1, available: false, items: [], truncated: false };
+        const ids = readdirSync(indexDirectory).filter(file => /^[a-f0-9]{64}\.json$/.test(file)).sort();
+        if (ids.length > 10000)
+            fail('Evidence index exceeds limit');
+        const selected = ids.slice(offset, offset + limit);
+        return { schemaVersion: 1, available: true, items: selected.map(file => {
+                const indexFile = safeChild(indexDirectory, file);
+                if (lstatSync(indexFile).size > 65536)
+                    fail('Evidence summary exceeds limit');
+                const index = object(readJson(indexFile)), summary = object(index.summary);
+                if (summary.id !== file.slice(0, -5) || summary.runId !== context.runId || index.integrity !== digest(canonical(summary)))
+                    fail('Evidence index integrity check failed');
+                return summary;
+            }), truncated: offset + selected.length < ids.length, ...(offset + selected.length < ids.length ? { nextCursor: cursor(offset + selected.length) } : {}) };
+    }
+    const document = load(query.id);
+    if (section === 'summary')
+        return { schemaVersion: 1, available: true, items: [evidenceSummary(document)], truncated: false };
+    const source = section === 'source' ? document.sources.find(source => source.id === query.sourceId) : undefined;
+    if (section === 'source' && !source)
+        fail('Source does not belong to this evidence');
+    let outputDocument = document;
+    const visited = new Set([document.id]);
+    while (outputDocument.reusedFrom && section !== 'source') {
+        if (visited.has(outputDocument.reusedFrom) || visited.size > 100)
+            fail('Invalid reused evidence chain');
+        visited.add(outputDocument.reusedFrom);
+        outputDocument = load(outputDocument.reusedFrom);
+    }
+    const content = source?.text ?? (section === 'stdout' ? outputDocument.stdout : outputDocument.stderr);
+    // Character offsets are opaque. Stop at code-point boundaries within 64 KiB.
+    if (offset > content.length || (offset > 0 && /[\uDC00-\uDFFF]/.test(content[offset] ?? '')))
+        fail('Invalid evidence text cursor');
+    let text = '', bytes = 0;
+    for (const character of content.slice(offset)) {
+        const size = Buffer.byteLength(character);
+        if (bytes + size > 65536)
+            break;
+        text += character;
+        bytes += size;
+    }
+    const next = offset + text.length;
+    return { schemaVersion: 1, available: true, text, byteCount: bytes, totalBytes: Buffer.byteLength(content), truncated: next < content.length || document.outputTruncated, ...(next < content.length ? { nextCursor: cursor(next) } : {}) };
+}
 //# sourceMappingURL=pipeline-state.js.map