specrails-core 5.0.0 → 5.1.0

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

@@ -0,0 +1,801 @@
+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';
+const PHASES = ['architect', 'developer', 'reviewer', 'archive', 'ship', 'ci'];
+const TRANSPORT_ENV_KEYS = new Set(['_', 'PWD', 'OLDPWD', 'SHLVL']);
+function verificationEnvironmentKeys(env, overrideKeys = []) {
+    return Object.keys(env).filter((key) => env[key] !== undefined && !TRANSPORT_ENV_KEYS.has(key) && !overrideKeys.includes(key)).sort();
+}
+const ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+const slug = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function fail(message) { throw new Error(message); }
+function digest(value) { return createHash('sha256').update(value).digest('hex'); }
+function canonical(value) {
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    if (value && typeof value === 'object')
+        return '{' + Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => JSON.stringify(k) + ':' + canonical(v)).join(',') + '}';
+    return JSON.stringify(value) ?? 'null';
+}
+function readJson(file) { return JSON.parse(readFileSync(file, 'utf8')); }
+function object(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail('Expected a JSON object');
+    return value;
+}
+function directory(value) {
+    if (typeof value !== 'string' || !path.isAbsolute(value))
+        fail('Execution roots must be absolute paths');
+    const resolved = realpathSync(value);
+    if (!lstatSync(resolved).isDirectory())
+        fail('Execution root is not a directory: ' + value);
+    return resolved;
+}
+function within(root, target) {
+    const relative = path.relative(root, target);
+    return relative === '' || (!relative.startsWith('..' + path.sep) && relative !== '..' && !path.isAbsolute(relative));
+}
+function safeChild(root, relative) {
+    if (!relative || path.isAbsolute(relative) || relative.includes('\0'))
+        fail('Expected a repository-relative path');
+    const target = path.resolve(root, relative);
+    if (!within(root, target) || target === root)
+        fail('Path escapes its repository: ' + relative);
+    let current = root;
+    for (const part of path.relative(root, target).split(path.sep)) {
+        current = path.join(current, part);
+        try {
+            if (lstatSync(current).isSymbolicLink())
+                fail('Refusing a symlink write path: ' + relative);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return target;
+}
+function atomicJson(file, value) {
+    mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temp = file + '.' + randomUUID() + '.tmp';
+    try {
+        writeFileSync(temp, JSON.stringify(value, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+        renameSync(temp, file);
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+export function validatePipelineContext(input) {
+    const data = object(input);
+    if (data.schemaVersion !== 1 || typeof data.runId !== 'string' || !ID.test(data.runId))
+        fail('Invalid execution context version or runId');
+    if (!Array.isArray(data.repositories) || data.repositories.length === 0)
+        fail('Execution context needs repositories');
+    const repositories = data.repositories.map((entry) => {
+        const repo = object(entry);
+        if (typeof repo.id !== 'string' || !ID.test(repo.id) || typeof repo.name !== 'string')
+            fail('Invalid repository identity');
+        if (repo.baseSha !== undefined && (typeof repo.baseSha !== 'string' || !/^[a-f0-9]{40,64}$/.test(repo.baseSha)))
+            fail('Invalid repository base SHA');
+        return { id: repo.id, name: repo.name, path: directory(repo.path), ...(repo.baseSha ? { baseSha: repo.baseSha } : {}) };
+    });
+    if (new Set(repositories.map((repo) => repo.id)).size !== repositories.length || new Set(repositories.map((repo) => repo.path)).size !== repositories.length)
+        fail('Duplicate repository identity or path');
+    const artifactRoot = directory(data.artifactRoot);
+    if (!repositories.some((repo) => repo.id === data.artifactRepositoryId && repo.path === artifactRoot))
+        fail('artifactRoot must match artifactRepositoryId');
+    const ownership = object(data.ownership);
+    for (const key of ['git', 'backlog', 'worktrees'])
+        if (!['host', 'core'].includes(String(ownership[key])))
+            fail('Invalid ownership: ' + key);
+    if (!Array.isArray(data.specs))
+        fail('Frozen specs must be an array');
+    const specs = data.specs.map((entry) => {
+        const spec = object(entry);
+        if (!['string', 'number'].includes(typeof spec.id) || typeof spec.title !== 'string' || typeof spec.description !== 'string')
+            fail('Invalid frozen spec');
+        if (spec.repositoryIds !== undefined && (!Array.isArray(spec.repositoryIds) || !spec.repositoryIds.every((id) => repositories.some((repo) => repo.id === id))))
+            fail('Spec selects an unknown repository');
+        if (spec.acceptanceCriteria !== undefined && (!Array.isArray(spec.acceptanceCriteria) || !spec.acceptanceCriteria.every((x) => typeof x === 'string')))
+            fail('Invalid acceptance criteria');
+        return { id: spec.id, title: spec.title, description: spec.description, ...(spec.repositoryIds ? { repositoryIds: spec.repositoryIds } : {}), ...(spec.acceptanceCriteria ? { acceptanceCriteria: spec.acceptanceCriteria } : {}) };
+    });
+    const backlogRoot = directory(data.backlogRoot);
+    const backlogPath = data.backlogPath === undefined ? path.join(backlogRoot, '.specrails', 'local-tickets.json') : String(data.backlogPath);
+    if (!path.isAbsolute(backlogPath) || !within(backlogRoot, path.resolve(backlogPath)))
+        fail('Backlog path escapes backlogRoot');
+    return { schemaVersion: 1, runId: data.runId, backlogRoot, backlogPath, artifactRoot, artifactRepositoryId: String(data.artifactRepositoryId), repositories, ownership: ownership, specs };
+}
+export function pipelineStateDirectory(context) {
+    return safeChild(context.backlogRoot, '.specrails/pipeline/' + context.runId);
+}
+function locked(context, operation) {
+    const dir = pipelineStateDirectory(context);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = safeChild(dir, 'journal.lock');
+    const owner = { pid: process.pid, token: randomUUID() };
+    const release = (target, token) => {
+        try {
+            if (object(readJson(target)).token === token)
+                rmSync(target);
+        }
+        catch { /* never remove a replacement or uncertain lease */ }
+    };
+    let fd;
+    try {
+        fd = openSync(file, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        // A stable exclusive guard serializes stale-owner recovery. Without it,
+        // two readers of a dead PID could unlink the new winner's live lease.
+        const guard = safeChild(dir, 'journal-reclaim.lock');
+        const recovery = { pid: process.pid, token: randomUUID() };
+        let guardFd;
+        try {
+            guardFd = openSync(guard, 'wx', 0o600);
+        }
+        catch {
+            fail('Pipeline journal recovery is locked; inspect a stale recovery guard before retrying');
+        }
+        try {
+            writeFileSync(guardFd, JSON.stringify(recovery));
+            if (existsSync(file)) {
+                const previousText = readFileSync(file, 'utf8');
+                const previous = object(JSON.parse(previousText));
+                let stale = false;
+                if (typeof previous.pid === 'number' && previous.pid > 0) {
+                    try {
+                        process.kill(previous.pid, 0);
+                    }
+                    catch (error) {
+                        stale = error.code === 'ESRCH';
+                    }
+                }
+                if (!stale || readFileSync(file, 'utf8') !== previousText)
+                    fail('Pipeline journal is locked by another operation');
+                rmSync(file);
+            }
+            // A fast-path contender can win after unlink; exclusive create then
+            // fails instead of deleting that contender's lease or running unlocked.
+            fd = openSync(file, 'wx', 0o600);
+        }
+        finally {
+            closeSync(guardFd);
+            release(guard, recovery.token);
+        }
+    }
+    try {
+        writeFileSync(fd, JSON.stringify(owner));
+        return operation();
+    }
+    finally {
+        closeSync(fd);
+        release(file, owner.token);
+    }
+}
+function stateFile(context) { return path.join(pipelineStateDirectory(context), 'state.json'); }
+function readState(context) {
+    const state = object(readJson(stateFile(context)));
+    if (state.schemaVersion !== 1 || state.runId !== context.runId || state.scopeHash !== digest(canonical(context)))
+        fail('Execution context differs from the frozen journal scope');
+    return state;
+}
+function saveState(state) {
+    state.revision += 1;
+    state.updatedAt = new Date().toISOString();
+    atomicJson(stateFile(state.context), state);
+}
+function relativeUnix(value) { return value.split(path.sep).join('/'); }
+function excluded(state, repo, relative) {
+    const absolute = path.join(repo.path, relative);
+    if (within(pipelineStateDirectory(state.context), absolute))
+        return true;
+    if (['.specrails/kimi-role-wave.json', '.specrails/kimi-role-request.json', '.specrails/kimi-role-merge.json', '.specrails/kimi-role-worktrees/' + state.runId + '.json'].includes(relative))
+        return true;
+    if (relative === '.specrails/runtime' || relative.startsWith('.specrails/runtime/'))
+        return true;
+    if (repo.id !== state.context.artifactRepositoryId)
+        return false;
+    return state.artifactExclusions.some((item) => relative === item || relative.startsWith(item + '/'));
+}
+function fileFingerprint(file, ancestors = new Set(), budget = { entries: 0, bytes: 0 }, linkedTree = false) {
+    const stat = lstatSync(file, { throwIfNoEntry: false });
+    if (!stat) {
+        if (linkedTree)
+            fail('Candidate has a missing symlink target: ' + file);
+        return 'deleted';
+    }
+    if (++budget.entries > 50_000)
+        fail('Linked candidate tree exceeds fingerprint entry limit: ' + file);
+    if (stat.isSymbolicLink()) {
+        const link = readlinkSync(file);
+        let target;
+        try {
+            target = realpathSync(file);
+        }
+        catch {
+            fail('Candidate has a dangling or cyclic symlink: ' + file);
+        }
+        if (ancestors.has(target))
+            fail('Candidate has a cyclic linked directory: ' + file);
+        const next = new Set(ancestors);
+        next.add(target);
+        return 'link:' + link + ':' + fileFingerprint(target, next, budget, true);
+    }
+    if (stat.isDirectory() && linkedTree) {
+        // Framework directory links are normal. Hash their actual inputs, not only
+        // link text, with deterministic traversal and bounds. Git administration is
+        // not a source input; dependency/output directories are not blindly hidden.
+        const children = readdirSync(file, { withFileTypes: true }).filter((entry) => entry.name !== '.git').sort((a, b) => a.name.localeCompare(b.name));
+        return 'directory:' + digest(canonical(children.map((entry) => [entry.name, fileFingerprint(path.join(file, entry.name), ancestors, budget, true)])));
+    }
+    if (!stat.isFile())
+        fail('Candidate contains a directory entry or unsupported file: ' + file);
+    budget.bytes += stat.size;
+    if (linkedTree && budget.bytes > 256 * 1024 * 1024)
+        fail('Linked candidate inputs exceed fingerprint byte limit: ' + file);
+    return (stat.mode & 0o111 ? 'executable:' : 'file:') + digest(readFileSync(file));
+}
+function trackedFiles(repo) {
+    // A provider's temporary GIT_CONFIG_COUNT/excludesFile must not hide
+    // candidate files from verification or change receipt validity at handoff.
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+    env.GIT_CONFIG_NOSYSTEM = '1';
+    env.GIT_CONFIG_GLOBAL = process.platform === 'win32' ? 'NUL' : '/dev/null';
+    const result = spawnSync('git', ['-c', 'core.excludesFile=', '-C', repo.path, 'ls-files', '-z', '--cached', '--others', '--exclude-standard'], { env, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, windowsHide: true });
+    if (result.error || result.status !== 0)
+        fail('Cannot fingerprint repository ' + repo.name + ': ' + (result.error?.message ?? result.stderr));
+    return [...new Set(result.stdout.split('\0').filter(Boolean))].sort();
+}
+export function fingerprintCandidate(state) {
+    const entries = state.context.repositories.map((repo) => ({
+        id: repo.id, path: repo.path,
+        files: trackedFiles(repo).filter((file) => !excluded(state, repo, relativeUnix(file))).map((file) => [relativeUnix(file), fileFingerprint(path.join(repo.path, file))]),
+    }));
+    return digest(canonical(entries));
+}
+function activeArtifactPath(state) { return state.archivePath ?? path.join(state.context.artifactRoot, 'openspec', 'changes', state.change); }
+function artifactFingerprint(state) {
+    const root = activeArtifactPath(state);
+    if (!existsSync(root))
+        return 'missing';
+    const result = [];
+    const walk = (dir) => {
+        for (const item of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const file = path.join(dir, item.name);
+            if (item.name === 'confidence-score.json')
+                continue;
+            if (item.isDirectory())
+                walk(file);
+            else {
+                const relative = relativeUnix(path.relative(root, file));
+                const fingerprint = relative === 'tasks.md' ? digest(readFileSync(file, 'utf8').replace(/^(\s*-\s+)\[[ x]\]/gm, '$1[ ]')) : fileFingerprint(file);
+                result.push([relative, fingerprint]);
+            }
+        }
+    };
+    walk(root);
+    return digest(canonical(result));
+}
+export function initializePipeline(contextInput, change) {
+    const context = validatePipelineContext(contextInput);
+    if (!slug.test(change))
+        fail('Invalid OpenSpec change name');
+    return locked(context, () => {
+        if (existsSync(stateFile(context))) {
+            const existing = readState(context);
+            if (existing.change !== change)
+                fail('A runId cannot be reused for another change');
+            return existing;
+        }
+        const now = new Date().toISOString();
+        const state = {
+            schemaVersion: 1, runId: context.runId, change, context, scopeHash: digest(canonical(context)), revision: 0,
+            createdAt: now, updatedAt: now,
+            phases: Object.fromEntries(PHASES.map((phase) => [phase, { status: 'pending' }])),
+            artifactExclusions: ['openspec/changes/' + change],
+        };
+        atomicJson(path.join(pipelineStateDirectory(context), 'context.json'), context);
+        saveState(state);
+        return state;
+    });
+}
+function environmentHash(keys, overrides = {}, env = process.env) {
+    return digest(canonical(Object.fromEntries(keys.map((key) => [key, overrides[key] ?? env[key] ?? null]))));
+}
+function inspectReceipt(state, env = process.env) {
+    const receipt = state.verification;
+    const reasons = [];
+    if (!receipt)
+        return { valid: false, reasons: ['No verification receipt'] };
+    if (!receipt.valid || receipt.kind !== 'full')
+        reasons.push(receipt.reason ?? 'No successful full verification');
+    if (receipt.scopeHash !== state.scopeHash)
+        reasons.push('Spec scope changed');
+    if (receipt.candidateHash !== fingerprintCandidate(state))
+        reasons.push('Candidate files changed');
+    for (const command of receipt.commands) {
+        if (command.exitCode !== 0)
+            reasons.push('Command failed: ' + command.command);
+        const currentKeys = verificationEnvironmentKeys(env, command.environmentOverrideKeys ?? []);
+        if (canonical(currentKeys) !== canonical(command.environmentKeys) || command.environmentHash !== environmentHash(currentKeys, {}, env))
+            reasons.push('Verification environment changed: ' + command.command);
+    }
+    return { valid: reasons.length === 0, reasons: [...new Set(reasons)], receipt };
+}
+function designGate(state) {
+    const root = activeArtifactPath(state);
+    for (const file of ['proposal.md', 'design.md', 'tasks.md'])
+        if (!existsSync(path.join(root, file)))
+            fail('Missing architecture artifact: ' + file);
+    const specs = path.join(root, 'specs');
+    if (!existsSync(specs) || !readdirSync(specs, { withFileTypes: true }).some((entry) => entry.isDirectory() && existsSync(path.join(specs, entry.name, 'spec.md'))))
+        fail('Missing architecture delta specs');
+    const design = object(readJson(path.join(root, 'design-confidence.json')));
+    if (!['high', 'medium'].includes(String(design.confidence)))
+        fail('Design confidence blocks implementation');
+}
+function confidenceGate(state) {
+    const file = path.join(activeArtifactPath(state), 'confidence-score.json');
+    if (!existsSync(file))
+        fail('Required confidence-score.json is missing');
+    const score = object(readJson(file));
+    const aspects = object(score.aspects);
+    if (score.change !== state.change || typeof score.overall !== 'number' || score.overall < 70)
+        fail('Confidence score does not pass');
+    for (const [name, threshold] of Object.entries({ type_correctness: 60, pattern_adherence: 60, test_coverage: 60, security: 75, architectural_alignment: 60 })) {
+        if (typeof aspects[name] !== 'number' || Number(aspects[name]) < threshold || Number(aspects[name]) > 100)
+            fail('Confidence aspect does not pass: ' + name);
+    }
+    if (score.overall > 100)
+        fail('Invalid confidence score');
+}
+function taskGate(state) {
+    const tasks = readFileSync(path.join(activeArtifactPath(state), 'tasks.md'), 'utf8');
+    if (!/^\s*-\s+\[x\]/m.test(tasks) || /^\s*-\s+\[ \]/m.test(tasks))
+        fail('Required implementation tasks remain incomplete');
+}
+export function checkArchive(contextInput) {
+    const context = validatePipelineContext(contextInput);
+    return locked(context, () => {
+        const state = readState(context);
+        if (state.phases.reviewer.status !== 'done')
+            fail('Review must complete before archive');
+        const verification = inspectReceipt(state);
+        if (!verification.valid)
+            fail('Archive blocked: ' + verification.reasons.join('; '));
+        if (state.phases.reviewer.candidateHash !== fingerprintCandidate(state))
+            fail('Review does not describe the current candidate');
+        if (state.phases.reviewer.artifactHash !== artifactFingerprint(state))
+            fail('Review artifacts changed after review');
+        designGate(state);
+        if (state.phases.architect.artifactHash !== artifactFingerprint(state))
+            fail('Architecture artifacts changed after design approval');
+        taskGate(state);
+        confidenceGate(state);
+        state.archiveApproval = { candidateHash: fingerprintCandidate(state), artifactHash: artifactFingerprint(state), confidenceHash: digest(readFileSync(path.join(activeArtifactPath(state), 'confidence-score.json'))) };
+        saveState(state);
+        return state;
+    });
+}
+export function transitionPipeline(contextInput, phase, status, reason) {
+    const context = validatePipelineContext(contextInput);
+    if (!PHASES.includes(phase) || !['running', 'done', 'blocked', 'failed', 'skipped'].includes(status))
+        fail('Invalid phase transition');
+    return locked(context, () => {
+        const state = readState(context);
+        if ((status === 'blocked' || status === 'failed') && !reason?.trim())
+            fail('Blocked and failed phases require a reason');
+        if (status === 'skipped' && !((phase === 'ship' || phase === 'ci') && context.ownership.git === 'host'))
+            fail('Only host-owned shipping/CI can be skipped');
+        if ((phase === 'ship' || phase === 'ci') && context.ownership.git === 'host' && status !== 'skipped')
+            fail('Host owns delivery; Core cannot ship or monitor its CI');
+        if (status === 'running' || status === 'done') {
+            const before = PHASES.slice(0, PHASES.indexOf(phase));
+            if (before.some((p) => !['done', 'skipped'].includes(state.phases[p].status)))
+                fail('A required earlier phase is incomplete');
+        }
+        if (status === 'done') {
+            if (phase === 'architect') {
+                const root = activeArtifactPath(state);
+                designGate(state);
+                const specsDir = path.join(root, 'specs');
+                if (existsSync(specsDir)) {
+                    for (const item of readdirSync(specsDir, { withFileTypes: true })) {
+                        if (item.isDirectory() && slug.test(item.name))
+                            state.artifactExclusions.push('openspec/specs/' + item.name);
+                    }
+                }
+            }
+            if (phase === 'developer' || phase === 'reviewer') {
+                designGate(state);
+                if (state.phases.architect.artifactHash !== artifactFingerprint(state))
+                    fail('Architecture artifacts changed after design approval');
+                taskGate(state);
+                const verification = inspectReceipt(state);
+                if (!verification.valid)
+                    fail('Fresh full verification required: ' + verification.reasons.join('; '));
+            }
+            if (phase === 'reviewer')
+                confidenceGate(state);
+            if (phase === 'archive') {
+                const archiveRoot = path.join(context.artifactRoot, 'openspec', 'changes', 'archive');
+                const candidates = existsSync(archiveRoot) ? readdirSync(archiveRoot).filter((name) => name.endsWith('-' + state.change)) : [];
+                if (existsSync(activeArtifactPath(state)) || candidates.length !== 1)
+                    fail('Archive location must be unambiguous and active change moved');
+                state.archivePath = path.join(archiveRoot, candidates[0]);
+                state.artifactExclusions.push(relativeUnix(path.relative(context.artifactRoot, state.archivePath)));
+                taskGate(state);
+                confidenceGate(state);
+                const approval = state.archiveApproval;
+                if (!approval || approval.candidateHash !== fingerprintCandidate(state) || approval.artifactHash !== artifactFingerprint(state) || approval.confidenceHash !== digest(readFileSync(path.join(activeArtifactPath(state), 'confidence-score.json'))))
+                    fail('Archive was not authorized for this exact reviewed candidate');
+            }
+            state.phases[phase] = { status, candidateHash: fingerprintCandidate(state), artifactHash: artifactFingerprint(state), completedAt: new Date().toISOString() };
+        }
+        else {
+            state.phases[phase] = { status, ...(reason ? { reason } : {}) };
+            if (status === 'running')
+                for (const later of PHASES.slice(PHASES.indexOf(phase) + 1))
+                    state.phases[later] = { status: 'pending' };
+        }
+        saveState(state);
+        return state;
+    });
+}
+export function inspectPipeline(contextInput) {
+    const context = validatePipelineContext(contextInput);
+    const state = readState(context);
+    const candidate = fingerprintCandidate(state);
+    const verification = inspectReceipt(state);
+    let resumePhase = null;
+    for (const phase of PHASES) {
+        const record = state.phases[phase];
+        if (record.status === 'skipped')
+            continue;
+        if (record.status !== 'done') {
+            resumePhase = phase;
+            break;
+        }
+        if (phase === 'architect' && record.artifactHash !== artifactFingerprint(state)) {
+            resumePhase = phase;
+            break;
+        }
+        if ((phase === 'developer' || phase === 'reviewer') && record.candidateHash !== candidate) {
+            if (phase === 'developer' && state.phases.reviewer.status === 'done' && state.phases.reviewer.candidateHash === candidate)
+                continue;
+            resumePhase = phase === 'developer' ? 'reviewer' : phase;
+            break;
+        }
+    }
+    if (!verification.valid && state.phases.developer.status === 'done' && (resumePhase === null || ['archive', 'ship', 'ci'].includes(resumePhase)))
+        resumePhase = 'reviewer';
+    return { schemaVersion: 1, runId: context.runId, change: state.change, context, stateDir: pipelineStateDirectory(context), resumePhase, phases: state.phases, verification };
+}
+function validateCommand(context, raw) {
+    const command = object(raw);
+    const repo = context.repositories.find((item) => item.id === command.repositoryId);
+    if (!repo || typeof command.command !== 'string' || !command.command || command.command.includes('\0') || !Array.isArray(command.args) || !command.args.every((arg) => typeof arg === 'string' && !arg.includes('\0')))
+        fail('Invalid verification command');
+    const cwd = command.cwd === undefined ? repo.path : directory(path.resolve(repo.path, String(command.cwd)));
+    if (!within(repo.path, cwd))
+        fail('Verification cwd escapes selected repository');
+    const env = command.env === undefined ? undefined : object(command.env);
+    if (env && Object.values(env).some((value) => typeof value !== 'string' || value.includes('\0')))
+        fail('Invalid verification environment');
+    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 };
+}
+/**
+ * Native executables retain structured argv; Windows script shims need cmd.
+ * This runtime is copied as one standalone module into .specrails/runtime,
+ * without installer util/exec. Keep this builtins-only equivalent local rather
+ * than importing a helper absent from installed projects. Like runCommand, it
+ * handles Windows shims; unlike a shell string it refuses ambiguous arguments.
+ */
+export function verificationInvocation(command, args, cwd, platform = process.platform, env = process.env) {
+    if (platform !== 'win32')
+        return { command, args };
+    let resolved = command;
+    if (!/\.(cmd|bat|exe|com)$/i.test(command)) {
+        const pathValue = Object.entries(env).find(([key]) => key.toLowerCase() === 'path')?.[1] ?? '';
+        const extensions = (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';');
+        const bases = /[\\/]/.test(command) ? [path.win32.resolve(cwd, command)] : [path.win32.join(cwd, command), ...pathValue.split(';').map((dir) => path.win32.join(dir, command))];
+        for (const base of bases) {
+            const candidate = extensions.map((extension) => base + extension.toLowerCase()).find((file) => existsSync(file));
+            if (candidate) {
+                resolved = candidate;
+                break;
+            }
+        }
+    }
+    if (!/\.(cmd|bat)$/i.test(resolved))
+        return { command: resolved, args };
+    // cmd performs a second parse, including environment expansion. Rather than
+    // silently reinterpret a structured argument, reject ambiguous script input.
+    // Call node/python/the native tool executable directly for these arguments.
+    if ([resolved, ...args].some((value) => /[\r\n"%!^&|<>]/.test(value)))
+        fail('Windows script-shim arguments contain cmd syntax; invoke the underlying executable with structured argv instead');
+    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) {
+    const started = Date.now();
+    const overrideKeys = Object.keys(command.env ?? {}).sort();
+    const keys = verificationEnvironmentKeys(process.env, overrideKeys);
+    const hash = environmentHash(keys);
+    const overridesHash = digest(canonical(command.env ?? {}));
+    let output = '';
+    let exitCode = -1;
+    await new Promise((resolve) => {
+        let child;
+        let timer;
+        let done = false;
+        const finish = (code) => { if (done)
+            return; done = true; exitCode = code; if (timer)
+            clearTimeout(timer); resolve(); };
+        try {
+            const invocation = verificationInvocation(command.command, command.args, command.cwd);
+            child = spawn(invocation.command, invocation.args, { windowsVerbatimArguments: invocation.windowsVerbatimArguments, cwd: command.cwd, env: { ...process.env, ...command.env }, shell: false, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+        }
+        catch (error) {
+            output = String(error);
+            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); });
+        child.on('close', (code) => finish(code ?? -1));
+        timer = setTimeout(() => {
+            output += '\nVerification command timed out';
+            if (child.pid) {
+                if (process.platform === 'win32')
+                    spawnSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true });
+                else {
+                    try {
+                        process.kill(-child.pid, 'SIGKILL');
+                    }
+                    catch { /* already exited */ }
+                }
+            }
+            finish(-1);
+        }, command.timeoutMs);
+    });
+    return { repositoryId: command.repositoryId, command: command.command, args: command.args, cwd: command.cwd, environmentHash: hash, environmentKeys: keys, environmentOverrideKeys: overrideKeys, environmentOverridesHash: overridesHash, exitCode, durationMs: Date.now() - started, output };
+}
+export async function verifyPipeline(contextInput, raw, log = () => { }) {
+    const context = validatePipelineContext(contextInput);
+    const { request, commands } = verificationPlan(context, raw);
+    const state = readState(context);
+    const candidateHash = fingerprintCandidate(state);
+    const results = [];
+    for (const command of commands) {
+        results.push(await executeCheck(command, log));
+        if (results[results.length - 1].exitCode !== 0)
+            break;
+    }
+    return locked(context, () => {
+        const current = readState(context);
+        const changed = fingerprintCandidate(current) !== candidateHash || current.revision !== state.revision;
+        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),
+            ...(changed ? { reason: 'Candidate changed during verification' } : results.some((result) => result.exitCode !== 0) ? { reason: 'A verification command failed' } : {}),
+        };
+        atomicJson(safeChild(pipelineStateDirectory(context), 'receipts/' + receipt.id + '.json'), receipt);
+        if (receipt.kind === 'full' || !receipt.valid || !current.verification)
+            current.verification = receipt;
+        saveState(current);
+        return receipt;
+    });
+}
+function verificationPlan(context, raw) {
+    const request = object(raw);
+    if (!['full', 'scoped'].includes(String(request.kind)) || !Array.isArray(request.commands) || request.commands.length === 0 || request.commands.length > 100)
+        fail('Verification requires bounded structured commands');
+    const commands = request.commands.map((command) => validateCommand(context, command));
+    if (request.kind === 'full' && context.repositories.some((repo) => !commands.some((command) => command.repositoryId === repo.id)))
+        fail('Full verification must cover every selected repository');
+    return { request, commands };
+}
+export function preparePreview(contextInput, raw) {
+    const context = validatePipelineContext(contextInput);
+    const request = object(raw);
+    if (!Array.isArray(request.files) || request.files.length === 0)
+        fail('Preview needs explicit files');
+    const inputFiles = request.files;
+    return locked(context, () => {
+        const state = readState(context);
+        const files = inputFiles.map((item, index) => {
+            const input = object(item);
+            const repo = context.repositories.find((entry) => entry.id === input.repositoryId);
+            if (!repo || typeof input.path !== 'string' || !['write', 'delete'].includes(String(input.operation)))
+                fail('Invalid preview file');
+            const target = safeChild(repo.path, input.path);
+            if (excluded(state, repo, relativeUnix(path.relative(repo.path, target))))
+                fail('Preview cannot overwrite runtime or lifecycle artifacts');
+            if (input.operation === 'delete')
+                return { repositoryId: repo.id, path: relativeUnix(path.relative(repo.path, target)), operation: 'delete' };
+            if (typeof input.sourcePath !== 'string' || !path.isAbsolute(input.sourcePath))
+                fail('Preview sourcePath must be absolute');
+            const source = realpathSync(input.sourcePath);
+            if (![context.backlogRoot, ...context.repositories.map((entry) => entry.path)].some((root) => within(root, source)))
+                fail('Preview source is outside execution scope');
+            const bytes = readFileSync(source);
+            const cached = safeChild(pipelineStateDirectory(context), 'preview/' + String(index));
+            mkdirSync(path.dirname(cached), { recursive: true, mode: 0o700 });
+            writeFileSync(cached, bytes, { mode: 0o600 });
+            return { repositoryId: repo.id, path: relativeUnix(path.relative(repo.path, target)), operation: 'write', sourcePath: cached, contentHash: digest(bytes) };
+        });
+        if (new Set(files.map((file) => file.repositoryId + ':' + file.path)).size !== files.length)
+            fail('Duplicate preview target');
+        state.preview = { baseHash: fingerprintCandidate(state), files, createdAt: new Date().toISOString() };
+        saveState(state);
+        return state;
+    });
+}
+export async function applyPreview(contextInput, verificationRequest, log = () => { }) {
+    const context = validatePipelineContext(contextInput);
+    verificationPlan(context, verificationRequest);
+    locked(context, () => {
+        const state = readState(context);
+        if (!state.preview || fingerprintCandidate(state) !== state.preview.baseHash)
+            fail('Preview base changed; create a new preview instead of overwriting work');
+        const operations = state.preview.files.map((file) => {
+            const repo = context.repositories.find((entry) => entry.id === file.repositoryId);
+            const target = safeChild(repo.path, file.path);
+            if (file.operation === 'write' && (!file.sourcePath || !within(path.join(pipelineStateDirectory(context), 'preview'), realpathSync(file.sourcePath))))
+                fail('Preview cache path escapes its owned directory');
+            const content = file.operation === 'write' ? readFileSync(file.sourcePath) : null;
+            if (content && digest(content) !== file.contentHash)
+                fail('Preview content changed');
+            return { target, content, before: existsSync(target) ? readFileSync(target) : null };
+        });
+        const applied = [];
+        try {
+            for (const operation of operations) {
+                mkdirSync(path.dirname(operation.target), { recursive: true });
+                if (operation.content)
+                    writeFileSync(operation.target, operation.content);
+                else
+                    rmSync(operation.target);
+                applied.push(operation);
+            }
+        }
+        catch (error) {
+            for (const operation of applied.reverse()) {
+                if (operation.before)
+                    writeFileSync(operation.target, operation.before);
+                else
+                    rmSync(operation.target, { force: true });
+            }
+            throw error;
+        }
+        state.verification = undefined;
+        for (const phase of PHASES.slice(1))
+            state.phases[phase] = { status: 'pending' };
+        saveState(state);
+    });
+    // Applied files remain reviewable on failure; never ship based on preview's
+    // unchanged baseline. The actual applied candidate owns this fresh receipt.
+    return verifyPipeline(context, verificationRequest, log);
+}
+function parseArguments(argv) {
+    const operation = argv[0] ?? 'status';
+    const flags = {};
+    for (let i = 1; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--'))
+            fail('Unexpected positional argument: ' + arg);
+        const next = argv[i + 1];
+        if (next && !next.startsWith('--')) {
+            flags[arg.slice(2)] = next;
+            i++;
+        }
+        else
+            flags[arg.slice(2)] = true;
+    }
+    return { operation, flags };
+}
+function resolveContext(flags, operation) {
+    const file = typeof flags.context === 'string' ? flags.context : process.env.SPECRAILS_EXECUTION_CONTEXT;
+    if (file)
+        return validatePipelineContext(readJson(file));
+    const cwd = realpathSync(process.cwd());
+    const legacy = safeChild(cwd, '.specrails/pipeline-context.json');
+    if (existsSync(legacy)) {
+        const previous = validatePipelineContext(readJson(legacy));
+        if (operation !== 'init')
+            return previous;
+        if (existsSync(stateFile(previous)) && readState(previous).change === flags.change)
+            return previous;
+    }
+    if (operation !== 'init')
+        fail('Initialize the pipeline or supply SPECRAILS_EXECUTION_CONTEXT');
+    const repo = realpathSync(process.env.SPECRAILS_REPO_DIR ?? cwd);
+    let scope = {};
+    if (typeof flags['scope-request'] === 'string')
+        scope = object(readJson(flags['scope-request']));
+    const backlogPath = typeof flags['backlog-path'] === 'string' ? flags['backlog-path'] : path.join(cwd, '.specrails', 'local-tickets.json');
+    let specs = scope.specs ?? [];
+    if (typeof flags.tickets === 'string') {
+        if (scope.specs !== undefined)
+            fail('Choose --tickets or --scope-request specs, not both');
+        const ids = flags.tickets.split(',').map((id) => id.trim().replace(/^#/, '')).filter(Boolean);
+        if (!ids.length || new Set(ids).size !== ids.length || ids.some((id) => !/^[a-zA-Z0-9._-]+$/.test(id)))
+            fail('Invalid or duplicate ticket IDs');
+        const tickets = object(object(readJson(backlogPath)).tickets);
+        specs = ids.map((id) => {
+            if (!tickets[id])
+                fail('Ticket not found in backlog: ' + id);
+            const ticket = object(tickets[id]);
+            if (typeof ticket.title !== 'string')
+                fail('Ticket title is missing: ' + id);
+            return { id: ticket.id ?? id, title: ticket.title, description: ticket.description ?? '',
+                ...(ticket.acceptanceCriteria ? { acceptanceCriteria: ticket.acceptanceCriteria } : {}),
+                ...(ticket.repositoryIds ? { repositoryIds: ticket.repositoryIds } : {}) };
+        });
+    }
+    const context = validatePipelineContext({
+        schemaVersion: 1, runId: randomUUID(), backlogRoot: cwd, backlogPath, artifactRoot: repo, artifactRepositoryId: 'primary',
+        repositories: [{ id: 'primary', name: path.basename(repo), path: repo }], specs,
+        ownership: scope.ownership ?? { git: 'host', backlog: 'host', worktrees: 'host' },
+    });
+    atomicJson(legacy, context);
+    return context;
+}
+export async function runPipelineCommand(flags, positionals) {
+    const operation = positionals[0] ?? 'status';
+    const context = resolveContext(flags, operation);
+    let result;
+    switch (operation) {
+        case 'init':
+            result = initializePipeline(context, String(flags.change ?? ''));
+            break;
+        case 'status':
+            result = inspectPipeline(context);
+            break;
+        case 'phase':
+            result = transitionPipeline(context, String(flags.phase), String(flags.status), typeof flags.reason === 'string' ? flags.reason : undefined);
+            break;
+        case 'archive-check':
+            result = checkArchive(context);
+            break;
+        case 'verify':
+        case 'apply-preview': {
+            if (typeof flags.request !== 'string')
+                fail('Provide --request with structured verification JSON');
+            const request = readJson(flags.request);
+            const receipt = operation === 'verify' ? await verifyPipeline(context, request, (text) => process.stderr.write(text)) : await applyPreview(context, request, (text) => process.stderr.write(text));
+            console.log(JSON.stringify(receipt));
+            return receipt.valid ? 0 : 1;
+        }
+        case 'preview':
+            if (typeof flags.request !== 'string')
+                fail('Provide --request with preview file JSON');
+            result = preparePreview(context, readJson(flags.request));
+            break;
+        default: fail('Unknown pipeline operation: ' + operation);
+    }
+    console.log(JSON.stringify(result));
+    return 0;
+}
+export async function runPipelineCli(argv) {
+    try {
+        const { operation, flags } = parseArguments(argv);
+        return await runPipelineCommand(flags, [operation]);
+    }
+    catch (error) {
+        console.error('Pipeline: ' + (error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+}
+//# sourceMappingURL=pipeline-state.js.map