specrails-core 6.4.0 → 6.6.0

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

@@ -13,9 +13,9 @@ export declare function configuredCapabilities(config: RuntimeConfig, registry:
     schemaVersion: 1;
     roles: {
         transport: string;
-        continuation: "supported" | "unsupported" | "unknown";
+        continuation: 'supported' | 'unsupported' | 'unknown';
         resumeRequiresFullContext?: boolean;
-        effortSupport: "supported" | "unsupported" | "unknown";
+        effortSupport: 'supported' | 'unsupported' | 'unknown';
         supportedEfforts: string[] | null;
         observedModel: boolean;
         observedEffort: boolean;

package/dist/agent-runtime/capabilities.js

@@ -36,6 +36,16 @@ export async function cliCapabilities(provider, model, options = {}) {
                 return { ...result, effortSupport: 'supported', supportedEfforts: levels };
         }
         else if (model && help.stdout.includes('--config')) {
+            // Ask the installed client for its own model catalog. Other Codex clients
+            // (the desktop app's app-server daemon, IDE extensions) share
+            // models_cache.json and rewrite it with their own version, so the cache
+            // is only a fallback for clients without `codex debug models`.
+            const catalog = await runner({ command: provider, args: ['debug', 'models'] }, { cwd: tmpdir(), env, timeoutMs: 10_000 }).catch(() => null);
+            if (catalog?.exitCode === 0 && catalog.stdout.length <= 2 * 1024 * 1024) {
+                const levels = codexModelEfforts(JSON.parse(catalog.stdout), model);
+                if (levels)
+                    return { ...result, effortSupport: 'supported', supportedEfforts: levels };
+            }
             // Use the installed client's own bounded, fresh model catalog. Do not
             // infer reasoning support from a model prefix or another provider.
             const file = path.join(env.CODEX_HOME ?? path.join(env.HOME ?? homedir(), '.codex'), 'models_cache.json');
@@ -48,16 +58,23 @@ export async function cliCapabilities(provider, model, options = {}) {
             const version = await runner({ command: provider, args: ['--version'] }, { cwd: tmpdir(), env, timeoutMs: 10_000 });
             if (version.exitCode !== 0 || version.stdout.trim() !== `codex-cli ${cache.client_version}`)
                 return result;
-            const entry = Array.isArray(cache.models) ? cache.models.find((item) => item?.slug === model) : undefined;
-            const levels = entry?.supported_reasoning_levels?.map((item) => item?.effort);
-            if (Array.isArray(levels) && levels.length && levels.every(value => typeof value === 'string' && /^[a-z][a-z0-9_-]{0,31}$/.test(value))) {
-                return { ...result, effortSupport: 'supported', supportedEfforts: [...new Set(levels)] };
-            }
+            const levels = codexModelEfforts(cache, model);
+            if (levels)
+                return { ...result, effortSupport: 'supported', supportedEfforts: levels };
         }
     }
     catch { /* Missing/stale metadata is unknown, never optimistic support. */ }
     return result;
 }
+/** Reasoning levels a Codex catalog (`{ models: [...] }`) declares for one model; null when unknown or malformed. */
+function codexModelEfforts(catalog, model) {
+    const models = catalog?.models;
+    const entry = Array.isArray(models) ? models.find((item) => item?.slug === model) : undefined;
+    const levels = entry?.supported_reasoning_levels?.map?.((item) => item?.effort);
+    if (!Array.isArray(levels) || !levels.length || !levels.every(value => typeof value === 'string' && /^[a-z][a-z0-9_-]{0,31}$/.test(value)))
+        return null;
+    return [...new Set(levels)];
+}
 export function assertEffortSupported(selection, capability) {
     if (selection.effort !== undefined && (capability.effortSupport !== 'supported' || !capability.supportedEfforts?.includes(selection.effort))) {
         throw new AgentExecutionError(`Requested effort '${selection.effort}' is not confirmed for ${capability.transport}. Select a supported effort or provider default.`, 'provider_capability_unsupported');

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

@@ -32,7 +32,7 @@ export function buildCliInvocation(provider, request, options = {}) {
     }
     const readOnly = requestPolicy(request).access === 'read';
     // Pin the product alias; explicit IDs remain reproducible across releases.
-    const claudeModelIds = { opus: 'claude-opus-5-5', sonnet: 'claude-sonnet-5-5' };
+    const claudeModelIds = { opus: 'claude-opus-5-5', sonnet: 'claude-sonnet-5-5', haiku: 'claude-haiku-5-5' };
     const modelId = provider === 'claude' && request.model ? claudeModelIds[request.model] ?? request.model : request.model;
     const model = modelId ? ['--model', modelId] : [];
     const extraRoots = request.allowedRoots.filter(root => root !== request.cwd);
@@ -54,14 +54,19 @@ export function buildCliInvocation(provider, request, options = {}) {
                 ...(resume ? ['--resume', resume] : []),
             ] };
         case 'codex': {
-            const sandbox = readOnly ? 'read-only' : 'workspace-write';
+            // Writers run without Codex's OS sandbox, like the Claude developer
+            // (--dangerously-skip-permissions) and Desktop's legacy rail runs: the
+            // workspace-write seatbelt denies what real verification needs (a
+            // localhost listen, Chromium's Mach bootstrap registration, the browser
+            // cache). Read-only roles keep the read-only sandbox.
+            const sandbox = readOnly ? 'read-only' : 'danger-full-access';
             const common = ['--json', '--skip-git-repo-check', '-c', 'approval_policy="never"', ...model,
                 ...(request.effort === undefined ? [] : ['-c', 'model_reasoning_effort=' + JSON.stringify(request.effort)]),
                 ...(options.openspecBridge ? ['-c', 'mcp_servers.specrails_openspec.command=' + JSON.stringify(options.openspecBridge.command), '-c', 'mcp_servers.specrails_openspec.args=' + JSON.stringify(options.openspecBridge.args), '-c', 'mcp_servers.specrails_openspec.default_tools_approval_mode="approve"', '-c', 'mcp_servers.specrails_openspec.required=true'] : []),
             ];
             // `codex exec resume` has no --sandbox flag; the same policy travels as a config override.
             if (resume)
-                return { command: 'codex', stdin: request.prompt, args: ['exec', 'resume', ...common, '-c', `sandbox_mode="${sandbox}"`, '-c', 'sandbox_workspace_write.writable_roots=' + JSON.stringify(readOnly ? [] : request.allowedRoots), resume, '-'] };
+                return { command: 'codex', stdin: request.prompt, args: ['exec', 'resume', ...common, '-c', `sandbox_mode="${sandbox}"`, ...(readOnly ? ['-c', 'sandbox_workspace_write.writable_roots=[]'] : []), resume, '-'] };
             return { command: 'codex', stdin: request.prompt, args: [
                     'exec', ...common, '--sandbox', sandbox,
                     ...(options.codexSchemaFile ? ['--output-schema', options.codexSchemaFile] : []),

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

@@ -4,13 +4,13 @@ export declare function runtimeFailure(error: unknown): {
     type: string;
     status: string;
     error: string | {
-        details?: import("./workflow-types.js").JsonValue | undefined;
         code: string;
         message: string;
+        details?: import("./workflow-types.js").JsonValue | undefined;
     };
 };
 /** Machine operations are mirrored in integration-contract.json; help is presentation-only. */
-export declare const RUNTIME_CLI_OPERATIONS: readonly ["api", "validate", "run", "status", "resume", "prompts", "capabilities", "evidence", "recovery", "evaluate", "workflows", "fork", "signal", "cancel", "help"];
+export declare const RUNTIME_CLI_OPERATIONS: readonly ['api', 'validate', 'run', 'status', 'resume', 'prompts', 'capabilities', 'evidence', 'recovery', 'evaluate', 'workflows', 'fork', 'signal', 'cancel', 'host', 'help'];
 /** The host-facing summary: phase status, pending interrupts and usage without accumulated outputs. */
 export declare function compactState(state: WorkflowState | null): {
     runId: string;
@@ -42,13 +42,13 @@ export declare function compactState(state: WorkflowState | null): {
     };
     steps: {
         [k: string]: {
-            status: "pending" | "running" | "interrupted" | import("./workflow-types.js").StepStatus;
+            status: "interrupted" | "pending" | "running" | import("./workflow-types.js").StepStatus;
             visits: number;
         };
     };
     recentFailures: {
         stepId: string;
-        status: "running" | "interrupted" | import("./workflow-types.js").StepStatus;
+        status: "interrupted" | "running" | import("./workflow-types.js").StepStatus;
         attempt: number;
         visit: number;
         at: string;

package/dist/agent-runtime/cli.js

@@ -18,14 +18,58 @@ import { configuredCapabilities } from './capabilities.js';
 import { createExecutorRegistry } from './executors.js';
 import { runRecovery } from './recovery.js';
 import { EngineError } from './engine/contracts.js';
+/**
+ * Long-lived agent session host (docs/agent-sessions/protocol.md). Loaded lazily
+ * so batch operations never initialize session drivers or the journal.
+ */
+async function runSessionHost(flags) {
+    if (flags.stdio !== true)
+        throw new Error('runtime host requires --stdio');
+    if (flags.scope !== undefined && typeof flags.scope !== 'string')
+        throw new Error('--scope requires a value');
+    const [{ createSessionRuntime, GLOBAL_SESSION_SCOPE }, { SessionHost }, { CliExecutor }] = await Promise.all([
+        import('./session/index.js'),
+        import('./session/host/server.js'),
+        import('./cli-executor.js'),
+    ]);
+    const scope = flags.scope ?? GLOBAL_SESSION_SCOPE;
+    let host = null;
+    const runtime = await createSessionRuntime({
+        scope,
+        drivers: {
+            executors: [
+                { id: 'gemini', displayName: 'Gemini CLI', executor: new CliExecutor('gemini') },
+                { id: 'kimi', displayName: 'Kimi Code', executor: new CliExecutor('kimi') },
+            ],
+        },
+        onLeaseLost: () => host?.leaseLost(),
+    });
+    host = new SessionHost({ service: runtime.service, scope, identity: { ...coreRuntimeIdentity(), coreVersion: CORE_PACKAGE_VERSION }, close: () => runtime.close() }, { input: process.stdin, output: process.stdout });
+    const stop = () => { void host?.stop(); };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+    try {
+        await host.start();
+        return 0;
+    }
+    finally {
+        process.off('SIGINT', stop);
+        process.off('SIGTERM', stop);
+        // A stopped host must not be kept alive by its still-open stdin pipe.
+        process.stdin.destroy();
+    }
+}
 /** Both runtime entry points emit the same machine-readable fatal result. */
 export function runtimeFailure(error) {
     return { type: 'runtime-result', status: 'failed', error: error instanceof EngineError
             ? { code: error.code, message: error.message, ...(error.details === undefined ? {} : { details: error.details }) }
-            : error instanceof Error ? error.message : String(error) };
+            // Session errors keep their code so hosts can react (e.g. `journal_locked` must not be retried).
+            : error instanceof Error && error.name === 'SessionError' && typeof error.code === 'string'
+                ? { code: error.code, message: error.message }
+                : error instanceof Error ? error.message : String(error) };
 }
 /** Machine operations are mirrored in integration-contract.json; help is presentation-only. */
-export const RUNTIME_CLI_OPERATIONS = ['api', 'validate', 'run', 'status', 'resume', 'prompts', 'capabilities', 'evidence', 'recovery', 'evaluate', 'workflows', 'fork', 'signal', 'cancel', 'help'];
+export const RUNTIME_CLI_OPERATIONS = ['api', 'validate', 'run', 'status', 'resume', 'prompts', 'capabilities', 'evidence', 'recovery', 'evaluate', 'workflows', 'fork', 'signal', 'cancel', 'host', 'help'];
 function read(file) { return JSON.parse(readFileSync(file, 'utf8')); }
 async function readStdin() {
     const chunks = [];
@@ -150,6 +194,7 @@ export async function runRuntimeCommand(flags, positionals, emit = value => proc
                 'specrails-core runtime fork --context <json> --from <nodePath> --run-id <newRunId> [--scope-id <scope>] [--visit <number>] [--state <json>]',
                 'specrails-core runtime signal --context <json> --stdin [--request-id <id>]',
                 'specrails-core runtime cancel --context <json> [--request-id <id>]',
+                'specrails-core runtime host --stdio [--scope <projectKey|global>]',
             ] });
         return 0;
     }
@@ -158,9 +203,11 @@ export async function runRuntimeCommand(flags, positionals, emit = value => proc
         emit({ type: 'runtime-api', apiVersion: RUNTIME_API_VERSION, coreVersion: CORE_PACKAGE_VERSION, runtimeIdentity: coreRuntimeIdentity(), workflowVersions: [CORE_WORKFLOW_VERSION],
             engineVersion: 2, engines: RUNTIME_ENGINES, nodeKindsVersion: NODE_KINDS_VERSION, nodeKinds: validationPieceRegistry().kinds(),
             capabilities: { openRoles: 1, scopedRecovery: 1, efficientRoleExecution: 1, reproducibleVerification: 1, implementationEfficiencyMetrics: 1, compactAgentLoop: 1, configurableGuardrails: 1, compactOutputBudget: 1, roleThinkingControl: 1, repositoryScope: 1,
-                engineV2: 1, workflowAgentSteps: 1, implementationSteps: 1, workflowDefinitions: 1, fanOut: 1, fork: 1, forkIdempotency: 1, steeringInbox: 1, hostBlockers: 1, setupCommands: 1 }, guardrails: GUARDRAIL_CATALOG });
+                engineV2: 1, workflowAgentSteps: 1, implementationSteps: 1, workflowDefinitions: 1, fanOut: 1, fork: 1, forkIdempotency: 1, steeringInbox: 1, hostBlockers: 1, setupCommands: 1, sessions: 1 }, guardrails: GUARDRAIL_CATALOG });
         return 0;
     }
+    if (command === 'host')
+        return runSessionHost(flags);
     if (command === 'validate') {
         if (flags.stdin !== undefined && flags.stdin !== true)
             throw new Error('--stdin is a boolean flag');

package/dist/agent-runtime/compact/environment.d.ts

@@ -1,5 +1,5 @@
 import type { spawnSync } from 'node:child_process';
-/** `timeoutMs` overrides the default bound for one plan (a browser download is far larger than a dependency install). */
+/** `timeoutMs` overrides the default bound for one plan (a browser download is far larger than a dependency install). `drift`: installed direct dependencies the install must bring back inside their declared ranges. */
 export interface EnvironmentInstall {
     ecosystem: 'node' | 'python' | 'go' | 'rust';
     root: string;
@@ -7,12 +7,20 @@ export interface EnvironmentInstall {
     args: string[];
     timeoutMs?: number;
     installs?: string;
+    drift?: DriftedDependency[];
 }
-/** `precondition`: the install failed for a reason only the host can repair (see hostPreconditionFailure). */
+/** `precondition`: the install failed for a reason only the host can repair (see hostPreconditionFailure). `driftPersists`: drifted packages a successful install left drifted (the lockfile pins them). */
 export interface InstallOutcome extends EnvironmentInstall {
     ok: boolean;
     detail: string;
     precondition?: string;
+    driftPersists?: DriftedDependency[];
+}
+/** An installed direct dependency whose version does not satisfy the range package.json declares. */
+export interface DriftedDependency {
+    name: string;
+    declared: string;
+    installed: string;
 }
 export type HostPreconditionKind = 'network' | 'credential' | 'environment-variable' | 'toolchain' | 'setup' | 'environment';
 export interface HostPrecondition {
@@ -44,10 +52,20 @@ export declare function hostPrecondition(output: string): HostPrecondition | und
 export declare function suggestedPackages(output: string): string[];
 /** Dependencies package.json declares that node_modules does not hold (bounded). */
 export declare function missingNodeDependencies(root: string): string[];
+/**
+ * Installed direct dependencies whose version fails the range package.json
+ * declares (bounded, never throws): a tree installed for other inputs, such as
+ * a warm link from a base checkout or a manifest edited after the install,
+ * passes `missingNodeDependencies` and then fails lint on an untouched file.
+ * Absent packages are `missingNodeDependencies`' to report.
+ */
+export declare function driftedNodeDependencies(root: string): DriftedDependency[];
+/** `@busuu/experiments 5.23.0 does not satisfy ^5.24.0, …` for up to five packages. */
+export declare function describeDrift(drift: readonly DriftedDependency[]): string;
 /** The installs a repository root needs, judged from its manifests and the absence of their install output. */
 export declare function plannedInstalls(root: string, failureOutput?: string): EnvironmentInstall[];
 /** Runs each planned install once, bounded; never throws. */
-export declare function installEnvironment(roots: readonly string[], io?: {
+export interface InstallIo {
     spawn?: typeof spawnSync;
     timeoutMs?: number;
     failureOutput?: string;
@@ -58,7 +76,35 @@ export declare function installEnvironment(roots: readonly string[], io?: {
         detail?: string;
         text?: string;
     }) => void;
-}): InstallOutcome[];
+    /** The installs for one root; the failure-driven plan by default. */
+    plan?: (root: string) => EnvironmentInstall[];
+}
+export declare function installEnvironment(roots: readonly string[], io?: InstallIo): InstallOutcome[];
+type PlaywrightBrowser = 'chromium' | 'firefox' | 'webkit';
+/** Browsers the repository's Playwright config runs (by project names, devices or browserName); chromium when it names none. */
+export declare function configuredPlaywrightBrowsers(root: string): PlaywrightBrowser[];
+/**
+ * The configured browsers when any build the installed Playwright pins is
+ * missing from the host cache. `install --dry-run` names the exact install
+ * locations without downloading; an unreadable answer means "unknown", never
+ * an install.
+ */
+export declare function missingPlaywrightBrowsers(root: string, spawn?: typeof spawnSync): PlaywrightBrowser[];
+/**
+ * Host preparation before an agent edits a repository: the dependencies its
+ * manifest declares but are not installed, then the browser builds its
+ * Playwright pins. Agents run sandboxed (Codex cannot write the browser cache
+ * or reach it at all), so what they need must already be there. Only cheap,
+ * idempotent, project-local work happens here; other ecosystems keep their
+ * failure-driven repair at verification.
+ */
+export declare function prepareEnvironment(roots: readonly string[], io?: Omit<InstallIo, 'plan' | 'failureOutput'>): InstallOutcome[];
+/**
+ * A Node preload that answers IPv6 lookups with nothing when the host has an
+ * IPv4 address, so dual-stack clients connect over IPv4. Written once to the
+ * temp directory; undefined when it cannot be written.
+ */
+export declare function ipv4FirstPreload(): string | undefined;
 /** The repository's own test command, judged from its manifest (npm/pnpm/yarn `test` script, pytest, go, cargo); undefined when none. */
 export declare function detectCheckCommand(root: string): {
     command: string;

package/dist/agent-runtime/compact/environment.js

@@ -1,6 +1,8 @@
 import crossSpawn from 'cross-spawn';
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import path from 'node:path';
+import semver from 'semver';
 // npm/pnpm/yarn are `.cmd` shims on Windows: a bare `spawnSync('npm')` is
 // ENOENT there, which read as an environment failure of its own and sent the
 // install/check round in circles. cross-spawn resolves the shim on every OS.
@@ -132,6 +134,56 @@ export function missingNodeDependencies(root) {
     }
     return [...declared].filter(name => !existsSync(path.join(root, 'node_modules', name))).slice(0, 20);
 }
+// Specifiers with no installed-version contract to check locally; reporting
+// them would plan an install on every run.
+const NON_SEMVER_SPECIFIER = /^(?:workspace:|file:|link:|portal:|patch:|npm:|catalog:|git[+:]|github:|gitlab:|bitbucket:|https?:|ssh:)|\//;
+/**
+ * Installed direct dependencies whose version fails the range package.json
+ * declares (bounded, never throws): a tree installed for other inputs, such as
+ * a warm link from a base checkout or a manifest edited after the install,
+ * passes `missingNodeDependencies` and then fails lint on an untouched file.
+ * Absent packages are `missingNodeDependencies`' to report.
+ */
+export function driftedNodeDependencies(root) {
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'));
+    }
+    catch {
+        return [];
+    }
+    const drifted = new Map();
+    for (const field of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+        const block = manifest[field];
+        if (!block || typeof block !== 'object' || Array.isArray(block))
+            continue;
+        for (const [name, declared] of Object.entries(block)) {
+            if (drifted.has(name) || typeof declared !== 'string' || NON_SEMVER_SPECIFIER.test(declared.trim()))
+                continue;
+            const range = semver.validRange(declared);
+            if (!range)
+                continue;
+            let installed;
+            try {
+                installed = JSON.parse(readFileSync(path.join(root, 'node_modules', name, 'package.json'), 'utf8')).version;
+            }
+            catch {
+                continue;
+            }
+            if (typeof installed !== 'string' || !semver.valid(installed))
+                continue;
+            if (!semver.satisfies(installed, range, { includePrerelease: false }))
+                drifted.set(name, { name, declared, installed });
+            if (drifted.size >= 20)
+                return [...drifted.values()];
+        }
+    }
+    return [...drifted.values()];
+}
+/** `@busuu/experiments 5.23.0 does not satisfy ^5.24.0, …` for up to five packages. */
+export function describeDrift(drift) {
+    return drift.slice(0, 5).map(item => `${item.name} ${item.installed} does not satisfy ${item.declared}`).join(', ') + (drift.length > 5 ? ` and ${drift.length - 5} more` : '');
+}
 /** Browser builds are ~150 MB each; the default 5-minute install bound is too short on a slow link. */
 const PLAYWRIGHT_INSTALL_TIMEOUT_MS = 10 * 60_000;
 /** True when package.json declares `@playwright/test` or `playwright`; only those repositories get a browser install plan. */
@@ -160,9 +212,12 @@ export function plannedInstalls(root, failureOutput = '') {
     // A manifest edited after the first install (a later task group adds
     // jest-extended) leaves node_modules present but incomplete; verify then
     // fails on the environment, not the code. Declared-but-absent ⇒ reinstall.
-    if (has('package.json') && (!has('node_modules') || missingNodeDependencies(root).length)) {
+    // A version outside its declared range (a stale warm-linked tree) is the
+    // same kind of gap: the same install brings it back in range.
+    const drift = has('package.json') && has('node_modules') ? driftedNodeDependencies(root) : [];
+    if (has('package.json') && (!has('node_modules') || missingNodeDependencies(root).length || drift.length)) {
         const runner = has('pnpm-lock.yaml') ? 'pnpm' : has('yarn.lock') ? 'yarn' : 'npm';
-        plans.push({ ecosystem: 'node', root, command: runner, args: runner === 'npm' ? ['install', '--no-audit', '--no-fund', '--loglevel=error'] : ['install'] });
+        plans.push({ ecosystem: 'node', root, command: runner, args: runner === 'npm' ? ['install', '--no-audit', '--no-fund', '--loglevel=error'] : ['install'], ...(drift.length ? { drift } : {}) });
     }
     // After the dependency plan: a fresh worktree needs node_modules before
     // `playwright install` can run at all.
@@ -208,12 +263,11 @@ function relaxManifestPin(root, name, version) {
         writeFileSync(file, JSON.stringify(manifest, null, 2) + '\n');
     return changed;
 }
-/** Runs each planned install once, bounded; never throws. */
 export function installEnvironment(roots, io = {}) {
     const spawn = io.spawn ?? defaultSpawn;
     const outcomes = [];
     for (const root of roots) {
-        for (const plan of plannedInstalls(root, io.failureOutput ?? '')) {
+        for (const plan of io.plan ? io.plan(root) : plannedInstalls(root, io.failureOutput ?? '')) {
             io.onEvent?.({ kind: 'tool-start', tool: plan.command, detail: `${plan.args.join(' ')} (${path.basename(root)})` });
             const run = () => {
                 try {
@@ -245,16 +299,139 @@ export function installEnvironment(roots, io = {}) {
                 io.onEvent?.({ kind: 'text', text: `Environment: ${unpublished[1]}@${unpublished[2]} is not published; relaxed the pin in package.json and retrying ${plan.command} ${plan.args.join(' ')}` });
                 result = run();
             }
+            // Playwright's downloader tries IPv6 first; on a host whose DNS returns
+            // an AAAA record without an IPv6 route, Node's family auto-selection
+            // times the request out before IPv4 is tried. Retry once preferring IPv4.
+            if (result.status !== 0 && plan.installs?.startsWith('Playwright') && NETWORK_TIMEOUT.test(`${result.stdout ?? ''}\n${result.stderr ?? ''}`)) {
+                const preload = ipv4FirstPreload();
+                if (preload) {
+                    io.onEvent?.({ kind: 'text', text: `Environment: the browser download timed out; retrying ${plan.command} ${plan.args.join(' ')} over IPv4` });
+                    try {
+                        result = spawn(plan.command, plan.args, { cwd: root, encoding: 'utf8', timeout: plan.timeoutMs ?? io.timeoutMs ?? 5 * 60_000, windowsHide: true, env: { ...process.env, NODE_OPTIONS: `${process.env.NODE_OPTIONS ?? ''} --require ${JSON.stringify(preload)}`.trim() } });
+                    }
+                    catch (error) {
+                        result = { status: null, error: error, stdout: '', stderr: '', pid: 0, output: [], signal: null };
+                    }
+                }
+            }
             io.onEvent?.({ kind: 'tool-end', tool: plan.command });
             const ok = result.status === 0;
-            const detail = ok ? `installed ${plan.installs ?? `${plan.ecosystem} dependencies`} in ${path.basename(root)}` : `${plan.command} ${plan.args.join(' ')} failed in ${path.basename(root)}: ${String(result.stderr || result.error?.message || `exit ${result.status}`).trim().slice(0, 400)}`;
+            const detail = ok ? `installed ${plan.installs ?? `${plan.ecosystem} dependencies`} in ${path.basename(root)}${plan.drift?.length ? ` (${describeDrift(plan.drift)})` : ''}` : `${plan.command} ${plan.args.join(' ')} failed in ${path.basename(root)}: ${String(result.stderr || result.error?.message || `exit ${result.status}`).trim().slice(0, 400)}`;
             io.onEvent?.({ kind: 'text', text: `Environment: ${detail}` });
+            // An install that leaves the drift in place means the lockfile itself
+            // resolves the old version: a code change, never a second install.
+            const persisting = ok && plan.drift?.length ? driftedNodeDependencies(root).filter(item => plan.drift.some(before => before.name === item.name)) : [];
+            if (persisting.length)
+                io.onEvent?.({ kind: 'text', text: `Environment: ${describeDrift(persisting)} after installing in ${path.basename(root)}; the lockfile still resolves the drifted version, so update the lockfile or the declared range.` });
             const precondition = ok ? undefined : hostPreconditionFailure(`${result.stdout ?? ''}\n${result.stderr ?? ''}`);
-            outcomes.push({ ...plan, ok, detail, ...(precondition ? { precondition } : {}) });
+            outcomes.push({ ...plan, ok, detail, ...(precondition ? { precondition } : {}), ...(persisting.length ? { driftPersists: persisting } : {}) });
         }
     }
     return outcomes;
 }
+const PLAYWRIGHT_CONFIGS = ['playwright.config.ts', 'playwright.config.mts', 'playwright.config.cts', 'playwright.config.js', 'playwright.config.mjs', 'playwright.config.cjs'];
+/** Browsers the repository's Playwright config runs (by project names, devices or browserName); chromium when it names none. */
+export function configuredPlaywrightBrowsers(root) {
+    const file = PLAYWRIGHT_CONFIGS.map(name => path.join(root, name)).find(candidate => existsSync(candidate));
+    let source = '';
+    try {
+        if (file)
+            source = readFileSync(file, 'utf8').slice(0, 200_000);
+    }
+    catch { /* unreadable config: the default browser */ }
+    const browsers = [];
+    if (/\b(?:chromium|chrome|edge|pixel|galaxy)\b/i.test(source))
+        browsers.push('chromium');
+    if (/\bfirefox\b/i.test(source))
+        browsers.push('firefox');
+    if (/\b(?:webkit|safari|iphone|ipad)\b/i.test(source))
+        browsers.push('webkit');
+    return browsers.length ? browsers : ['chromium'];
+}
+/** How to run the repository's own Playwright CLI; undefined until its package is installed (never downloads one). */
+function playwrightCli(root) {
+    const bin = path.join(root, 'node_modules', '.bin');
+    if (!['playwright', 'playwright.cmd'].some(name => existsSync(path.join(bin, name))))
+        return undefined;
+    if (existsSync(path.join(root, 'pnpm-lock.yaml')))
+        return { command: 'pnpm', args: ['exec', 'playwright'] };
+    if (existsSync(path.join(root, 'yarn.lock')))
+        return { command: 'yarn', args: ['playwright'] };
+    return { command: 'npx', args: ['--no', 'playwright'] };
+}
+/**
+ * The configured browsers when any build the installed Playwright pins is
+ * missing from the host cache. `install --dry-run` names the exact install
+ * locations without downloading; an unreadable answer means "unknown", never
+ * an install.
+ */
+export function missingPlaywrightBrowsers(root, spawn = defaultSpawn) {
+    if (!declaresPlaywright(root))
+        return [];
+    const cli = playwrightCli(root);
+    if (!cli)
+        return [];
+    const browsers = configuredPlaywrightBrowsers(root);
+    let result;
+    try {
+        result = spawn(cli.command, [...cli.args, 'install', '--dry-run', ...browsers], { cwd: root, encoding: 'utf8', timeout: 30_000, windowsHide: true, env: process.env });
+    }
+    catch {
+        return [];
+    }
+    if (result.status !== 0)
+        return [];
+    const locations = [...String(result.stdout ?? '').matchAll(/Install location:\s+(.+?)\s*$/gm)].map(match => match[1]);
+    return locations.length && locations.some(location => !existsSync(location)) ? browsers : [];
+}
+/**
+ * Host preparation before an agent edits a repository: the dependencies its
+ * manifest declares but are not installed, then the browser builds its
+ * Playwright pins. Agents run sandboxed (Codex cannot write the browser cache
+ * or reach it at all), so what they need must already be there. Only cheap,
+ * idempotent, project-local work happens here; other ecosystems keep their
+ * failure-driven repair at verification.
+ */
+export function prepareEnvironment(roots, io = {}) {
+    const spawn = io.spawn ?? defaultSpawn;
+    const dependencies = installEnvironment(roots, { ...io, plan: root => plannedInstalls(root).filter(plan => plan.ecosystem === 'node') });
+    const browsers = installEnvironment(roots, { ...io, plan: root => {
+            const missing = missingPlaywrightBrowsers(root, spawn);
+            const cli = missing.length ? playwrightCli(root) : undefined;
+            return cli ? [{ ecosystem: 'node', root, command: cli.command, args: [...cli.args, 'install', ...missing], timeoutMs: PLAYWRIGHT_INSTALL_TIMEOUT_MS, installs: `Playwright ${missing.join(', ')}` }] : [];
+        } });
+    return [...dependencies, ...browsers];
+}
+const NETWORK_TIMEOUT = /timed out after \d+ ?ms|ETIMEDOUT|ENETUNREACH|EHOSTUNREACH/i;
+/**
+ * A Node preload that answers IPv6 lookups with nothing when the host has an
+ * IPv4 address, so dual-stack clients connect over IPv4. Written once to the
+ * temp directory; undefined when it cannot be written.
+ */
+export function ipv4FirstPreload() {
+    const file = path.join(tmpdir(), 'specrails-ipv4-first-v1.cjs');
+    if (existsSync(file))
+        return file;
+    try {
+        writeFileSync(file, [
+            "const dns = require('node:dns')",
+            'const lookup = dns.promises.lookup.bind(dns.promises)',
+            'dns.promises.lookup = async (hostname, options) => {',
+            "  const family = typeof options === 'number' ? options : options && options.family",
+            '  if (family === 6) {',
+            '    const v4 = await lookup(hostname, { all: true, family: 4 }).catch(() => [])',
+            "    if (v4.length) { if (options && typeof options === 'object' && options.all) return []; throw Object.assign(new Error('IPv6 skipped: ' + hostname), { code: 'ENOTFOUND' }) }",
+            '  }',
+            '  return lookup(hostname, options)',
+            '}',
+            '',
+        ].join('\n'));
+        return file;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** The repository's own test command, judged from its manifest (npm/pnpm/yarn `test` script, pytest, go, cargo); undefined when none. */
 export function detectCheckCommand(root) {
     const has = (file) => existsSync(path.join(root, file));

package/dist/agent-runtime/compact/step.d.ts

@@ -40,7 +40,7 @@ export declare function openspecCall(env: CompactEnv, input: Parameters<OpenSpec
 export declare const PLANNING_CONTROLS: {
     readonly temperature: 0.2;
     readonly maxOutputTokens: 16384;
-    readonly reasoningEffort: "high";
+    readonly reasoningEffort: 'high';
 };
 export declare function structuredStep(env: CompactEnv, name: string, system: string, user: string, schema: Record<string, unknown>, validate?: (value: Record<string, unknown>) => string | undefined, controls?: {
     temperature?: number;

package/dist/agent-runtime/efficiency-summary.d.ts

@@ -25,7 +25,7 @@ export declare function efficiencySummary(state: WorkflowState, context: Pipelin
     workflowVersion: string;
     technicalAcceptance: string;
     archive: import("../pipeline/pipeline-state.js").PhaseStatus;
-    delivery: "pending" | "complete" | "pending-host";
+    delivery: "complete" | "pending" | "pending-host";
     roles: {
         role: string;
         provider: string | null;

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

@@ -28,7 +28,7 @@ export interface ProviderInvocation {
         costUsd: number | null;
     };
 }
-export declare const CACHE_TOKEN_KEYS: readonly ["uncachedInputTokens", "cacheReadInputTokens", "cacheWriteInputTokens"];
+export declare const CACHE_TOKEN_KEYS: readonly ['uncachedInputTokens', 'cacheReadInputTokens', 'cacheWriteInputTokens'];
 export declare function sumCacheUsage(values: CacheTokenUsage[]): CacheTokenUsage;
 export interface EfficiencyTotals {
     attempts: number;

package/dist/agent-runtime/engine/checkpoint/database.d.ts

@@ -5,21 +5,21 @@ export type DatabaseRow = Record<string, SQLOutputValue>;
 export type WriteRow = Record<string, SQLInputValue>;
 /** Every identifier interpolated into SQL comes from this closed adapter-owned map. */
 declare const keys: {
-    readonly runs: readonly ["run_id"];
-    readonly visits: readonly ["visit_id"];
-    readonly steps: readonly ["run_id", "node_path", "scope_id"];
-    readonly attempts: readonly ["attempt_id"];
-    readonly invocations: readonly ["invocation_id"];
-    readonly receipts: readonly ["receipt_id"];
-    readonly budget: readonly ["run_id"];
-    readonly interrupts: readonly ["interrupt_id"];
-    readonly control_inbox: readonly ["request_id"];
-    readonly role_sessions: readonly ["session_key"];
-    readonly piece_state: readonly ["run_id", "scope_id", "node_path", "key"];
-    readonly reservations: readonly ["reservation_id"];
-    readonly events: readonly ["run_id", "sequence"];
-    readonly checkpoints: readonly ["thread_id", "checkpoint_ns", "checkpoint_id"];
-    readonly writes: readonly ["thread_id", "checkpoint_ns", "checkpoint_id", "task_id", "idx"];
+    readonly runs: readonly ['run_id'];
+    readonly visits: readonly ['visit_id'];
+    readonly steps: readonly ['run_id', 'node_path', 'scope_id'];
+    readonly attempts: readonly ['attempt_id'];
+    readonly invocations: readonly ['invocation_id'];
+    readonly receipts: readonly ['receipt_id'];
+    readonly budget: readonly ['run_id'];
+    readonly interrupts: readonly ['interrupt_id'];
+    readonly control_inbox: readonly ['request_id'];
+    readonly role_sessions: readonly ['session_key'];
+    readonly piece_state: readonly ['run_id', 'scope_id', 'node_path', 'key'];
+    readonly reservations: readonly ['reservation_id'];
+    readonly events: readonly ['run_id', 'sequence'];
+    readonly checkpoints: readonly ['thread_id', 'checkpoint_ns', 'checkpoint_id'];
+    readonly writes: readonly ['thread_id', 'checkpoint_ns', 'checkpoint_id', 'task_id', 'idx'];
 };
 export type RevisionTable = keyof typeof keys;
 /** Short synchronous transactions own graph writes and ledger evidence together. */

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

@@ -103,7 +103,8 @@ export interface ReceiptEvidence {
  * is reserved for a correction role that diagnoses the cause outside the change.
  */
 export interface HostBlocker {
-    kind: 'network' | 'credential' | 'environment-variable' | 'toolchain' | 'setup' | 'environment' | 'scope';
+    /** `nondeterministic-output`: verification rewrites candidate files differently on every run (error code `verification_nondeterministic_output`). */
+    kind: 'network' | 'credential' | 'environment-variable' | 'toolchain' | 'setup' | 'environment' | 'scope' | 'nondeterministic-output';
     reason: string;
     command: string;
     args: string[];

package/dist/agent-runtime/engine/definition-types.d.ts

@@ -1,5 +1,5 @@
 import type { EngineEffect, JsonObject, WorkflowBudget } from './contracts.js';
-export declare const PIECE_KINDS: readonly ["prompt", "role-turn", "decider", "condition", "assign", "verify", "shell", "artifact-contract", "openspec-validate", "openspec-archive", "approval", "question", "gate", "map", "join", "component", "implementation", "implementation-step", "end"];
+export declare const PIECE_KINDS: readonly ['prompt', 'role-turn', 'decider', 'condition', 'assign', 'verify', 'shell', 'artifact-contract', 'openspec-validate', 'openspec-archive', 'approval', 'question', 'gate', 'map', 'join', 'component', 'implementation', 'implementation-step', 'end'];
 export type PieceKind = typeof PIECE_KINDS[number];
 export interface DefinitionNode {
     kind: PieceKind;