specrails-core 6.0.1 → 6.2.0

package/dist/agent-runtime/evaluation.js

@@ -10,6 +10,13 @@ import { ExecutorRegistry } from './executors.js';
 import { OpenSpecTools } from './openspec.js';
 import { validatePipelineContext } from '../pipeline/pipeline-state.js';
 import { runtimeEfficiency } from './efficiency.js';
+import { validateWorkflowDefinition } from './engine/definition-validator.js';
+import { validationPieceRegistry } from './engine/pieces/index.js';
+import { configuredRoles } from './engine/preflight.js';
+import { createRun, definitionRunDirectory } from './engine/runs.js';
+import { observeLedger } from './engine/run-status.js';
+import { RunDatabase } from './engine/checkpoint/database.js';
+import { ledgerWorkflowState } from './engine/invocation-context.js';
 function oracle(test, file) {
     return spawnSync(process.execPath, ['-e', 'const assert = require("node:assert/strict"); const api = require(process.argv[1]);' + test.oracle, file], { encoding: 'utf8', timeout: 10000 }).status === 0;
 }
@@ -26,12 +33,13 @@ function prepare(test, root) {
     });
     return validatePipelineContext({ schemaVersion: 1, runId: randomUUID(), backlogRoot: root, artifactRoot: repositories[0].path, artifactRepositoryId: repositories[0].id, repositories, ownership: { git: 'host', backlog: 'host', worktrees: 'host' }, specs: [{ id: 1, title: test.id, description: test.description + ' Implement behavior in implementation.cjs in every selected repository.', repositoryIds: test.repositories, acceptanceCriteria: [test.description] }] });
 }
