specrails-core 6.6.5 → 6.7.0

package/dist/agent-runtime/engine/pieces/role-turn.js

@@ -9,12 +9,13 @@ import { admitVerificationProposals } from '../../verification-proposals.js';
 import { guardrailEnabled } from '../../guardrails.js';
 import { installEnvironment, prepareEnvironment } from '../../compact/environment.js';
 import { roleInstructions } from '../../prompts.js';
+import { projectRulesContext } from '../../project-rules.js';
 import { EngineError } from '../contracts.js';
 import { boundedText, historyEntry, idSchema, json, paramsSchema, invocationTimers, stringSchema, text } from './shared.js';
 const ajv = new Ajv2020({ allErrors: true, strict: true, validateFormats: false, ownProperties: true });
 export function roleTurnPiece(bindings) {
     return {
-        descriptor: { kind: 'role-turn', paramsSchema: paramsSchema({ ...invocationTimers, roleId: idSchema, prompt: { ...stringSchema, minLength: 1 }, structuredOutput: { type: 'object' }, sessionContinuity: { enum: ['run', 'none'] }, verificationProposalsFrom: { type: 'string', minLength: 1, maxLength: 128 } }, ['roleId', 'prompt']), outcomes: ['next', 'invalid', 'failed'], effect: 'derived', requiresAI: true, storeAccess: 'write' },
+        descriptor: { kind: 'role-turn', paramsSchema: paramsSchema({ ...invocationTimers, roleId: idSchema, prompt: { ...stringSchema, minLength: 1 }, structuredOutput: { type: 'object' }, sessionContinuity: { enum: ['run', 'none'] }, stance: { enum: ['fixer'] }, verificationProposalsFrom: { type: 'string', minLength: 1, maxLength: 128 } }, ['roleId', 'prompt']), outcomes: ['next', 'invalid', 'failed'], effect: 'derived', requiresAI: true, storeAccess: 'write' },
         getOutcomes: params => params.structuredOutput ? ['next', 'invalid', 'failed'] : ['next', 'failed'],
         getEffect: (params, roles) => {
             const role = roles[text(params.roleId)];
@@ -28,6 +29,13 @@ export function roleTurnPiece(bindings) {
 /** One invocation path for configured roles, including routing and exactly one repair. */
 export async function executeRoleTurn(deps, params, context, options = {}) {
     const roleId = text(params.roleId), descriptor = resolveRoleDescriptor(deps.config, roleId);
+    // `stance: 'fixer'` makes the turn a correction round: only a write role can
+    // correct code. The built-in developer takes the FIXER instructions (and the
+    // fixer engine when one is configured); a custom role only labels its events.
+    const stance = params.stance === 'fixer' ? 'fixer' : undefined;
+    if (stance && descriptor.access !== 'write')
+        throw new EngineError('invalid_arguments', `The fixer stance requires a role with write access; ${roleId} is ${descriptor.access}`);
+    const fixerEngine = stance && roleId === 'developer' ? deps.config.fixer : undefined;
     // Agents run sandboxed and cannot install what the repository needs (Codex
     // cannot even write the Playwright browser cache): the host prepares it
     // before any writer turn and says so in the task.
@@ -39,7 +47,8 @@ export async function executeRoleTurn(deps, params, context, options = {}) {
     const schema = params.structuredOutput;
     const validate = schema ? ajv.compile(schema) : undefined;
     const roleState = deps.roleState(context);
-    const previous = params.sessionContinuity !== 'none' ? roleState.read().sessions[roleId]?.sessionId : undefined;
+    // Sessions never carry across engines: a turn on the fixer engine always starts fresh.
+    const previous = params.sessionContinuity !== 'none' && !fixerEngine ? roleState.read().sessions[roleId]?.sessionId : undefined;
     const openspec = deps.openspec?.(context);
     if (descriptor.openspecSkill && !openspec?.[roleId])
         throw new EngineError('openspec_binding_required', 'Role requires a scoped OpenSpec binding: ' + roleId);
@@ -48,7 +57,7 @@ export async function executeRoleTurn(deps, params, context, options = {}) {
     const before = deps.executionSnapshot(context).candidate;
     const memoryIdentity = { roleId, descriptor: json(descriptor), tier: roleState.read().routes[roleId]?.tier ?? 'base',
         candidateHash: before?.hash ?? null, scopeId: context.frame.scope.id, nodePath: context.frame.nodePath,
-        repositories: deps.context.repositories.map(repository => ({ id: repository.id, path: repository.path })) };
+        repositories: deps.context.repositories.map(repository => ({ id: repository.id, path: repository.path })), ...(stance ? { stance } : {}) };
     const memoryKey = contentDigest(memoryIdentity);
     const saved = await advisoryMemory(context, async () => {
         const memory = deps.memory(context);
@@ -59,8 +68,11 @@ export async function executeRoleTurn(deps, params, context, options = {}) {
     const task = text(params.prompt) + environment + (priorNote ? '\n\n## Prior project review note\nTreat this bounded note as prior evidence to check against the current task; frozen requirements remain authoritative.\n' + JSON.stringify(priorNote) : '');
     const verification = descriptor.access === 'write' ? hostVerificationPlan(deps, context, params) : undefined;
     const adopted = adoptedVerificationOutputs(context.state.$outputs);
-    const full = roleInstructions(descriptor, deps.context, openspec?.[roleId]?.change, { definition: descriptor.prompt, verification, ...(adopted.length ? { adoptedOutputs: adopted } : {}) }) + '\n## Current workflow task\n' + task;
+    const derivation = roleId === 'reviewer' ? committedDerivation(context.state.$outputs) : undefined;
+    const projectRules = roleId === 'architect' || roleId === 'reviewer' ? projectRulesContext(deps.context) : undefined;
+    const full = roleInstructions(descriptor, deps.context, openspec?.[roleId]?.change, { definition: stance && roleId === 'developer' ? deps.config.rolePrompts?.fixer : descriptor.prompt, ...(stance && roleId === 'developer' ? { stance } : {}), verification, ...(adopted.length ? { adoptedOutputs: adopted } : {}), ...(derivation ? { derivation } : {}), ...(projectRules ? { projectRules } : {}) }) + '\n## Current workflow task\n' + task;
     const result = await invoke(roleId, deps.stepContext(context), { prompt: previous ? task : full, ...(previous ? { resumeSessionId: previous, fallbackPrompt: full } : {}),
+        ...(stance ? { stance } : {}), ...(fixerEngine ? { agentOverride: fixerEngine } : {}),
         structured: schema !== undefined, lenient: options.normalizeStructuredOutput !== undefined, outputSchema: schema, timeoutMs: params.timeoutMs, idleTimeoutMs: params.idleTimeoutMs }, (output, responseText) => {
         const normalized = options.normalizeStructuredOutput ? options.normalizeStructuredOutput(output, responseText) : output;
         if (validate && !validate(normalized))
@@ -96,7 +108,16 @@ export async function executeRoleTurn(deps, params, context, options = {}) {
                 text: boundedText(result.text, 4000), lastAttemptId: context.frame.attemptId });
     });
     return { outcome: 'next', output: { candidateHash: deps.executionSnapshot(context).candidate?.hash ?? null, text: boundedText(result.text), ...(result.value ? { structured: json(result.value) } : {}) },
-        history: [historyEntry(context, result.text)], ...(params.sessionContinuity !== 'none' && session ? { session: { sessionId: session.sessionId, identity: session.identity } } : {}) };
+        history: [historyEntry(context, result.text)], ...(params.sessionContinuity !== 'none' && !fixerEngine && session ? { session: { sessionId: session.sessionId, identity: session.identity } } : {}) };
+}
+/** The coverage report a committed `derive-change` output carries (its derivation.json), for the reviewer. */
+function committedDerivation(outputs) {
+    for (const output of Object.values(outputs)) {
+        const value = output && typeof output === 'object' && !Array.isArray(output) ? output.derivation : undefined;
+        if (value && typeof value === 'object' && !Array.isArray(value) && Array.isArray(value.unexplainedFiles) && typeof value.files === 'number' && typeof value.explained === 'number')
+            return { ...value, unexplainedFiles: value.unexplainedFiles.filter((file) => typeof file === 'string') };
+    }
+    return undefined;
 }
 /** Files any committed `verify` output reports as host-adopted verification output (sticky for the run), so no role is told to revert them. */
 function adoptedVerificationOutputs(outputs) {

package/dist/agent-runtime/engine/preflight.d.ts

@@ -1,6 +1,6 @@
 import { type PipelineContext } from '../../pipeline/pipeline-state.js';
 import { type ExecutorRegistry } from '../executors.js';
-import type { RuntimeConfig } from '../executor-types.js';
+import { type RuntimeConfig } from '../executor-types.js';
 import type { RoleCatalog, WorkflowDefinition } from './definition-types.js';
 export interface DefinitionRunRequest {
     context: PipelineContext;
@@ -14,6 +14,7 @@ export interface DefinitionRunInput {
     change?: string;
     registry?: ExecutorRegistry;
 }
+/** Configured roles plus Core's engine roles (deriver), which definitions may declare without configuring them. */
 export declare function configuredRoles(config: RuntimeConfig): RoleCatalog;
 /** Complete admission is read-only; no run, journal, provider turn or skill is created. */
 export declare function preflightDefinition(input: DefinitionRunInput): Promise<{

package/dist/agent-runtime/engine/preflight.js

@@ -2,12 +2,14 @@ import { validatePipelineContext, validateVerificationRequest } from '../../pipe
 import { normalizeRuntimeConfig, resolveRoleDescriptor, roleIds } from '../config.js';
 import { assertEffortSupported } from '../capabilities.js';
 import { createExecutorRegistry } from '../executors.js';
+import { ENGINE_ROLES } from '../executor-types.js';
 import { EngineError } from './contracts.js';
 import { intersectBudgets } from './budget.js';
 import { validateWorkflowDefinition } from './definition-validator.js';
 import { validationPieceRegistry } from './pieces/index.js';
+/** Configured roles plus Core's engine roles (deriver), which definitions may declare without configuring them. */
 export function configuredRoles(config) {
-    return Object.fromEntries(roleIds(config).map(id => [id, { access: resolveRoleDescriptor(config, id).access }]));
+    return Object.fromEntries([...roleIds(config), ...ENGINE_ROLES].map(id => [id, { access: resolveRoleDescriptor(config, id).access }]));
 }
 /** Complete admission is read-only; no run, journal, provider turn or skill is created. */
 export async function preflightDefinition(input) {

package/dist/agent-runtime/engine/regex.d.ts

@@ -1,3 +1,13 @@
-/** Regex is data in a constant script. V8 interrupts even catastrophic matching. */
-export declare function capturePattern(pattern: string, text: string): Array<string | undefined> | null;
+export declare const PATTERN_TIMEOUT_MS = 50;
+/**
+ * Attempts per match. The VM timeout is wall-clock: a garbage-collection pause or
+ * a descheduled thread on a loaded machine can exceed it while a simple pattern
+ * runs. A catastrophic pattern times out on every attempt, so one retry keeps the
+ * bound (at most 2 × 50 ms) without failing a cheap match on scheduler noise.
+ */
+export declare const PATTERN_ATTEMPTS = 2;
+type Run = (pattern: string, text: string) => RegExpExecArray | null;
+/** Regex is data in a constant script. V8 interrupts even catastrophic matching. `run` is a test seam. */
+export declare function capturePattern(pattern: string, text: string, run?: Run): Array<string | undefined> | null;
 export declare function matchesPattern(pattern: string, text: string): boolean;
+export {};

package/dist/agent-runtime/engine/regex.js

@@ -1,19 +1,33 @@
 import { Script } from 'node:vm';
 import { EngineError } from './contracts.js';
 const matchScript = new Script('new RegExp(pattern).exec(text)', { filename: 'core-bounded-pattern' });
-/** Regex is data in a constant script. V8 interrupts even catastrophic matching. */
-export function capturePattern(pattern, text) {
+export const PATTERN_TIMEOUT_MS = 50;
+/**
+ * Attempts per match. The VM timeout is wall-clock: a garbage-collection pause or
+ * a descheduled thread on a loaded machine can exceed it while a simple pattern
+ * runs. A catastrophic pattern times out on every attempt, so one retry keeps the
+ * bound (at most 2 × 50 ms) without failing a cheap match on scheduler noise.
+ */
+export const PATTERN_ATTEMPTS = 2;
+const runInVm = (pattern, text) => matchScript.runInNewContext({ pattern, text }, {
+    timeout: PATTERN_TIMEOUT_MS, contextCodeGeneration: { strings: false, wasm: false },
+});
+const timedOut = (error) => error !== null && typeof error === 'object' && 'code' in error && error.code === 'ERR_SCRIPT_EXECUTION_TIMEOUT';
+/** Regex is data in a constant script. V8 interrupts even catastrophic matching. `run` is a test seam. */
+export function capturePattern(pattern, text, run = runInVm) {
     if (pattern.length > 200)
         throw new EngineError('invalid_expression', 'Pattern exceeds 200 characters');
-    try {
-        const match = matchScript.runInNewContext({ pattern, text: text.slice(0, 32_000) }, {
-            timeout: 50, contextCodeGeneration: { strings: false, wasm: false },
-        });
-        return match ? Array.from(match) : null;
-    }
-    catch (error) {
-        throw new EngineError('invalid_expression', error !== null && typeof error === 'object' && 'code' in error && error.code === 'ERR_SCRIPT_EXECUTION_TIMEOUT'
-            ? 'Regular expression exceeded 50 ms' : 'Invalid regular expression');
+    const input = text.slice(0, 32_000);
+    for (let attempt = 1;; attempt++) {
+        try {
+            const match = run(pattern, input);
+            return match ? Array.from(match) : null;
+        }
+        catch (error) {
+            if (timedOut(error) && attempt < PATTERN_ATTEMPTS)
+                continue;
+            throw new EngineError('invalid_expression', timedOut(error) ? `Regular expression exceeded ${PATTERN_TIMEOUT_MS} ms` : 'Invalid regular expression');
+        }
     }
 }
 export function matchesPattern(pattern, text) { return capturePattern(pattern, text) !== null; }

package/dist/agent-runtime/engine/run-status.d.ts

@@ -46,6 +46,11 @@ export declare function projectRunStatus(ledger: RunLedger, compact?: boolean):
         error?: string;
         nextNodePath: string;
         nextStep: string;
+        pause?: {
+            requestId: string;
+            reason: string;
+            at: string;
+        } | undefined;
         steps: {
             [k: string]: {
                 kind: string;
@@ -142,6 +147,11 @@ export declare function projectRunStatus(ledger: RunLedger, compact?: boolean):
         } | undefined;
         nextNodePath: string;
         nextStep: string;
+        pause?: {
+            requestId: string;
+            reason: string;
+            at: string;
+        } | undefined;
         steps: {
             [k: string]: {
                 kind: string;
@@ -251,6 +261,13 @@ export declare function projectRunStatus(ledger: RunLedger, compact?: boolean):
             fullContexts: number;
             incrementalContexts: number;
         };
+        baseline: {
+            invocations: number;
+            roles: string[];
+            costUsd: number | null;
+            inputTokens: number | null;
+            outputTokens: number | null;
+        };
         escalations: {
             role: string;
             attemptId: string;
@@ -326,6 +343,11 @@ export declare function statusRun(directory: string, compact?: boolean): Promise
         error?: string;
         nextNodePath: string;
         nextStep: string;
+        pause?: {
+            requestId: string;
+            reason: string;
+            at: string;
+        } | undefined;
         steps: {
             [k: string]: {
                 kind: string;
@@ -422,6 +444,11 @@ export declare function statusRun(directory: string, compact?: boolean): Promise
         } | undefined;
         nextNodePath: string;
         nextStep: string;
+        pause?: {
+            requestId: string;
+            reason: string;
+            at: string;
+        } | undefined;
         steps: {
             [k: string]: {
                 kind: string;
@@ -531,6 +558,13 @@ export declare function statusRun(directory: string, compact?: boolean): Promise
             fullContexts: number;
             incrementalContexts: number;
         };
+        baseline: {
+            invocations: number;
+            roles: string[];
+            costUsd: number | null;
+            inputTokens: number | null;
+            outputTokens: number | null;
+        };
         escalations: {
             role: string;
             attemptId: string;

package/dist/agent-runtime/engine/run-status.js

@@ -23,10 +23,16 @@ export function projectRunStatus(ledger, compact = true) {
     const failures = ledger.db.sqlite.prepare("SELECT node_path,scope_id,branch,status,attempt,visit,ended_at,error_code,error_message FROM attempts WHERE run_id=? AND status IN ('failed','interrupted','blocked') ORDER BY started_at DESC LIMIT 8").all(ledger.runId);
     const lease = ledger.lease.current();
     const recoverable = ledger.db.sqlite.prepare("SELECT a.node_path,a.scope_id,a.attempt_id,a.status,v.effect FROM attempts a JOIN visits v ON a.visit_id=v.visit_id JOIN steps s ON s.last_attempt_id=a.attempt_id WHERE a.run_id=? AND a.terminal_digest IS NULL AND a.status IN ('running','interrupted') AND v.effect='write'").all(ledger.runId);
+    // A requested pause (runtime pause) records its reason on the workflow_paused event.
+    const pauseEvent = row.status === 'paused' && !pending.length
+        ? ledger.db.sqlite.prepare("SELECT at,payload_json FROM events WHERE run_id=? AND type='workflow_paused' ORDER BY sequence DESC LIMIT 1").get(ledger.runId) : undefined;
+    const pausePayload = pauseEvent ? JSON.parse(String(pauseEvent.payload_json)).payload : undefined;
+    const pause = pausePayload && typeof pausePayload.reason === 'string' && typeof pausePayload.requestId === 'string'
+        ? { requestId: pausePayload.requestId, reason: pausePayload.reason, at: String(pauseEvent.at) } : undefined;
     const next = pending[0]?.nodePath ?? (row.status === 'succeeded' || row.status === 'cancelled' ? null : base.nextStep);
     const state = { ...(compact ? { runId: base.runId, traceId: base.traceId, status: base.status, updatedAt: base.updatedAt, usage: base.usage,
             ...(base.pendingApproval ? { pendingApproval: base.pendingApproval } : {}), ...(base.pendingQuestion ? { pendingQuestion: base.pendingQuestion } : {}) } : base),
-        nextNodePath: next, nextStep: next,
+        nextNodePath: next, nextStep: next, ...(pause ? { pause } : {}),
         steps: Object.fromEntries(steps.map(step => [String(step.node_path), { kind: String(step.kind), status: String(step.status), visits: Number(step.visits) }])),
         scopes: steps.map(step => {
             // Read only the current committed attempt. A previous successful visit is

package/dist/agent-runtime/engine/runs.d.ts

@@ -80,6 +80,11 @@ export declare function createRun(input: DefinitionRunInput & RunObservers): Pro
         error?: string;
         nextNodePath: string;
         nextStep: string;
+        pause?: {
+            requestId: string;
+            reason: string;
+            at: string;
+        } | undefined;
         steps: {
             [k: string]: {
                 kind: string;
@@ -176,6 +181,11 @@ export declare function createRun(input: DefinitionRunInput & RunObservers): Pro
         } | undefined;
         nextNodePath: string;
         nextStep: string;
+        pause?: {
+            requestId: string;
+            reason: string;
+            at: string;
+        } | undefined;
         steps: {
             [k: string]: {
                 kind: string;
@@ -285,6 +295,13 @@ export declare function createRun(input: DefinitionRunInput & RunObservers): Pro
             fullContexts: number;
             incrementalContexts: number;
         };
+        baseline: {
+            invocations: number;
+            roles: string[];
+            costUsd: number | null;
+            inputTokens: number | null;
+            outputTokens: number | null;
+        };
         escalations: {
             role: string;
             attemptId: string;
@@ -363,6 +380,11 @@ export declare function resumeRun(directory: string, options?: ResumeDefinitionO
         error?: string;
         nextNodePath: string;
         nextStep: string;
+        pause?: {
+            requestId: string;
+            reason: string;
+            at: string;
+        } | undefined;
         steps: {
             [k: string]: {
                 kind: string;
@@ -459,6 +481,11 @@ export declare function resumeRun(directory: string, options?: ResumeDefinitionO
         } | undefined;
         nextNodePath: string;
         nextStep: string;
+        pause?: {
+            requestId: string;
+            reason: string;
+            at: string;
+        } | undefined;
         steps: {
             [k: string]: {
                 kind: string;
@@ -568,6 +595,13 @@ export declare function resumeRun(directory: string, options?: ResumeDefinitionO
             fullContexts: number;
             incrementalContexts: number;
         };
+        baseline: {
+            invocations: number;
+            roles: string[];
+            costUsd: number | null;
+            inputTokens: number | null;
+            outputTokens: number | null;
+        };
         escalations: {
             role: string;
             attemptId: string;
@@ -603,3 +637,25 @@ export declare function cancelRun(directory: string, requestId?: string): Promis
     requestId: string;
     createdAt: string;
 }>;
+export declare const PAUSE_OUTCOMES: readonly ['requested', 'paused', 'already-paused', 'not-running', 'terminal'];
+export type PauseOutcome = typeof PAUSE_OUTCOMES[number];
+export interface PauseResult {
+    runId: string;
+    requestId: string;
+    reason: string;
+    outcome: PauseOutcome;
+    status: string;
+    createdAt?: string;
+}
+/**
+ * Cooperative pause. A run executing under a live lease receives an idempotent
+ * inbox request: its in-flight attempts finish and commit, the next admission is
+ * refused, and the owner settles `paused` with the reason and releases its lease.
+ * A run whose owner is gone while still marked running is settled `paused`
+ * directly. Terminal, already paused or otherwise stopped runs are left
+ * unchanged and reported as such. `runtime resume` continues every paused run.
+ */
+export declare function pauseRun(directory: string, options?: {
+    requestId?: string;
+    reason?: string;
+}): Promise<PauseResult>;

package/dist/agent-runtime/engine/runs.js

@@ -13,7 +13,7 @@ import { EngineEventStream } from './events.js';
 import { initialDefinitionState } from './state.js';
 import { preflightDefinition } from './preflight.js';
 import { observeLedger, projectRunStatus } from './run-status.js';
-import { ControlInbox } from './steering/inbox.js';
+import { ControlInbox, PAUSE_REASON } from './steering/inbox.js';
 import { ledgerBudget } from './invocation-context.js';
 import { composeDefinitionRuntime } from './composition.js';
 import { createEngineTelemetry } from './otel.js';
@@ -145,6 +145,8 @@ async function execute(database, admitted, options, resume) {
         if (resume)
             database.transaction('workflow-resumed', () => {
                 lease.assert(token);
+                // An explicit resume supersedes pause requests that arrived before it.
+                inbox.consumePauses();
                 appendRunEvent(database, runId, 'workflow_resumed', {});
             });
         stream.flush();
@@ -168,21 +170,30 @@ async function execute(database, admitted, options, resume) {
         if (controller.signal.reason instanceof EngineError && controller.signal.reason.code === 'lease_lost')
             throw controller.signal.reason;
         const reason = controller.signal.aborted ? controller.signal.reason : error;
-        const code = reason instanceof EngineError || reason && typeof reason === 'object' && 'code' in reason ? String(reason.code) : 'execution_failed';
+        const pause = controller.signal.aborted ? undefined : pauseOf(error);
+        const code = pause ? 'paused' : reason instanceof EngineError || reason && typeof reason === 'object' && 'code' in reason ? String(reason.code) : 'execution_failed';
         const message = reason instanceof Error ? reason.message : String(reason);
+        let settled;
         database.transaction('execution-stopped', () => {
             lease.assert(token);
             const row = ledger.run();
             if (row.completion_json)
                 return;
-            const status = code === 'aborted' ? 'cancelled' : row.status === 'interrupted' || code === 'recover_required' ? 'interrupted' : 'failed';
+            const status = code === 'aborted' ? 'cancelled' : pause ? 'paused' : row.status === 'interrupted' || code === 'recover_required' ? 'interrupted' : 'failed';
+            settled = status;
             database.put('runs', { ...row, status, active_duration_ms: ledger.activeDurationMs(), active_started_at: null, updated_at: new Date().toISOString() });
-            appendRunEvent(database, runId, status === 'cancelled' ? 'workflow_cancelled' : 'workflow_failed', { error: { code, message } });
+            if (pause) {
+                inbox.consumePauses();
+                appendRunEvent(database, runId, 'workflow_paused', { requestId: pause.requestId, reason: pause.reason });
+            }
+            else
+                appendRunEvent(database, runId, status === 'cancelled' ? 'workflow_cancelled' : 'workflow_failed', { error: { code, message } });
         });
         if (inbox.cancellationRequested())
             inbox.acknowledgeCancellation(token);
         const status = projectRunStatus(ledger);
-        return { ...status, error: { code, message } };
+        // A requested pause is a resumable stop, not a failure.
+        return settled === 'paused' ? status : { ...status, error: { code, message } };
     }
     finally {
         clearInterval(controlTimer);
@@ -194,6 +205,18 @@ async function execute(database, admitted, options, resume) {
         await telemetry?.close();
     }
 }
+/** The pause request carried by an admission refusal, also when several branches refused together. */
+function pauseOf(error) {
+    const errors = error instanceof AggregateError ? error.errors : [error];
+    for (const value of errors) {
+        if (value instanceof EngineError && value.code === 'paused' && value.details && typeof value.details === 'object' && !Array.isArray(value.details)) {
+            const details = value.details;
+            if (typeof details.requestId === 'string' && typeof details.reason === 'string')
+                return { requestId: details.requestId, reason: details.reason };
+        }
+    }
+    return undefined;
+}
 function validateAnswers(ledger, answers) {
     const known = new Map(ledger.interrupts().map(value => [value.id, value]));
     for (const [id, value] of Object.entries(answers)) {
@@ -245,3 +268,63 @@ export async function cancelRun(directory, requestId) {
         database.close();
     }
 }
+export const PAUSE_OUTCOMES = ['requested', 'paused', 'already-paused', 'not-running', 'terminal'];
+/**
+ * Cooperative pause. A run executing under a live lease receives an idempotent
+ * inbox request: its in-flight attempts finish and commit, the next admission is
+ * refused, and the owner settles `paused` with the reason and releases its lease.
+ * A run whose owner is gone while still marked running is settled `paused`
+ * directly. Terminal, already paused or otherwise stopped runs are left
+ * unchanged and reported as such. `runtime resume` continues every paused run.
+ */
+export async function pauseRun(directory, options = {}) {
+    const reason = options.reason ?? 'requested', requestId = options.requestId ?? randomUUID();
+    if (!PAUSE_REASON.test(reason))
+        throw new EngineError('invalid_arguments', 'Pause reason must be a lowercase token of 1–64 characters (for example requested or budget)');
+    if (!requestId || requestId.length > 256)
+        throw new EngineError('invalid_arguments', 'Control request ID must contain 1–256 characters');
+    const database = await RunDatabase.open(path.join(directory, 'run.sqlite'));
+    try {
+        const view = observeLedger(database), runId = view.runId;
+        const result = (outcome, createdAt) => ({ runId, requestId, reason, outcome, status: String(view.run().status), ...(createdAt ? { createdAt } : {}) });
+        const terminal = () => { const row = view.run(); return !!row.completion_json || row.status === 'succeeded' || row.status === 'cancelled'; };
+        if (terminal())
+            return result('terminal');
+        // Only this exact package can resume the run, so only it may pause it.
+        if (!sameRuntimeIdentity(JSON.parse(String(view.run().runtime_identity_json)), coreRuntimeIdentity()))
+            throw new EngineError('resume_incompatible', 'Pause requires the retained original Core package');
+        const lease = new RunLease(database, runId);
+        if ((lease.current()?.expiresAt ?? 0) > Date.now()) {
+            database.upgradeSchema();
+            const accepted = new ControlInbox(database, runId).pause(reason, requestId);
+            return result('requested', accepted.createdAt);
+        }
+        if (view.run().status === 'paused')
+            return result('already-paused');
+        if (view.run().status !== 'running')
+            return result('not-running');
+        const token = lease.acquire(randomUUID());
+        let outcome = 'paused';
+        try {
+            const ledger = new RunLedger(database, token, { maxTransitions: 1 });
+            database.transaction('workflow-paused', () => {
+                lease.assert(token);
+                const run = ledger.run();
+                // The owner may have settled between the observation and the lease.
+                if (run.completion_json || run.status !== 'running') {
+                    outcome = run.status === 'paused' ? 'already-paused' : run.completion_json || run.status === 'succeeded' || run.status === 'cancelled' ? 'terminal' : 'not-running';
+                    return;
+                }
+                database.put('runs', { ...run, status: 'paused', active_duration_ms: ledger.activeDurationMs(), active_started_at: null, updated_at: new Date().toISOString() });
+                appendRunEvent(database, runId, 'workflow_paused', { requestId, reason });
+            });
+        }
+        finally {
+            lease.release(token);
+        }
+        return result(outcome);
+    }
+    finally {
+        database.close();
+    }
+}

package/dist/agent-runtime/engine/steering/inbox.d.ts

@@ -4,6 +4,7 @@ export declare const MAX_STEERING_CHARACTERS = 20000;
 export declare const MAX_STEERING_BYTES = 80000;
 export declare const MAX_PENDING_STEERING = 128;
 export declare const MAX_PENDING_STEERING_BYTES: number;
+export declare const PAUSE_REASON: RegExp;
 export interface SteeringMessage {
     id: string;
     text: string;
@@ -34,6 +35,12 @@ export declare class ControlInbox {
         requestId: string;
         createdAt: string;
     };
+    /** Cooperative pause: the owner stops before admitting its next attempt and settles `paused`. */
+    pause(reason: string, requestId?: string): {
+        requestId: string;
+        createdAt: string;
+        reason: string;
+    };
     private appendControl;
     pending(): SteeringMessage[];
     /** Bounded read-only projection. Counts cover the whole inbox, previews never expose full prompts. */
@@ -48,6 +55,14 @@ export declare class ControlInbox {
     /** Called inside attempt admission, after the attempt row exists and the lease was fenced. */
     claimForAttempt(frame: AttemptFrame): SteeringMessage[];
     cancellationRequested(): boolean;
+    /** The oldest unconsumed pause request, if any. */
+    pauseRequested(): {
+        requestId: string;
+        reason: string;
+        createdAt: string;
+    } | undefined;
+    /** Marks every pending pause request consumed. Callers hold the lease inside their own transaction. */
+    consumePauses(): void;
     acknowledgeCancellation(token: ExecutionLease): void;
 }
 /** Operator text is delimited and cannot replace frozen acceptance obligations/instructions. */

package/dist/agent-runtime/engine/steering/inbox.js

@@ -7,6 +7,7 @@ export const MAX_STEERING_CHARACTERS = 20_000;
 export const MAX_STEERING_BYTES = 80_000;
 export const MAX_PENDING_STEERING = 128;
 export const MAX_PENDING_STEERING_BYTES = 512 * 1024;
+export const PAUSE_REASON = /^[a-z][a-z0-9-]{0,63}$/;
 const project = (row) => {
     const value = JSON.parse(String(row.payload_json));
     return { id: String(row.request_id), ...value, createdAt: String(row.created_at),
@@ -33,6 +34,13 @@ export class ControlInbox {
         const row = this.appendControl('cancel', {}, requestId);
         return { requestId: String(row.request_id), createdAt: String(row.created_at) };
     }
+    /** Cooperative pause: the owner stops before admitting its next attempt and settles `paused`. */
+    pause(reason, requestId = randomUUID()) {
+        if (!PAUSE_REASON.test(reason))
+            throw new EngineError('invalid_arguments', 'Pause reason must be a lowercase token of 1–64 characters (for example requested or budget)');
+        const row = this.appendControl('pause', { reason }, requestId);
+        return { requestId: String(row.request_id), createdAt: String(row.created_at), reason: JSON.parse(String(row.payload_json)).reason };
+    }
     appendControl(kind, payload, requestId) {
         if (!requestId || requestId.length > 256)
             throw new EngineError('invalid_arguments', 'Control request ID must contain 1–256 characters');
@@ -56,7 +64,7 @@ export class ControlInbox {
             }
             const at = new Date().toISOString();
             this.database.put('control_inbox', { request_id: requestId, run_id: this.runId, kind, payload_json: encoded, created_at: at, received_sequence: run.next_event_sequence });
-            appendRunEvent(this.database, this.runId, kind === 'steer' ? 'steering_received' : 'cancellation_requested', { requestId }, {}, at);
+            appendRunEvent(this.database, this.runId, kind === 'steer' ? 'steering_received' : kind === 'pause' ? 'pause_requested' : 'cancellation_requested', kind === 'pause' ? { requestId, reason: payload.reason } : { requestId }, {}, at);
             return this.database.get('control_inbox', { request_id: requestId });
         });
     }
@@ -95,6 +103,18 @@ export class ControlInbox {
     cancellationRequested() {
         return !!this.database.sqlite.prepare("SELECT 1 FROM control_inbox WHERE run_id=? AND kind='cancel' AND consumed_at IS NULL").get(this.runId);
     }
+    /** The oldest unconsumed pause request, if any. */
+    pauseRequested() {
+        const row = this.database.sqlite.prepare("SELECT * FROM control_inbox WHERE run_id=? AND kind='pause' AND consumed_at IS NULL ORDER BY received_sequence,request_id LIMIT 1").get(this.runId);
+        return row ? { requestId: String(row.request_id), reason: JSON.parse(String(row.payload_json)).reason, createdAt: String(row.created_at) } : undefined;
+    }
+    /** Marks every pending pause request consumed. Callers hold the lease inside their own transaction. */
+    consumePauses() {
+        const at = new Date().toISOString();
+        for (const row of this.database.sqlite.prepare("SELECT * FROM control_inbox WHERE run_id=? AND kind='pause' AND consumed_at IS NULL").all(this.runId)) {
+            this.database.put('control_inbox', { ...row, consumed_at: at });
+        }
+    }
     acknowledgeCancellation(token) {
         this.database.transaction('cancellation-consumed', () => {
             new RunLease(this.database, this.runId).assert(token);

package/dist/agent-runtime/engine/storage/private-path.js

@@ -19,12 +19,18 @@ if($actual.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $i
 foreach($entry in $actual.GetAccessRules($true,$true,[System.Security.Principal.SecurityIdentifier])) {
  if($entry.IdentityReference.Value -notin @($identity.User.Value,'S-1-5-18') -or $entry.AccessControlType -ne 'Allow'){throw 'Private directory grants broad access'}
 }`;
+// A cold `powershell.exe` that loads the .NET AccessControl types has taken
+// more than 30 s on a loaded windows-latest runner (run 39675761584: the first
+// RunDatabase.open of a file failed with the total execution limit). The bound
+// only protects against a hung PowerShell; a slow one must not fail closed
+// storage creation, so it gets the same headroom as other Windows cold starts.
+const WINDOWS_ACL_TIMEOUT_MS = 120_000;
 async function setPrivateWindowsAcl(target, cwd) {
     const env = { ...process.env, SPECRAILS_PRIVATE_PATH: target };
     for (const key of Object.keys(env))
         if (key.toLowerCase() === 'psmodulepath')
             delete env[key];
-    const result = await runCliProcess({ command: 'powershell.exe', args: ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(aclScript, 'utf16le').toString('base64')] }, { cwd, timeoutMs: 30_000, env });
+    const result = await runCliProcess({ command: 'powershell.exe', args: ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(aclScript, 'utf16le').toString('base64')] }, { cwd, timeoutMs: WINDOWS_ACL_TIMEOUT_MS, env });
     if (result.exitCode !== 0)
         throw new PersistenceError('private_storage_unavailable', `Cannot protect engine storage: ${result.stderr.slice(0, 2000)}`);
 }

package/dist/agent-runtime/evaluation.js

@@ -53,7 +53,7 @@ function fixtureRegistry(test, context, onPrompt) {
                 await tools.execute({ action: 'new' });
                 const artifacts = [
                     ['proposal', 'proposal.md', `## Why\n${test.description}\n## What Changes\n- Implement the requested behavior.\n## Capabilities\n### New Capabilities\n- \`fixture-behavior\`: ${test.description}\n### Modified Capabilities\nNone.\n## Impact\nSelected repositories.\n`],
-                    ['design', 'design.md', `## Context\n${test.description}\n## Decisions\nUse the existing implementation.cjs pattern and keep the public function boundary.`],
+                    ['design', 'design.md', `## Context\n${test.description}\n## Decisions\nUse the existing implementation.cjs pattern and keep the public function boundary.\n## Non-Goals\n- No change outside implementation.cjs.`],
                     ['specs', 'specs/fixture-behavior/spec.md', `## ADDED Requirements\n### Requirement: Requested behavior\nThe implementation SHALL satisfy the frozen behavior.\n#### Scenario: Supported input\n- **WHEN** a supported input is supplied\n- **THEN** the expected value is returned without losing required ordering or boundary behavior\n`],
                     ['tasks', 'tasks.md', '## 1. Implementation\n- [ ] 1.1 Implement and test the requested behavior\n'],
                 ];