specrails-core 6.0.0 → 6.1.0

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

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { bindVerificationPlan, pipelineStateDirectory, validateVerificationRequest } from '../pipeline/pipeline-state.js';
+import { assertProposalInScope, withScopeDefault } from './change-scope.js';
 import { fingerprint } from './durable-store.js';
 import { child, write } from './graph/artifacts.js';
 const SAFE_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
@@ -39,7 +40,10 @@ export function validateProposedChecks(context, raw) {
         text(check.command, 'command', 4096);
         if (!Array.isArray(check.args) || check.args.length > 128 || check.args.some(arg => typeof arg !== 'string' || arg.includes('\0') || arg.length > 4096))
             throw new Error('Invalid verification proposal args');
-        validateVerificationRequest(context, { kind: 'scoped', commands: [check] });
+        if (check.cwd !== undefined && typeof check.cwd !== 'string')
+            throw new Error('Invalid verification proposal cwd');
+        assertProposalInScope(context, check);
+        validateVerificationRequest(context, { kind: 'scoped', commands: [withScopeDefault(context, check)] });
         if (check.kind === 'command') {
             if (check.entrypoint !== undefined || check.files !== undefined)
                 throw new Error('Invalid command proposal: harness fields are forbidden');
@@ -123,7 +127,8 @@ export function readVerificationPlan(context) {
 }
 export function initializeVerificationPlan(context, host, architect, maxConcurrency = 1) {
     const previous = readVerificationPlan(context);
-    const baseline = [['host', host], ['architect', architect]].flatMap(([origin, commands]) => commands.map((command, i) => entry(`${origin}:${command.key ?? `${i}-${fingerprint(normalized(command)).slice(0, 12)}`}`, command.label ?? [command.command, ...command.args].join(' ').slice(0, 256), command, origin)));
+    // The key hashes the command as declared, so a scope default never renames a check.
+    const baseline = [['host', host], ['architect', architect]].flatMap(([origin, commands]) => commands.map((command, i) => entry(`${origin}:${command.key ?? `${i}-${fingerprint(normalized(command)).slice(0, 12)}`}`, command.label ?? [command.command, ...command.args].join(' ').slice(0, 256), withScopeDefault(context, command), origin)));
     if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4)
         throw new Error('Invalid verification concurrency');
     if (previous && fingerprint(previous.baseline) !== fingerprint(baseline))
@@ -156,7 +161,7 @@ export function addDeveloperChecks(context, proposals) {
     const developer = new Map(previous.developer.map(item => [item.key, item]));
     const sources = [];
     for (const check of checked) {
-        const command = { repositoryId: check.repositoryId, command: check.command, args: check.args, ...(check.cwd === undefined ? {} : { cwd: check.cwd }), ...(check.timeoutMs === undefined ? {} : { timeoutMs: check.timeoutMs }) };
+        const command = withScopeDefault(context, { repositoryId: check.repositoryId, command: check.command, args: check.args, ...(check.cwd === undefined ? {} : { cwd: check.cwd }), ...(check.timeoutMs === undefined ? {} : { timeoutMs: check.timeoutMs }) });
         const files = check.files?.slice().sort((a, b) => a.path.localeCompare(b.path)).map(file => ({ path: file.path, hash: bytesHash(file.content), byteCount: Buffer.byteLength(file.content) }));
         const harness = files ? { hash: fingerprint(files), entrypoint: check.entrypoint, sources: files } : undefined;
         const item = entry('dev:' + check.key, check.label, command, 'developer', harness);
@@ -203,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

@@ -7,11 +7,18 @@ export interface PipelineSpec {
     repositoryIds?: string[];
     acceptanceCriteria?: string[];
 }
+/**
+ * `scope`: checkout-relative directories the repository is confined to — a
+ * package registered inside a larger checkout (a monorepo app). Edits outside
+ * them are not part of the change, and a command without `cwd` runs in the
+ * first one. Absent: the whole checkout is the repository.
+ */
 export interface PipelineRepository {
     id: string;
     name: string;
     path: string;
     baseSha?: string;
+    scope?: string[];
 }
 export interface PipelineContext {
     schemaVersion: 1;
@@ -180,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[];
@@ -194,8 +204,24 @@ export interface PreviewFile {
     contentHash?: string;
 }
 export declare function verificationEnvironment(env: NodeJS.ProcessEnv, overrides?: Record<string, string>, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
+/** True when a checkout-relative POSIX path belongs to the repository's scope (always, without a scope). */
+export declare function withinRepositoryScope(repository: Pick<PipelineRepository, 'scope'>, relative: string): boolean;
+/** Where a command without `cwd` runs: the first scope directory, else the checkout root. */
+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;
@@ -205,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<{
@@ -259,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;
@@ -269,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;
@@ -288,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

@@ -83,6 +83,58 @@ function safeChild(root, relative) {
     }
     return target;
 }
+/** Case-insensitive filesystems: compare checkout paths the way the OS resolves them. */
+const foldedPaths = process.platform === 'win32' || process.platform === 'darwin';
+function samePathPrefix(file, directory) {
+    const [a, b] = foldedPaths ? [file.toLowerCase(), directory.toLowerCase()] : [file, directory];
+    return a === b || a.startsWith(b + '/');
+}
+/** Normalized scope: existing, symlink-free directories spelled as on disk. Undefined = whole checkout. */
+function repositoryScope(root, raw) {
+    if (!Array.isArray(raw) || raw.length === 0 || raw.length > 32)
+        fail('Invalid repository scope: expected 1–32 directories');
+    const scope = [];
+    for (const value of raw) {
+        if (typeof value !== 'string' || !value.trim() || value.includes('\0') || value.length > 1024)
+            fail('Invalid repository scope directory');
+        const relative = value.replace(/\\/g, '/').replace(/^(?:\.\/)+/, '').replace(/\/+$/, '');
+        // The checkout root is the whole repository: no narrower scope applies.
+        if (!relative || relative === '.')
+            return undefined;
+        if (/^[a-z]:/i.test(relative) || relative.startsWith('/') || relative.split('/').some(part => !part || part === '.' || part === '..'))
+            fail('Invalid repository scope directory: ' + value);
+        // Spell every component as the directory listing does, so git paths match it.
+        let current = root;
+        const parts = [];
+        for (const part of relative.split('/')) {
+            let name = part;
+            try {
+                const names = readdirSync(current);
+                if (!names.includes(part))
+                    name = names.find(entry => entry.toLowerCase() === part.toLowerCase()) ?? part;
+            }
+            catch { /* the lstat below reports the missing directory */ }
+            current = path.join(current, name);
+            const stat = lstatSync(current, { throwIfNoEntry: false });
+            if (!stat)
+                fail('Repository scope directory does not exist: ' + value);
+            if (stat.isSymbolicLink() || !stat.isDirectory())
+                fail('Repository scope must be a real directory: ' + value);
+            parts.push(name);
+        }
+        scope.push(parts.join('/'));
+    }
+    const unique = [...new Set(scope)];
+    return unique.filter(item => !unique.some(other => other !== item && samePathPrefix(item, other)));
+}
+/** True when a checkout-relative POSIX path belongs to the repository's scope (always, without a scope). */
+export function withinRepositoryScope(repository, relative) {
+    return !repository.scope?.length || repository.scope.some(directory => samePathPrefix(relative, directory));
+}
+/** Where a command without `cwd` runs: the first scope directory, else the checkout root. */
+export function repositoryWorkingDirectory(repository) {
+    return repository.scope?.length ? path.join(repository.path, ...repository.scope[0].split('/')) : repository.path;
+}
 function atomicJson(file, value) {
     mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
     const temp = file + '.' + randomUUID() + '.tmp';
@@ -106,7 +158,9 @@ export function validatePipelineContext(input) {
             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 } : {}) };
+        const root = directory(repo.path);
+        const scope = repo.scope === undefined ? undefined : repositoryScope(root, repo.scope);
+        return { id: repo.id, name: repo.name, path: root, ...(repo.baseSha ? { baseSha: repo.baseSha } : {}), ...(scope ? { scope } : {}) };
     });
     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');
@@ -219,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)
@@ -711,7 +811,7 @@ function validateCommand(context, 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)));
+    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');
     const env = command.env === undefined ? undefined : object(command.env);
@@ -751,6 +851,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] ?? '';
@@ -791,6 +897,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 ?? {});
@@ -1024,7 +1134,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);
@@ -1043,6 +1153,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();
@@ -1062,7 +1199,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 };
@@ -1077,7 +1214,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;
                 }
@@ -1106,25 +1243,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) {
@@ -1352,7 +1479,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;