-function fixtureRegistry(test, context) {
+function fixtureRegistry(test, context, onPrompt) {
     let developers = 0, reviews = 0;
     const sessions = new Map();
     return new ExecutorRegistry().register('fixture', {
         capabilities: () => ({ transport: 'offline-fixture', continuation: 'supported', effortSupport: 'unsupported', supportedEfforts: [], observedModel: false, observedEffort: false }),
         async execute(request) {
+            onPrompt?.(request);
             const sessionId = 'fixture-' + request.role;
             if (request.resumeSessionId && !sessions.has(request.resumeSessionId))
                 throw new Error('Fixture session was not restored');
@@ -57,11 +65,11 @@ function fixtureRegistry(test, context) {
             }
             else {
                 await tools.execute({ action: 'instructions', artifact: 'apply' });
-                if (request.role === 'developer') {
+                if (request.role === 'developer' || request.role === 'fixer') {
                     developers++;
                     for (const repo of context.repositories)
                         writeFileSync(path.join(repo.path, 'implementation.cjs'), test.correction && developers === 1 ? test.defects[0] : test.solution);
-                    writeFileSync(path.join(context.artifactRoot, 'openspec/changes/evaluation-change/tasks.md'), '## 1. Implementation\n- [x] 1.1 Implement and test the requested behavior\n');
+                    await tools.execute({ action: 'write_artifact', path: 'tasks.md', content: '## 1. Implementation\n- [x] 1.1 Implement and test the requested behavior\n' });
                     output = { summary: 'Implemented fixture behavior', files: ['implementation.cjs'], tests: [], verification: 'Core executes the frozen checks', incomplete: [] };
                 }
                 else {
@@ -75,18 +83,23 @@ function fixtureRegistry(test, context) {
     });
 }
 export async function runEvaluation(options) {
+    if (options.capturePrompts && options.real)
+        throw new Error('Prompt capture is limited to offline fixture evaluation');
     const repetitions = options.repetitions ?? 1;
     if (!Number.isSafeInteger(repetitions) || repetitions < 1 || repetitions > 20)
         throw new Error('Evaluation repetitions must be 1–20');
     if (options.real && (!options.config || !Number.isFinite(options.maxCostUsd) || options.maxCostUsd <= 0 || Object.values(options.config.agents).some(role => !role.model)))
         throw new Error('Real evaluation requires explicit per-role models and a positive aggregate spend limit');
+    const corpus = options.caseIds ? EVALUATION_CORPUS.filter(item => options.caseIds.includes(item.id)) : EVALUATION_CORPUS;
+    if (!corpus.length || options.caseIds?.some(id => !corpus.some(item => item.id === id)))
+        throw new Error('Unknown or empty evaluation case selection');
     const identity = coreRuntimeIdentity();
     const observations = [];
-    let spend = 0, stopReason = null;
+    let spend = 0, stopReason = null, evaluatedDefinitionVersion = null;
     const root = mkdtempSync(path.join(tmpdir(), 'specrails-evaluation-'));
     try {
         for (let repeat = 0; repeat < repetitions && !stopReason; repeat++)
-            for (const test of EVALUATION_CORPUS) {
+            for (const test of corpus) {
                 // Check the independent oracle itself against defective candidates.
                 const probe = path.join(root, 'oracle-probe.cjs');
                 writeFileSync(probe, test.solution);
@@ -113,7 +126,33 @@ export async function runEvaluation(options) {
                     const started = Date.now();
                     let state;
                     try {
-                        state = await runCoreWorkflow({ context, change: 'evaluation-change', config, ...(options.real ? {} : { registry: fixtureRegistry(test, context) }) });
+                        let promptNumber = 0;
+                        const capture = options.capturePrompts ? (request) => {
+                            const directory = path.join(options.output, 'prompts', test.id + '-' + repeat + '-' + mode);
+                            mkdirSync(directory, { recursive: true, mode: 0o700 });
+                            const filename = String(++promptNumber).padStart(2, '0') + '-' + request.role + (request.stance ? '-' + request.stance : '');
+                            writeFileSync(path.join(directory, filename + '.txt'), request.prompt, { mode: 0o600 });
+                            writeFileSync(path.join(directory, filename + '.json'), JSON.stringify({ role: request.role, stance: request.stance ?? null,
+                                model: request.model ?? null, resumeSessionId: request.resumeSessionId ?? null, promptBytes: Buffer.byteLength(request.prompt),
+                                sections: request.prompt.split(/(?=^#{1,4} )/m).map(section => ({ heading: section.split('\n')[0].slice(0, 150), bytes: Buffer.byteLength(section) })) }, null, 2) + '\n', { mode: 0o600 });
+                        } : undefined;
+                        const registry = options.real ? undefined : fixtureRegistry(test, context, capture);
+                        if (options.definition === undefined)
+                            state = await runCoreWorkflow({ context, change: 'evaluation-change', config, ...(registry ? { registry } : {}) });
+                        else {
+                            const validation = validateWorkflowDefinition(options.definition, validationPieceRegistry(), configuredRoles(config), { published: true });
+                            if (!validation.ok)
+                                throw new Error('Evaluation definition failed validation: ' + JSON.stringify(validation.errors));
+                            evaluatedDefinitionVersion = validation.version;
+                            await createRun({ context, change: 'evaluation-change', config, definition: validation.definition, ...(registry ? { registry } : {}) });
+                            const database = await RunDatabase.open(path.join(definitionRunDirectory(context), 'run.sqlite'), { readOnly: true });
+                            try {
+                                state = ledgerWorkflowState(observeLedger(database), validation.definition, '*');
+                            }
+                            finally {
+                                database.close();
+                            }
+                        }
                     }
                     catch (error) {
                         observations.push({ caseId: test.id, repeat, mode, status: 'blocked', independentAccepted: false, error: error instanceof Error ? error.message : String(error), runtimeIdentity: identity, taskHash: fingerprint(test), oracleHash: fingerprint(test.oracle), repositories: context.repositories.map(({ id, baseSha }) => ({ id, baseSha })), configHash: fingerprint(config) });
@@ -145,7 +184,7 @@ export async function runEvaluation(options) {
             return [mode, { samples: rows.length, independentlyAccepted: accepted, costPerAcceptedUsd: options.real && knownCost !== null && accepted ? knownCost / accepted : null, medianActiveDurationMs: median(durations), minActiveDurationMs: durations.length ? Math.min(...durations) : null, maxActiveDurationMs: durations.length ? Math.max(...durations) : null, standardDeviationMs: average === null ? null : Math.sqrt(durations.reduce((sum, value) => sum + (value - average) ** 2, 0) / durations.length) }];
         }));
         const full = groups.full, optimized = groups.optimized;
-        const paired = observations.length === EVALUATION_CORPUS.length * repetitions * 2 && full.samples === optimized.samples;
+        const paired = observations.length === corpus.length * repetitions * 2 && full.samples === optimized.samples;
         const noObservedQualityDrop = paired && optimized.independentlyAccepted >= full.independentlyAccepted;
         const promptPairs = observations.filter(row => row.mode === 'full' && row.caseId === 'verification-correction').map(row => {
             const other = observations.find(item => item.mode === 'optimized' && item.caseId === row.caseId && item.repeat === row.repeat);
@@ -158,7 +197,10 @@ export async function runEvaluation(options) {
             return Array.isArray(row.invocations) && Array.isArray(other?.invocations) && other.invocations.length <= row.invocations.length;
         });
         const monetaryConclusion = options.real && paired && full.costPerAcceptedUsd !== null && optimized.costPerAcceptedUsd !== null && full.costPerAcceptedUsd > 0 ? optimized.costPerAcceptedUsd <= full.costPerAcceptedUsd * 0.8 && noObservedQualityDrop ? 'target-met-in-this-sample' : 'target-not-met-in-this-sample' : 'inconclusive';
-        const report = { schemaVersion: 1, experiment: Object.values(options.config?.agents ?? {}).some(role => role.escalation) ? 'routing' : 'same-model', noExtraInvocations, mode: options.real ? 'real' : 'offline', runtimeIdentity: identity, corpusHash: fingerprint(EVALUATION_CORPUS), measurement: options.real ? 'reported-provider-usage' : 'synthetic-fixture-usage; no actual AI savings measured', monetaryTarget: 0.2, monetaryConclusion, groups, noObservedQualityDrop, promptPairs, correctionPromptTargetMet: promptPairs.length > 0 && promptPairs.every(pair => pair.reduction !== null && pair.reduction >= 0.4), sampleLimitations: 'Small descriptive paired sample; does not establish a universal quality or savings guarantee.', stopReason, reportedSpendUsd: options.real ? spend : 0, observations };
+        const report = { schemaVersion: 1, isDefinitionEvaluation: options.definition !== undefined,
+            ...(options.definition === undefined ? {} : { definitionHash: evaluatedDefinitionVersion }),
+            acceptedCases: observations.filter(row => row.independentAccepted).length,
+            allCasesAccepted: paired && observations.every(row => row.independentAccepted), experiment: Object.values(options.config?.agents ?? {}).some(role => role.escalation) ? 'routing' : 'same-model', noExtraInvocations, mode: options.real ? 'real' : 'offline', runtimeIdentity: identity, corpusHash: fingerprint(corpus), measurement: options.real ? 'reported-provider-usage' : 'synthetic-fixture-usage; no actual AI savings measured', monetaryTarget: 0.2, monetaryConclusion, groups, noObservedQualityDrop, promptPairs, correctionPromptTargetMet: promptPairs.length > 0 && promptPairs.every(pair => pair.reduction !== null && pair.reduction >= 0.4), sampleLimitations: 'Small descriptive paired sample; does not establish a universal quality or savings guarantee.', stopReason, reportedSpendUsd: options.real ? spend : 0, observations };
         mkdirSync(options.output, { recursive: true });
         writeFileSync(path.join(options.output, 'evaluation.json'), JSON.stringify(report, null, 2) + '\n');
         writeFileSync(path.join(options.output, 'evaluation.md'), `# Implementation efficiency evaluation\n\nMode: ${report.mode}. ${report.measurement}.\n\nMonetary target: 20% lower aggregate cost per independently accepted output. Conclusion: ${monetaryConclusion}.\n\n${JSON.stringify(groups, null, 2)}\n\nCorrection prompt comparison: ${JSON.stringify(promptPairs)}\n\n${observations.map(row => `- ${row.caseId}, ${row.mode}: ${row.status}; independent acceptance ${row.independentAccepted}; ${row.activeDurationMs} ms`).join('\n')}\n\n${stopReason ?? (options.real ? report.sampleLimitations : 'No paid benchmark has established monetary savings.')}\n`);

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

@@ -3,7 +3,31 @@ import type { CacheTokenUsage } from './efficiency-types.js';
 import type { GuardrailSettings } from './guardrails.js';
 export declare const DEFAULT_AGENT_TIMEOUT_MS: number;
 export declare const DEFAULT_AGENT_IDLE_TIMEOUT_MS: number;
-export type AgentRole = 'architect' | 'developer' | 'reviewer';
+export declare const BUILTIN_ROLES: readonly ["architect", "developer", "reviewer"];
+export type BuiltinAgentRole = typeof BUILTIN_ROLES[number];
+export type AgentRole = string;
+export type AgentAccess = 'read' | 'write';
+export type ArtifactAccess = 'none' | 'tasks-checkboxes' | 'all';
+export type OpenSpecSkill = 'openspec-ff-change' | 'openspec-apply-change' | 'openspec-verify-change';
+export declare const ROLE_ID: RegExp;
+export declare function isBuiltinRole(role: string): role is BuiltinAgentRole;
+export declare const BUILTIN_ROLE_POLICY: {
+    readonly architect: {
+        readonly access: "read";
+        readonly artifacts: "all";
+        readonly openspecSkill: "openspec-ff-change";
+    };
+    readonly developer: {
+        readonly access: "write";
+        readonly artifacts: "tasks-checkboxes";
+        readonly openspecSkill: "openspec-apply-change";
+    };
+    readonly reviewer: {
+        readonly access: "read";
+        readonly artifacts: "none";
+        readonly openspecSkill: "openspec-verify-change";
+    };
+};
 /** Who an observer sees acting: a pipeline role, or the FIXER stance the developer step takes on a correction round. */
 export type AgentEventRole = AgentRole | 'fixer';
 export type CliProvider = 'claude' | 'codex' | 'gemini' | 'kimi';
@@ -37,6 +61,15 @@ export interface RuntimeAgentConfig {
         effort?: string;
     };
 }
+export interface RuntimeRoleConfig extends RuntimeAgentConfig {
+    access: AgentAccess;
+    artifacts: ArtifactAccess;
+    prompt?: string;
+    openspecSkill?: OpenSpecSkill;
+}
+export interface RoleDescriptor extends RuntimeRoleConfig {
+    id: AgentRole;
+}
 export interface EfficiencyPolicy {
     schemaVersion: 1;
     contextMode?: 'full' | 'incremental';
@@ -64,7 +97,8 @@ export interface RuntimeConfig {
     efficiency?: EfficiencyPolicy;
     enabled: boolean;
     providers: RuntimeProviderConfig[];
-    agents: Record<AgentRole, RuntimeAgentConfig>;
+    agents: Record<BuiltinAgentRole, RuntimeAgentConfig>;
+    roles?: Record<AgentRole, RuntimeRoleConfig>;
     /** Optional engine for correction rounds (after a failed verification or a rejected review); unset ⇒ the developer corrects. */
     fixer?: RuntimeAgentConfig;
     limits?: {
@@ -110,6 +144,14 @@ export interface AgentEvent {
 export interface AgentRequest {
     openspec?: import('./openspec.js').OpenSpecRoleContext;
     role: AgentRole;
+    /** Optional only for backward-compatible built-in requests. Custom roles require explicit policy. */
+    access?: AgentAccess;
+    artifacts?: ArtifactAccess;
+    instructions?: 'role' | 'none';
+    nativeCommand?: {
+        id: string;
+        args?: string;
+    };
     prompt: string;
     cwd: string;
     allowedRoots: string[];
@@ -118,8 +160,9 @@ export interface AgentRequest {
     /** Local engines: private thinking on/off for this invocation (see RuntimeAgentConfig.thinking). */
     thinking?: 'on' | 'off';
     maxTurns?: number;
+    /** Total invocation limit; zero disables this timer without disabling cancellation or run budgets. */
     timeoutMs?: number;
-    /** Maximum silence from the provider; independent of the total invocation limit. */
+    /** Maximum silence from the provider; zero disables the idle timer. */
     idleTimeoutMs?: number;
     maxTokens?: number;
     maxCostUsd?: number;
@@ -157,3 +200,10 @@ export declare class AgentExecutionError extends Error {
 }
 export declare function unknownUsage(): AgentUsage;
 export declare function validateAgentRequest(request: AgentRequest): void;
+/** Resolve compatible defaults without changing the caller's frozen request. */
+export declare function requestPolicy(request: Pick<AgentRequest, 'role' | 'access' | 'artifacts' | 'instructions'>): {
+    access: AgentAccess;
+    artifacts: ArtifactAccess;
+    instructions: 'role' | 'none';
+};
+export declare function normalizeAgentRequest(request: AgentRequest): AgentRequest & ReturnType<typeof requestPolicy>;

package/dist/agent-runtime/executor-types.js

@@ -1,5 +1,13 @@
 export const DEFAULT_AGENT_TIMEOUT_MS = 60 * 60_000;
 export const DEFAULT_AGENT_IDLE_TIMEOUT_MS = 15 * 60_000;
+export const BUILTIN_ROLES = ['architect', 'developer', 'reviewer'];
+export const ROLE_ID = /^[a-z][a-z0-9-]{0,63}$/;
+export function isBuiltinRole(role) { return BUILTIN_ROLES.includes(role); }
+export const BUILTIN_ROLE_POLICY = {
+    architect: { access: 'read', artifacts: 'all', openspecSkill: 'openspec-ff-change' },
+    developer: { access: 'write', artifacts: 'tasks-checkboxes', openspecSkill: 'openspec-apply-change' },
+    reviewer: { access: 'read', artifacts: 'none', openspecSkill: 'openspec-verify-change' },
+};
 export class AgentExecutionError extends Error {
     code;
     usage;
@@ -15,13 +23,21 @@ export class AgentExecutionError extends Error {
 }
 export function unknownUsage() { return { inputTokens: null, outputTokens: null, costUsd: null }; }
 export function validateAgentRequest(request) {
-    if (!['architect', 'developer', 'reviewer'].includes(request.role) || typeof request.prompt !== 'string' || !request.prompt.trim() || request.prompt.includes('\0'))
+    if (typeof request.role !== 'string' || !ROLE_ID.test(request.role) || typeof request.prompt !== 'string' || request.prompt.includes('\0') || (!request.nativeCommand && !request.prompt.trim()))
         throw new AgentExecutionError('Invalid role request', 'invalid_request');
+    const policy = requestPolicy(request);
+    if (request.nativeCommand !== undefined) {
+        const command = request.nativeCommand;
+        if (!command || typeof command !== 'object' || Array.isArray(command) || Object.keys(command).some(key => !['id', 'args'].includes(key)) || typeof command.id !== 'string' || !/^[a-z][a-z0-9:_-]{0,63}$/.test(command.id) || (command.args !== undefined && (typeof command.args !== 'string' || command.args.includes('\0'))) || request.prompt.trim() || policy.instructions !== 'none' || request.openspec)
+            throw new AgentExecutionError('Invalid native command request', 'invalid_request');
+    }
+    if (policy.instructions === 'none' && request.openspec)
+        throw new AgentExecutionError('Free prompts cannot bind role instructions', 'invalid_request');
     if (request.model !== undefined && (typeof request.model !== 'string' || !request.model.trim() || request.model.length > 256 || /^-/.test(request.model) || /[\0\r\n]/.test(request.model)))
         throw new AgentExecutionError('Invalid model identifier', 'invalid_model');
     for (const key of ['maxTurns', 'timeoutMs', 'idleTimeoutMs', 'maxTokens', 'maxCostUsd']) {
         const value = request[key];
-        if (value !== undefined && (!Number.isFinite(value) || value <= 0 || (key !== 'maxCostUsd' && !Number.isSafeInteger(value))))
+        if (value !== undefined && (!Number.isFinite(value) || (value < 0 || (value === 0 && key !== 'timeoutMs' && key !== 'idleTimeoutMs')) || (key !== 'maxCostUsd' && !Number.isSafeInteger(value))))
             throw new AgentExecutionError(`Invalid ${key}`, 'invalid_limit');
     }
     if (request.resumeSessionId !== undefined && (typeof request.resumeSessionId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(request.resumeSessionId)))
@@ -31,3 +47,20 @@ export function validateAgentRequest(request) {
     if (request.signal?.aborted)
         throw new AgentExecutionError('Agent cancelled', 'aborted');
 }
+/** Resolve compatible defaults without changing the caller's frozen request. */
+export function requestPolicy(request) {
+    const legacy = isBuiltinRole(request.role) ? BUILTIN_ROLE_POLICY[request.role] : undefined;
+    const access = request.access ?? legacy?.access;
+    const artifacts = request.artifacts ?? legacy?.artifacts;
+    const instructions = request.instructions ?? (legacy ? 'role' : undefined);
+    if ((access !== 'read' && access !== 'write') || (artifacts !== 'none' && artifacts !== 'tasks-checkboxes' && artifacts !== 'all') || (instructions !== 'role' && instructions !== 'none'))
+        throw new AgentExecutionError('Explicit access, artifacts and instructions are required', 'invalid_request');
+    return { access, artifacts, instructions };
+}
+export function normalizeAgentRequest(request) {
+    validateAgentRequest(request);
+    const policy = requestPolicy(request);
+    const legacy = isBuiltinRole(request.role) ? BUILTIN_ROLE_POLICY[request.role] : undefined;
+    const unchangedBinding = request.openspec && request.openspec.role === request.role && request.openspec.access === undefined && request.openspec.artifacts === undefined && policy.access === legacy?.access && policy.artifacts === legacy?.artifacts;
+    return { ...request, ...policy, ...(request.openspec && !unchangedBinding ? { openspec: { ...request.openspec, access: policy.access, artifacts: policy.artifacts } } : {}) };
+}

package/dist/agent-runtime/executors.js

@@ -1,4 +1,4 @@
-import { AgentExecutionError, validateAgentRequest } from './executor-types.js';
+import { AgentExecutionError, normalizeAgentRequest } from './executor-types.js';
 import { validateRuntimeConfig } from './config.js';
 import { CliExecutor } from './cli-executor.js';
 import { OpenAICompatibleExecutor } from './openai-executor.js';
@@ -24,7 +24,7 @@ export class ExecutorRegistry {
     async capabilities(id, model) { return await this.get(id).capabilities?.(model) ?? unknownCapabilities('registered:' + id); }
     validateLimits(id, limits) { this.get(id).validateLimits?.(limits); }
     async execute(id, request) {
-        validateAgentRequest(request);
+        request = normalizeAgentRequest(request);
         if (request.effort !== undefined)
             assertEffortSupported(request, await this.capabilities(id, request.model));
         const result = await this.get(id).execute(request);

package/dist/agent-runtime/graph/artifacts.d.ts

@@ -1,6 +1,8 @@
 import { type PipelineContext, type PipelineState, type VerificationCommand } from '../../pipeline/pipeline-state.js';
 import type { DesignConfidence } from './state.js';
 export declare const SLUG: RegExp;
+/** Historical target lookup, not an archive or verification receipt. */
+export declare function archivedOpenSpecChange(context: PipelineContext, change: string): string | undefined;
 export declare function object(value: unknown): Record<string, unknown>;
 /** Accepts the object wherever the model put it: bare, fenced, or surrounded by commentary. */
 export declare function parseAgentObject(text: string): Record<string, unknown>;
@@ -23,4 +25,9 @@ export declare function writeDesignConfidence(context: PipelineContext, change:
 }): void;
 /** Commands the architect proposed for repositories the configuration leaves uncovered. */
 export declare function proposedVerification(context: PipelineContext, configured: VerificationCommand[], verification: unknown): VerificationCommand[];
+/** Recoverable pinned-CLI archive for ledger-only runs; no implementation journal. */
+export declare function archiveOpenSpecChange(context: PipelineContext, change: string, adapter: {
+    directory: string;
+    beforePublish(): void;
+}, signal?: AbortSignal): Promise<void>;
 export declare function archive(context: PipelineContext, change: string, signal?: AbortSignal): Promise<void>;

package/dist/agent-runtime/graph/artifacts.js

@@ -5,6 +5,23 @@ import path from 'node:path';
 import { checkArchive, pipelineStateDirectory, transitionPipeline, validateVerificationRequest, } from '../../pipeline/pipeline-state.js';
 import { assertProposalInScope, withScopeDefault } from '../change-scope.js';
 export const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Historical target lookup, not an archive or verification receipt. */
+export function archivedOpenSpecChange(context, change) {
+    if (!SLUG.test(change) || change.length > 64)
+        throw new Error('Invalid OpenSpec change identifier');
+    if (existsSync(artifactPath(context.artifactRoot, 'openspec/changes/' + change)))
+        return undefined;
+    const relative = 'openspec/changes/archive', directory = artifactPath(context.artifactRoot, relative);
+    if (!existsSync(directory))
+        return undefined;
+    const candidate = readdirSync(directory, { withFileTypes: true }).filter(entry => entry.isDirectory() &&
+        (entry.name === change || /^\d{4}-\d{2}-\d{2}-/.test(entry.name) && entry.name.slice(11) === change))
+        .sort((left, right) => left.name.localeCompare(right.name, 'en'))[0];
+    if (!candidate)
+        return undefined;
+    artifactPath(context.artifactRoot, relative + '/' + candidate.name);
+    return relative + '/' + candidate.name;
+}
 export function object(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new Error('Expected a structured JSON object from agent');
@@ -114,8 +131,8 @@ export function proposedVerification(context, configured, verification) {
 }
 /** Publish an archive prepared by the real CLI. The durable write set makes a
  * crash between main-spec updates recoverable without applying a delta twice. */
-async function archiveWithOpenSpec(context, change, active, signal) {
-    const directory = pipelineStateDirectory(context);
+async function archiveWithOpenSpec(context, change, active, signal, adapter) {
+    const directory = adapter?.directory ?? pipelineStateDirectory(context);
     const receipt = path.join(directory, 'openspec-archive.json');
     const files = (root, prefix = '') => {
         if (!existsSync(root))
@@ -127,7 +144,8 @@ async function archiveWithOpenSpec(context, change, active, signal) {
             return entry.isDirectory() ? files(path.join(root, entry.name), relative + '/') : [relative];
         });
     };
-    const activeHash = hash(JSON.stringify(files(active).sort().map(file => [file, readFileSync(artifactPath(active, file), 'utf8')])));
+    const treeHash = (root) => hash(JSON.stringify(files(root).sort().map(file => [file, readFileSync(artifactPath(root, file), 'utf8')])));
+    const activeHash = treeHash(active);
     let plan;
     if (existsSync(receipt))
         plan = JSON.parse(readFileSync(receipt, 'utf8'));
@@ -137,6 +155,22 @@ async function archiveWithOpenSpec(context, change, active, signal) {
             const source = artifactPath(context.artifactRoot, 'openspec');
             files(source); // Reject symlinks before copying or invoking the external CLI.
             cpSync(source, path.join(staging, 'openspec'), { recursive: true });
+            // A fork prepares its delta against checkpoint-owned main specs. Publish
+            // still compares all current preimages below; no source files are rewound.
+            const forkBase = path.join(directory, 'openspec-archive-base.json');
+            let beforeRoot = path.join(source, 'specs');
+            let sourceChange;
+            if (existsSync(forkBase)) {
+                const baseline = object(JSON.parse(readFileSync(forkBase, 'utf8')));
+                if (baseline.schemaVersion !== 1 || baseline.directory !== 'agent-workflow/openspec-base-specs' || typeof baseline.snapshot !== 'string' || !/^[a-f0-9]{64}$/.test(baseline.snapshot)
+                    || typeof baseline.sourceChange !== 'string' || baseline.sourceChange.length > 64 || !SLUG.test(baseline.sourceChange))
+                    throw new Error('Invalid fork archive baseline');
+                sourceChange = baseline.sourceChange;
+                beforeRoot = child(directory, baseline.directory);
+                files(beforeRoot);
+                rmSync(path.join(staging, 'openspec/specs'), { recursive: true, force: true });
+                cpSync(beforeRoot, path.join(staging, 'openspec/specs'), { recursive: true });
+            }
             const output = await runOpenSpec(resolveOpenSpecCli(), staging, ['archive', change, '--yes'], signal);
             const archiveRoot = path.join(staging, 'openspec/changes/archive');
             const archives = existsSync(archiveRoot) ? readdirSync(archiveRoot).filter(name => name.endsWith('-' + change)) : [];
@@ -151,20 +185,40 @@ async function archiveWithOpenSpec(context, change, active, signal) {
             const destination = 'openspec/changes/archive/' + archives[0];
             if (existsSync(artifactPath(context.artifactRoot, destination)))
                 throw new Error('OpenSpec archive destination already exists');
-            const beforeRoot = path.join(source, 'specs'), afterRoot = path.join(staging, 'openspec/specs');
+            const afterRoot = path.join(staging, 'openspec/specs');
             const names = new Set([...files(beforeRoot), ...files(afterRoot)]);
             const contents = (root, name) => existsSync(path.join(root, name)) ? readFileSync(path.join(root, name), 'utf8') : null;
-            plan = { activeHash, destination, writes: [...names].map(name => ({ path: 'openspec/specs/' + name, before: contents(beforeRoot, name), after: contents(afterRoot, name) })).filter(item => item.before !== item.after) };
+            plan = { activeHash, destination, writes: [...names].map(name => {
+                    const before = contents(beforeRoot, name);
+                    let after = contents(afterRoot, name);
+                    // Pinned OpenSpec inserts a change ID into the placeholder for a newly
+                    // created specification. Preserve that provenance during fork replay;
+                    // authored text and all byte-for-byte publication guards stay intact.
+                    if (sourceChange && before === null && after !== null)
+                        after = after.replace(`\n## Purpose\nTBD - created by archiving change ${change}. Update Purpose after archive.\n## Requirements\n`, `\n## Purpose\nTBD - created by archiving change ${sourceChange}. Update Purpose after archive.\n## Requirements\n`);
+                    return { path: 'openspec/specs/' + name, before, after };
+                }).filter(item => item.before !== item.after) };
             write(receipt, JSON.stringify(plan));
         }
         finally {
             rmSync(staging, { recursive: true, force: true });
         }
     }
-    if (plan.activeHash !== activeHash)
-        throw new Error('Reviewed artifacts changed since the OpenSpec archive was prepared');
     if (!new RegExp('^openspec/changes/archive/[0-9]{4}-[0-9]{2}-[0-9]{2}-' + change + '$').test(plan.destination))
         throw new Error('Invalid OpenSpec archive receipt');
+    if (adapter && !existsSync(active)) {
+        const archived = artifactPath(context.artifactRoot, plan.destination);
+        if (!existsSync(archived) || treeHash(archived) !== plan.activeHash || plan.writes.some(item => {
+            if (!item.path.startsWith('openspec/specs/'))
+                throw new Error('Invalid OpenSpec archive write');
+            const target = artifactPath(context.artifactRoot, item.path);
+            return (existsSync(target) ? readFileSync(target, 'utf8') : null) !== item.after;
+        }))
+            throw new Error('OpenSpec archive recovery does not match the prepared write set');
+        return;
+    }
+    if (plan.activeHash !== activeHash)
+        throw new Error('Reviewed artifacts changed since the OpenSpec archive was prepared');
     const targets = plan.writes.map(item => {
         if (!item.path.startsWith('openspec/specs/'))
             throw new Error('Invalid OpenSpec archive write');
@@ -172,16 +226,23 @@ async function archiveWithOpenSpec(context, change, active, signal) {
         const current = existsSync(target) ? readFileSync(target, 'utf8') : null;
         if (current !== item.before && current !== item.after)
             throw new Error('Main specification changed during archive; refusing to overwrite: ' + item.path);
-        return { ...item, target };
+        return { ...item, target, unchanged: current === item.after };
     });
     // The external CLI ran asynchronously; recheck the candidate and artifacts before publishing.
     signal?.throwIfAborted();
-    checkArchive(context);
+    if (treeHash(active) !== activeHash)
+        throw new Error('Reviewed artifacts changed during OpenSpec archive preparation');
+    if (adapter)
+        adapter.beforePublish();
+    else
+        checkArchive(context);
     // Validate every path and preimage before publishing the first output.
     const destination = artifactPath(context.artifactRoot, plan.destination);
     if (existsSync(destination))
         throw new Error('Archive destination already exists');
     for (const item of targets) {
+        if (item.unchanged)
+            continue;
         if (item.after === null)
             rmSync(item.target, { force: true });
         else
@@ -190,6 +251,18 @@ async function archiveWithOpenSpec(context, change, active, signal) {
     mkdirSync(path.dirname(destination), { recursive: true });
     renameSync(active, destination);
 }
+/** Recoverable pinned-CLI archive for ledger-only runs; no implementation journal. */
+export async function archiveOpenSpecChange(context, change, adapter, signal) {
+    if (!SLUG.test(change) || change.length > 64)
+        throw new Error('Invalid OpenSpec change identifier');
+    mkdirSync(adapter.directory, { recursive: true, mode: 0o700 });
+    if (lstatSync(adapter.directory).isSymbolicLink())
+        throw new Error('Refusing symlink archive adapter directory');
+    const active = artifactPath(context.artifactRoot, 'openspec/changes/' + change);
+    if (!existsSync(active) && !existsSync(path.join(adapter.directory, 'openspec-archive.json')))
+        throw new Error('OpenSpec active change does not exist');
+    await archiveWithOpenSpec(context, change, active, signal, adapter);
+}
 export async function archive(context, change, signal) {
     const state = journal(context);
     if (state.phases.archive.status !== 'done') {

package/dist/agent-runtime/graph/nodes.d.ts

@@ -9,6 +9,8 @@ import type { CoreNodeId, CoreStateType, DeveloperRecord, VerificationRecord } f
 /** Autonomous investigation passes before a low-confidence design asks or proceeds. */
 export declare const MAX_DEEPEN_PASSES = 1;
 export interface CoreNodeDeps {
+    /** V2 presentation omits framework dispatch frames; original evidence stays complete. */
+    focusedCorrectionEvidence?: boolean;
     archiveApproved?: () => boolean;
     context: PipelineContext;
     config: RuntimeConfig;

package/dist/agent-runtime/graph/nodes.js

@@ -214,7 +214,7 @@ async function implementationVisit(deps, state, step, mode) {
         kind: visits > 1 ? 'correction' : 'initial',
         ...(fixer ? { agentOverride: fixer } : {}), ...(fixing ? { stance: 'fixer' } : {}),
         ...(resumable
-            ? { prompt: correctionInstructions('developer', feedback, { ...(changes ? { changeSet: changes } : {}), developer: state.development }), resumeSessionId: previous.sessionId, fallbackPrompt: full }
+            ? { prompt: correctionInstructions('developer', feedback, { ...(changes ? { changeSet: changes } : {}), developer: state.development, focusedEvidence: deps.focusedCorrectionEvidence && config.efficiency?.contextMode !== 'full' }), resumeSessionId: previous.sessionId, fallbackPrompt: full }
             : { prompt: full }),
         structured: true, lenient: true, outputSchema: DEVELOPER_OUTPUT_SCHEMA,
     }, (output, text, result) => {
@@ -513,7 +513,7 @@ function reviewerNode(deps) {
             const changes = measuredChange(context, change);
             const prompt = roleInstructions('reviewer', context, change, { definition: config.rolePrompts?.reviewer, feedback: feedbackFor(state), verification: state.plan, policy, criteria, developer: state.development, ...(changes ? { changeSet: changes } : {}), ...(reReview ? { reReview } : {}) });
             const incremental = config.efficiency?.reviewMode !== 'full' && delta.mode === 'incremental' && state.review?.sessionId;
-            const followup = correctionInstructions('reviewer', feedbackFor(state)) + '\nChanges since YOUR previous reviewed candidate:\n' + JSON.stringify(delta.changes)
+            const followup = correctionInstructions('reviewer', feedbackFor(state), { focusedEvidence: deps.focusedCorrectionEvidence && config.efficiency?.contextMode !== 'full' }) + '\nChanges since YOUR previous reviewed candidate:\n' + JSON.stringify(delta.changes)
                 + (changes ? '\nThe complete change under review (from git, against the run\'s base) — review these files only:\n' + changes.join('\n') : '')
                 + '\nRecertify EVERY current acceptance criterion; previous met results are not current evidence:\n' + JSON.stringify(criteria)
                 + '\nCurrent developer handoff:\n' + JSON.stringify(state.development);

package/dist/agent-runtime/graph/roles.d.ts

@@ -1,3 +1,4 @@
+import { type RoleStatePort } from '../role-state.js';
 import { type InvocationKind } from '../role-routing.js';
 import { type PipelineContext } from '../../pipeline/pipeline-state.js';
 import type { ExecutorRegistry } from '../executors.js';
@@ -17,6 +18,9 @@ export interface InvokeOptions {
     /** Run this invocation on another configured engine (the fixer) with the matching stance; sessions never carry across engines. */
     agentOverride?: RuntimeAgentConfig;
     stance?: 'fixer';
+    /** Per-piece invocation bounds; explicit zero disables only that timer. */
+    timeoutMs?: number;
+    idleTimeoutMs?: number;
 }
 export type InvokeOutcome<T> = {
     ok: true;
@@ -36,6 +40,10 @@ export interface RoleInvokerDeps {
     config: RuntimeConfig;
     registry: ExecutorRegistry;
     openspec?: Record<AgentRole, import('../openspec.js').OpenSpecRoleContext>;
+    /** Engine hosts isolate sessions/routes by scope and node instead of a role-global file. */
+    roleState?: RoleStatePort;
+    /** Durable independent operations must recover uncertain effects explicitly. */
+    propagateInterruptions?: boolean;
     /** `fixer` labels the developer step's events during a correction round on the fixer stance, so a log reader sees who is acting. */
     onAgentEvent?: (role: AgentEventRole, event: AgentEvent) => void;
 }