specrails-core 6.0.1 → 6.2.0

package/dist/agent-runtime/role-routing.js

@@ -1,3 +1,4 @@
+import { isBuiltinRole } from './executor-types.js';
 export function failedCandidateCount(checkpoint) {
     let candidate;
     const failures = new Set();
@@ -16,8 +17,9 @@ export function selectRoleRoute(role, selected, kind, checkpoint, previous) {
     const reason = previous?.tier === 'escalation' ? previous.reason
         : role === 'architect' && kind === 'deepen' ? 'Architect requested its single deeper investigation'
             : role === 'reviewer' && kind === 'repair' ? 'Reviewer required its single protocol repair'
-                : role === 'developer' && ['initial', 'correction'].includes(kind) && failedCandidateCount(checkpoint) >= 2 ? 'Two completed candidate attempts failed verification or review'
-                    : undefined;
+                : !isBuiltinRole(role) && kind === 'repair' ? 'Configured role required its single protocol repair'
+                    : role === 'developer' && ['initial', 'correction'].includes(kind) && failedCandidateCount(checkpoint) >= 2 ? 'Two completed candidate attempts failed verification or review'
+                        : undefined;
     if (!selected.escalation || !reason)
         return { tier: 'base', reason: 'Configured base role selection', selection: selected };
     return { tier: 'escalation', reason, selection: {

package/dist/agent-runtime/role-state.d.ts

@@ -13,6 +13,11 @@ export interface RoleExecutionState {
         attemptId: string;
     }>>;
 }
+/** Bound by the engine to one run/scope/node; the legacy adapter remains file-backed. */
+export interface RoleStatePort {
+    read(): RoleExecutionState;
+    write(state: RoleExecutionState): void;
+}
 /** Host-owned auxiliary state lives under the workflow's existing run lease.
  * A corrupted packet fails explicitly; it is never used as missing context. */
 export declare function readRoleState(directory: string): RoleExecutionState;

package/dist/agent-runtime/verification-plan.d.ts

@@ -53,4 +53,6 @@ export declare function addDeveloperChecks(context: PipelineContext, proposals:
 export declare function expandedPlanCommands(context: PipelineContext, plan: VerificationPlan): VerificationCommand[];
 /** Bind the exact manifest and every source to lifecycle gates. */
 export declare function bindPlan(context: PipelineContext, plan: VerificationPlan): void;
+/** Rebind a checkpoint-owned plan to a new run, retaining the exact admitted checks. */
+export declare function forkVerificationPlan(context: PipelineContext, source: VerificationPlan, sourceContext: PipelineContext): VerificationPlan;
 export {};

package/dist/agent-runtime/verification-plan.js

@@ -208,3 +208,13 @@ export function bindPlan(context, plan) {
         }
     bindVerificationPlan(context, plan.planHash, files);
 }
+/** Rebind a checkpoint-owned plan to a new run, retaining the exact admitted checks. */
+export function forkVerificationPlan(context, source, sourceContext) {
+    const { integrity, ...payload } = source;
+    if (integrity !== fingerprint(payload) || source.scopeHash !== fingerprint(sourceContext) || source.runId !== sourceContext.runId
+        || source.planHash !== fingerprint({ policyVersion: 1, scopeHash: source.scopeHash, executionPolicy: source.executionPolicy, entries: source.entries }))
+        throw new Error('Fork verification plan failed its source integrity check');
+    const plan = savePlan(context, source.baseline, source.developer, null, source.executionPolicy);
+    bindPlan(context, plan);
+    return plan;
+}

package/dist/agent-runtime/workflow-types.d.ts

@@ -52,6 +52,8 @@ export interface WorkflowStepContext {
     attemptId: string;
     attempt: number;
     input: JsonValue;
+    /** Engine-owned, durably claimed operator text; cannot replace the frozen scope. */
+    operatorSteering?: string;
     signal: AbortSignal;
     /** A detached snapshot; modifying it cannot modify the persisted run. */
     checkpoint: WorkflowState;

package/dist/agent-runtime/workflow.d.ts

@@ -1,10 +1,12 @@
-import type { RunWorkflowOptions, WorkflowState } from './workflow-types.js';
+import type { RunWorkflowOptions, WorkflowDefinition, WorkflowState } from './workflow-types.js';
 export * from './workflow-types.js';
 export { readWorkflowState, readWorkflowEnvelope, writeWorkflowEnvelope, WorkflowStoreError, type WorkflowEnvelope } from './durable-store.js';
 export declare class WorkflowError extends Error {
     readonly code: 'INVALID_WORKFLOW' | 'ALREADY_EXISTS' | 'NOT_FOUND' | 'INCOMPATIBLE_RESUME';
     constructor(code: 'INVALID_WORKFLOW' | 'ALREADY_EXISTS' | 'NOT_FOUND' | 'INCOMPATIBLE_RESUME', message: string);
 }
+/** Pure legacy resume identity; preserve node order, declared exits and default metadata. */
+export declare function definitionFingerprint<S extends Record<string, unknown>>(workflow: WorkflowDefinition<S>): string;
 /**
  * Execute a LangGraph state graph with a durable host ledger at every effect
  * boundary. LangGraph owns traversal, state reducers, checkpoints, interrupts

package/dist/agent-runtime/workflow.js

@@ -63,9 +63,13 @@ function validateWorkflow(workflow) {
     if (!Number.isInteger(maxTransitions) || maxTransitions < 1 || maxTransitions > 10_000) {
         throw new WorkflowError('INVALID_WORKFLOW', 'maxTransitions must be an integer from 1 to 10000');
     }
+    return definitionFingerprint(workflow);
+}
+/** Pure legacy resume identity; preserve node order, declared exits and default metadata. */
+export function definitionFingerprint(workflow) {
     return fingerprint({
-        id: workflow.id, version: workflow.version, maxTransitions, entry: workflow.entry,
-        nodes: ids.map(id => ({ id, effect: workflow.nodes[id].effect ?? 'read', maxAttempts: workflow.nodes[id].maxAttempts ?? 1, retrySafe: workflow.nodes[id].retrySafe ?? false, ends: workflow.nodes[id].ends })),
+        id: workflow.id, version: workflow.version, maxTransitions: workflow.maxTransitions ?? 100, entry: workflow.entry,
+        nodes: Object.keys(workflow.nodes).map(id => ({ id, effect: workflow.nodes[id].effect ?? 'read', maxAttempts: workflow.nodes[id].maxAttempts ?? 1, retrySafe: workflow.nodes[id].retrySafe ?? false, ends: workflow.nodes[id].ends })),
     });
 }
 function validateUsage(usage) {
@@ -406,7 +410,7 @@ export async function runWorkflow(options) {
                     },
                     reportInvocation: async (invocation) => {
                         validateUsage(invocation.usage);
-                        if (!Number.isFinite(invocation.durationMs) || invocation.durationMs < 0 || !Number.isSafeInteger(invocation.toolCalls) || invocation.toolCalls < 0)
+                        if (typeof invocation.durationMs !== 'number' || !Number.isFinite(invocation.durationMs) || invocation.durationMs < 0 || typeof invocation.toolCalls !== 'number' || !Number.isSafeInteger(invocation.toolCalls) || invocation.toolCalls < 0)
                             throw new TypeError('Invalid invocation measurement');
                         if (invocation.invocationId && history.invocations?.some(item => item.invocationId === invocation.invocationId))
                             return;

package/dist/agent-runtime/workspace-tools.d.ts

@@ -13,11 +13,11 @@ export declare function canonicalWorkspace(cwd: string, allowedRoots: string[]):
 };
 /** Application tool boundary, not an OS sandbox for concurrent external processes. */
 export declare class WorkspaceTools {
-    private readonly role;
+    private readonly access;
     readonly cwd: string;
     readonly roots: string[];
     private readonly rootAliases;
-    constructor(cwd: string, roots: string[], role: AgentRole);
+    constructor(cwd: string, roots: string[], access: 'read' | 'write' | AgentRole);
     definitions(): WorkspaceToolDefinition[];
     private resolve;
     execute(name: string, input: unknown): string;

package/dist/agent-runtime/workspace-tools.js

@@ -33,12 +33,12 @@ export function canonicalWorkspace(cwd, allowedRoots) {
 }
 /** Application tool boundary, not an OS sandbox for concurrent external processes. */
 export class WorkspaceTools {
-    role;
+    access;
     cwd;
     roots;
     rootAliases;
-    constructor(cwd, roots, role) {
-        this.role = role;
+    constructor(cwd, roots, access) {
+        this.access = access;
         const scope = canonicalWorkspace(cwd, roots);
         this.cwd = scope.cwd;
         this.roots = scope.roots;
@@ -52,8 +52,8 @@ export class WorkspaceTools {
             definition('read_lines', 'Read numbered lines, up to 500 lines / 48 KiB, from a UTF-8 file up to 1 MiB. Returns a full-file SHA-256 for guarded edits.', { ...file, startLine: { type: 'integer', minimum: 1 }, endLine: { type: 'integer', minimum: 1 } }, ['path']),
             definition('search_text', 'Search literal text recursively in source files. Skips dependencies, build output, metadata, binaries and symlinks. Returns bounded numbered matches and a truncation flag.', { ...file, query: { type: 'string' }, maxResults: { type: 'integer', minimum: 1, maximum: 100 } }, ['path', 'query']),
             definition('get_diff', 'Read the staged and unstaged Git diff against HEAD for one file, up to 48 KiB. Untracked files are identified; use read_lines for their content.', file, ['path']),
-            ...(this.role === 'developer' ? [definition('write_file', 'Create or replace a UTF-8 source file (max 256 KiB). Parent directories are created. Runtime metadata cannot be changed.', { ...file, content: { type: 'string' } }, ['path', 'content'])] : []),
-            ...(this.role === 'developer' ? [definition('apply_patch', 'Atomically replace one exact, unique fragment in a UTF-8 file. Rejects missing or ambiguous matches. Optionally guard against stale reads with expectedHash from read_lines.', { ...file, oldText: { type: 'string', minLength: 1 }, newText: { type: 'string' }, expectedHash: { type: 'string' } }, ['path', 'oldText', 'newText'])] : []),
+            ...((this.access === 'write' || this.access === 'developer') ? [definition('write_file', 'Create or replace a UTF-8 source file (max 256 KiB). Parent directories are created. Runtime metadata cannot be changed.', { ...file, content: { type: 'string' } }, ['path', 'content'])] : []),
+            ...((this.access === 'write' || this.access === 'developer') ? [definition('apply_patch', 'Atomically replace one exact, unique fragment in a UTF-8 file. Rejects missing or ambiguous matches. Optionally guard against stale reads with expectedHash from read_lines.', { ...file, oldText: { type: 'string', minLength: 1 }, newText: { type: 'string' }, expectedHash: { type: 'string' } }, ['path', 'oldText', 'newText'])] : []),
         ];
     }
     resolve(raw, write) {
@@ -92,7 +92,7 @@ export class WorkspaceTools {
             throw new Error('Tool input must be a JSON object');
         const args = input;
         if (!this.definitions().some(tool => tool.function.name === name))
-            throw new Error(`Tool '${name}' is unavailable for the ${this.role} role`);
+            throw new Error(`Tool '${name}' is unavailable for the ${this.access} role`);
         const allowed = name === 'write_file' ? ['path', 'content'] : name === 'apply_patch' ? ['path', 'oldText', 'newText', 'expectedHash'] : name === 'read_lines' ? ['path', 'startLine', 'endLine'] : name === 'search_text' ? ['path', 'query', 'maxResults'] : ['path'];
         if (Object.keys(args).some(key => !allowed.includes(key)) || typeof args.path !== 'string')
             throw new Error('Invalid tool arguments');

package/dist/installer/cli.js

@@ -99,6 +99,11 @@ export async function main(argv = process.argv.slice(2)) {
         return await dispatch(subcommand, flags, positionals);
     }
     catch (err) {
+        if (subcommand === 'runtime') {
+            const { runtimeFailure } = await import('../agent-runtime/cli.js');
+            process.stdout.write(JSON.stringify(runtimeFailure(err)) + '\n');
+            return 1;
+        }
         if (isInstallerError(err)) {
             fatal(err.message);
             return err.exitCode;

package/dist/installer/phases/scaffold.d.ts

@@ -4,8 +4,8 @@ import type { Provider } from './provider-detect.js';
  * ships. The implement pipeline depends on all three. Any additional agent
  * comes from a user-authored profile (`custom-*`), never the installer.
  *
- * Mirrors the `allOf` baseline in schemas/profile.v1.json — update
- * both files together if this set ever changes.
+ * Mirrors the required built-in roles in schemas/agent-runtime.schema.json
+ * (`agents`, with the sr- prefix in installed files); keep both in sync.
  */
 export declare const CORE_AGENTS: Set<string>;
 /**

package/dist/installer/phases/scaffold.js

@@ -11,8 +11,8 @@ import { buildManifest, writeManifestFiles } from './manifest.js';
  * ships. The implement pipeline depends on all three. Any additional agent
  * comes from a user-authored profile (`custom-*`), never the installer.
  *
- * Mirrors the `allOf` baseline in schemas/profile.v1.json — update
- * both files together if this set ever changes.
+ * Mirrors the required built-in roles in schemas/agent-runtime.schema.json
+ * (`agents`, with the sr- prefix in installed files); keep both in sync.
  */
 export const CORE_AGENTS = new Set([
     'sr-architect',
@@ -151,10 +151,6 @@ const SKILL_FROM_COMMAND = {
         command: 'implement',
         description: 'sr:implement — Full OpenSpec lifecycle with specialized agents: architect designs, developer implements, reviewer validates. Use for implementing frozen specs or feature descriptions.',
     },
-    'sr-batch-implement': {
-        command: 'batch-implement',
-        description: 'sr:batch-implement — Run multiple frozen specs as one programmatic agent workflow.',
-    },
 };
 /**
  * Provider-static subtrees inside a providerDir that are SHARED via symlink from
@@ -1557,7 +1553,7 @@ function renderInitialAgentsMd(repoRoot) {
         '',
         'Implementation is coordinated by the Specrails programmatic agent runtime.',
         'Use the frozen scope and official OpenSpec workflow supplied for your role.',
-        'Do not start another implement or batch-implement workflow inside a role.',
+        'Do not start another implement workflow inside a role.',
         '',
         '## Repository context',
         '',

package/dist/pipeline/pipeline-state.d.ts

@@ -187,6 +187,9 @@ export interface PipelineState {
         acceptanceHash: string;
     };
     artifactExclusions: string[];
+    /** Explicit engine-owned metadata; absent for all legacy journals. */
+    runtimeExclusions?: readonly string[];
+    repositoryExclusions?: Readonly<Record<string, readonly string[]>>;
     preview?: {
         baseHash: string;
         files: PreviewFile[];
@@ -207,6 +210,18 @@ export declare function withinRepositoryScope(repository: Pick<PipelineRepositor
 export declare function repositoryWorkingDirectory(repository: Pick<PipelineRepository, 'path' | 'scope'>): string;
 export declare function validatePipelineContext(input: unknown): PipelineContext;
 export declare function pipelineStateDirectory(context: PipelineContext): string;
+export type CandidateScope = Pick<PipelineState, 'context' | 'scopeHash' | 'artifactExclusions'> & {
+    /** Engine-owned child journals and artifact paths, never user-defined exclusion patterns. */
+    runtimeExclusions?: readonly string[];
+    repositoryExclusions?: Readonly<Record<string, readonly string[]>>;
+};
+/** Bind only engine-owned metadata paths; callers supply declared run/branch ownership. */
+export declare function bindImplementationExclusions(contextInput: PipelineContext, exclusions: {
+    runtimeExclusions: readonly string[];
+    repositoryExclusions: Readonly<Record<string, readonly string[]>>;
+}): void;
+/** Read the validated implementation journal's dynamic candidate exclusions. */
+export declare function readCandidateScope(contextInput: unknown): CandidateScope;
 export interface CandidateManifest {
     schemaVersion: 1;
     scopeHash: string;
@@ -216,8 +231,8 @@ export interface CandidateManifest {
         files: Array<[string, string]>;
     }>;
 }
-export declare function candidateManifest(state: PipelineState): CandidateManifest;
-export declare function fingerprintCandidate(state: PipelineState): string;
+export declare function candidateManifest(state: CandidateScope): CandidateManifest;
+export declare function fingerprintCandidate(state: CandidateScope): string;
 export declare function initializePipeline(contextInput: unknown, change: string): PipelineState;
 /** Host-owned binding, including immutable harness bytes outside the candidate. */
 export declare function bindVerificationPlan(contextInput: PipelineContext, hash: string, files: Array<{
@@ -270,6 +285,11 @@ export declare function verificationInvocation(command: string, args: string[],
 };
 /** Shared persisted-output/provider diagnostic redaction; preserves line structure. */
 export declare function redactRuntimeText(text: string, env?: NodeJS.ProcessEnv): string;
+/** Structured shell execution with the same scope, environment and tree-kill rules, without a receipt or journal. */
+export declare function executeVerificationCommand(contextInput: unknown, raw: unknown, log?: (text: string) => void, signal?: AbortSignal, options?: {
+    deadline?: number;
+    idleTimeoutMs?: number;
+}): Promise<CommandReceipt>;
 export interface VerificationSnapshot {
     eligible: boolean;
     reason: string;
@@ -280,12 +300,25 @@ export interface VerificationSnapshot {
 export declare function verificationSnapshot(context: PipelineContext, command: VerificationCommand): VerificationSnapshot;
 /** Contiguous waves preserve baseline order; an uncertain check is a barrier. */
 export declare function verificationWaves<T extends VerificationCommand>(commands: T[], maxConcurrency?: number): T[][];
-export declare function verifyPipeline(contextInput: unknown, raw: unknown, log?: (text: string) => void, signal?: AbortSignal, options?: {
+export interface VerificationRunOptions {
     deadline?: number;
     maxConcurrency?: number;
     idleTimeoutMs?: number;
     onEvidence?: (kind: 'check-started' | 'check-finished' | 'check-reused' | 'check-invalidated', payload: Record<string, string | number | null>) => Promise<void>;
-}): Promise<VerificationReceipt>;
+}
+/** Persistence and candidate ownership are bound by the host, never inferred from a journal path. */
+export interface VerificationEvidencePort {
+    candidateHash: string;
+    scopeHash: string;
+    planHash?: string;
+    previous?: VerificationReceipt;
+    isCurrent(): boolean;
+    persistCheck(result: CommandReceipt, planHash: string, candidateHash: string): void | Promise<void>;
+    commitReceipt(receipt: VerificationReceipt): VerificationReceipt | Promise<VerificationReceipt>;
+}
+export declare function verifyPipeline(contextInput: unknown, raw: unknown, log?: (text: string) => void, signal?: AbortSignal, options?: VerificationRunOptions): Promise<VerificationReceipt>;
+/** Same deterministic command/evidence runner for legacy journals and ledger-only engine runs. */
+export declare function executeVerification(contextInput: unknown, raw: unknown, evidence: VerificationEvidencePort, log?: (text: string) => void, signal?: AbortSignal, options?: VerificationRunOptions): Promise<VerificationReceipt>;
 /** Validate a check plan without creating state or executing commands. */
 export declare function validateVerificationRequest(contextInput: unknown, raw: unknown): void;
 export declare function preparePreview(contextInput: unknown, raw: unknown): PipelineState;
@@ -299,6 +332,7 @@ export interface VerificationEvidenceQuery {
     cursor?: string;
     limit?: number;
 }
+export declare function persistCheckEvidence(context: PipelineContext, result: CommandReceipt, planHash: string, candidateHash: string): void;
 /** Historical read: no live repository validation, source execution or lifecycle mutation. */
 export declare function readVerificationEvidence(context: Pick<PipelineContext, 'backlogRoot' | 'runId'>, query?: VerificationEvidenceQuery): {
     nextCursor?: string | undefined;

package/dist/pipeline/pipeline-state.js

@@ -273,10 +273,56 @@ function saveState(state) {
     atomicJson(stateFile(state.context), state);
 }
 function relativeUnix(value) { return value.split(path.sep).join('/'); }
+/** Bind only engine-owned metadata paths; callers supply declared run/branch ownership. */
+export function bindImplementationExclusions(contextInput, exclusions) {
+    const context = validatePipelineContext(contextInput);
+    const root = path.join(context.backlogRoot, '.specrails/pipeline');
+    const runtimeExclusions = [...new Set(exclusions.runtimeExclusions)].sort();
+    for (const item of runtimeExclusions) {
+        const relative = path.relative(root, item);
+        const memory = ['', '-wal', '-shm'].some(suffix => item === path.join(context.backlogRoot, '.specrails/engine-store.sqlite' + suffix));
+        if (memory) {
+            safeChild(context.backlogRoot, path.relative(context.backlogRoot, item));
+            continue;
+        }
+        if (!path.isAbsolute(item) || path.resolve(item) !== item || !ID.test(relative) || relative.includes(path.sep))
+            fail('Implementation runtime exclusion is not an admitted pipeline journal');
+        safeChild(root, relative);
+    }
+    const repositoryExclusions = {};
+    for (const [id, paths] of Object.entries(exclusions.repositoryExclusions)) {
+        const repository = context.repositories.find(repository => repository.id === id);
+        if (!repository)
+            continue; // A scoped child receives the parent union, filtered to its frozen repositories.
+        repositoryExclusions[id] = [...new Set(paths)].sort();
+        for (const item of repositoryExclusions[id]) {
+            if (!/^(?:[a-zA-Z0-9][a-zA-Z0-9._-]*\/)*openspec\/(?:changes|specs)\/[a-z0-9][a-z0-9./-]*$/.test(item))
+                fail('Implementation artifact exclusion is outside declared OpenSpec artifacts');
+            safeChild(repository.path, item);
+        }
+    }
+    locked(context, () => {
+        const state = readState(context);
+        if (canonical(state.runtimeExclusions ?? []) === canonical(runtimeExclusions) && canonical(state.repositoryExclusions ?? {}) === canonical(repositoryExclusions))
+            return;
+        state.runtimeExclusions = runtimeExclusions;
+        state.repositoryExclusions = repositoryExclusions;
+        saveState(state);
+    });
+}
+/** Read the validated implementation journal's dynamic candidate exclusions. */
+export function readCandidateScope(contextInput) {
+    const state = readState(validatePipelineContext(contextInput));
+    return { context: state.context, scopeHash: state.scopeHash, artifactExclusions: [...state.artifactExclusions], ...(state.runtimeExclusions ? { runtimeExclusions: [...state.runtimeExclusions] } : {}), ...(state.repositoryExclusions ? { repositoryExclusions: structuredClone(state.repositoryExclusions) } : {}) };
+}
 function excluded(state, repo, relative) {
     const absolute = path.join(repo.path, relative);
     if (within(pipelineStateDirectory(state.context), absolute))
         return true;
+    if (state.runtimeExclusions?.some(directory => within(directory, absolute)))
+        return true;
+    if (state.repositoryExclusions?.[repo.id]?.some(item => relative === item || relative.startsWith(item + '/')))
+        return true;
     if (relative === '.specrails/runtime' || relative.startsWith('.specrails/runtime/'))
         return true;
     if (repo.id !== state.context.artifactRepositoryId)
@@ -768,6 +814,8 @@ function validateCommand(context, raw) {
     const cwd = command.cwd === undefined ? directory(repositoryWorkingDirectory(repo)) : directory(path.resolve(repo.path, String(command.cwd)));
     if (!within(repo.path, cwd))
         fail('Verification cwd escapes selected repository');
+    if (!withinRepositoryScope(repo, path.relative(repo.path, cwd).split(path.sep).join('/')))
+        fail('Verification cwd escapes selected code workspace');
     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');
@@ -805,6 +853,12 @@ function validateCommand(context, raw) {
 export function verificationInvocation(command, args, cwd, platform = process.platform, env = process.env) {
     if (platform !== 'win32')
         return { command, args };
+    // An explicit shell line (`cmd /d /s /c <line>`) is already cmd syntax. Node's
+    // default quoting would escape its inner quotes with backslashes, which cmd does
+    // not understand. Pass it verbatim: /s strips exactly the outer quotes we add.
+    if (/(^|[\\/])cmd(\.exe)?$/i.test(command) && args.length === 4 && args[0].toLowerCase() === '/d' && args[1].toLowerCase() === '/s' && args[2].toLowerCase() === '/c') {
+        return { command, args: ['/d', '/s', '/c', '"' + args[3] + '"'], windowsVerbatimArguments: true };
+    }
     let resolved = command;
     if (!/\.(cmd|bat|exe|com)$/i.test(command)) {
         const pathValue = Object.entries(env).find(([key]) => key.toLowerCase() === 'path')?.[1] ?? '';
@@ -845,6 +899,10 @@ export function redactRuntimeText(text, env = process.env) {
 }
 /** 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; }
+/** Structured shell execution with the same scope, environment and tree-kill rules, without a receipt or journal. */
+export async function executeVerificationCommand(contextInput, raw, log = () => { }, signal, options = {}) {
+    return executeCheck(validateCommand(validatePipelineContext(contextInput), raw), log, signal, options.deadline, undefined, options.idleTimeoutMs);
+}
 async function executeCheck(command, log, signal, deadline, evidenceId = digest(randomUUID()), idleTimeoutOverrideMs) {
     const started = Date.now();
     const overrides = normalizeVerificationEnvironment(command.env ?? {});
@@ -1078,7 +1136,7 @@ export function verificationWaves(commands, maxConcurrency = 1) {
 }
 export async function verifyPipeline(contextInput, raw, log = () => { }, signal, options = {}) {
     const context = validatePipelineContext(contextInput);
-    const { request, commands, unverifiedRepositories } = verificationPlan(context, raw);
+    const { request } = verificationPlan(context, raw);
     let previous;
     const state = locked(context, () => {
         const current = readState(context);
@@ -1097,6 +1155,33 @@ export async function verifyPipeline(contextInput, raw, log = () => { }, signal,
     if (identityProblems.length)
         fail(identityProblems.join('; '));
     const candidateHash = fingerprintCandidate(state);
+    const isCurrent = () => {
+        const current = readState(context);
+        return fingerprintCandidate(current) === candidateHash && current.revision === state.revision && planReasons(current, request.planHash).length === 0;
+    };
+    return executeVerification(context, raw, {
+        candidateHash, scopeHash: state.scopeHash, planHash: state.verificationPlan?.hash, previous,
+        isCurrent: () => locked(context, isCurrent),
+        persistCheck: (result, planHash, candidate) => persistCheckEvidence(context, result, planHash, candidate),
+        commitReceipt: receipt => locked(context, () => {
+            const current = readState(context);
+            if (!isCurrent())
+                receipt = { ...receipt, valid: false, reason: 'Candidate changed during verification' };
+            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;
+        }),
+    }, log, signal, options);
+}
+/** Same deterministic command/evidence runner for legacy journals and ledger-only engine runs. */
+export async function executeVerification(contextInput, raw, evidence, log = () => { }, signal, options = {}) {
+    const context = validatePipelineContext(contextInput);
+    const { request, commands, unverifiedRepositories } = verificationPlan(context, raw);
+    const { candidateHash, previous } = evidence;
     const results = [];
     const controller = new AbortController();
     const abort = () => controller.abort();
@@ -1116,7 +1201,7 @@ export async function verifyPipeline(contextInput, raw, log = () => { }, signal,
                     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 evidence.persistCheck(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 };
@@ -1131,7 +1216,7 @@ export async function verifyPipeline(contextInput, raw, log = () => { }, signal,
                     }
                     if (result.exitCode !== 0)
                         controller.abort();
-                    persistCheckEvidence(context, result, request.planHash ?? digest(canonical(commands)), candidateHash);
+                    await evidence.persistCheck(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;
                 }
@@ -1160,25 +1245,15 @@ export async function verifyPipeline(contextInput, raw, log = () => { }, signal,
     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);
+        await evidence.persistCheck(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 || planReasons(current, request.planHash).length > 0;
-        const receipt = {
-            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;
+    const changed = !evidence.isCurrent();
+    const receipt = await evidence.commitReceipt({
+        id: randomUUID(), ...(evidence.planHash ? { planHash: evidence.planHash } : {}), kind: request.kind, scopeHash: evidence.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 } : {}),
     });
     if (!receipt.valid)
         for (const result of results) {
@@ -1406,7 +1481,7 @@ 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) {
+export 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;