specrails-core 6.3.0 → 6.5.0

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

@@ -10,7 +10,7 @@ export declare function runtimeFailure(error: unknown): {
     };
 };
 /** 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;

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 }, 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,16 +1,29 @@
 import type { spawnSync } from 'node:child_process';
-interface EnvironmentInstall {
+/** `timeoutMs` overrides the default bound for one plan (a browser download is far larger than a dependency install). */
+export interface EnvironmentInstall {
     ecosystem: 'node' | 'python' | 'go' | 'rust';
     root: string;
     command: string;
     args: string[];
+    timeoutMs?: number;
+    installs?: string;
 }
 /** `precondition`: the install failed for a reason only the host can repair (see hostPreconditionFailure). */
-interface InstallOutcome extends EnvironmentInstall {
+export interface InstallOutcome extends EnvironmentInstall {
     ok: boolean;
     detail: string;
     precondition?: string;
 }
+export type HostPreconditionKind = 'network' | 'credential' | 'environment-variable' | 'toolchain' | 'setup' | 'environment';
+export interface HostPrecondition {
+    kind: HostPreconditionKind;
+    reason: string;
+    requiredAction: string;
+}
+/** True when a verification failure names a missing Playwright browser build. */
+export declare function isPlaywrightBrowserFailure(output: string): boolean;
+/** The browser the missing build path names (`chromium_headless_shell-1243` → `chromium`), undefined when none is parsable. */
+export declare function playwrightBrowser(output: string): 'chromium' | 'firefox' | 'webkit' | undefined;
 /** True when a verification failure looks like a missing toolchain/dependency rather than a code defect. */
 export declare function isEnvironmentFailure(exitCode: number | null | undefined, output: string): boolean;
 /**
@@ -23,6 +36,10 @@ export declare function isEnvironmentFailure(exitCode: number | null | undefined
  * again). Returns a short host-facing reason, or undefined.
  */
 export declare function hostPreconditionFailure(output: string): string | undefined;
+/** The blocker kind the matched precondition belongs to; undefined when the output is not a host precondition. */
+export declare function hostPreconditionKind(output: string): HostPreconditionKind | undefined;
+/** Classifies a host precondition with its kind, host-facing reason and the action that unblocks it. */
+export declare function hostPrecondition(output: string): HostPrecondition | undefined;
 /** Packages a failure output names explicitly (`Try \`npm i --save-dev @types/jest\``); the host installs exactly those. */
 export declare function suggestedPackages(output: string): string[];
 /** Dependencies package.json declares that node_modules does not hold (bounded). */
@@ -30,7 +47,7 @@ export declare function missingNodeDependencies(root: string): 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;
@@ -41,7 +58,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,10 +1,32 @@
 import crossSpawn from 'cross-spawn';
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import path from 'node:path';
 // 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.
 const defaultSpawn = crossSpawn.sync;
+// A Playwright test run on a host whose browser cache was never populated (a
+// fresh machine, a new Playwright version): the package is installed, the
+// browser build it pins is not. `playwright install` is the documented fix.
+const PLAYWRIGHT_SIGNATURES = [
+    /browserType\.launch: Executable doesn't exist at/i,
+    /Looks like Playwright was just installed or updated/i,
+    /ms-playwright[\\/](?:chromium|firefox|webkit|chromium_headless_shell)[-_]\d+/i,
+];
+/** True when a verification failure names a missing Playwright browser build. */
+export function isPlaywrightBrowserFailure(output) {
+    const tail = output.slice(-6000);
+    return PLAYWRIGHT_SIGNATURES.some(pattern => pattern.test(tail));
+}
+/** The browser the missing build path names (`chromium_headless_shell-1243` → `chromium`), undefined when none is parsable. */
+export function playwrightBrowser(output) {
+    const match = /ms-playwright[\\/](chromium|firefox|webkit|chromium_headless_shell)[-_]\d+/i.exec(output.slice(-6000));
+    if (!match)
+        return undefined;
+    const name = match[1].toLowerCase();
+    return name === 'chromium_headless_shell' ? 'chromium' : name;
+}
 const ENVIRONMENT_SIGNATURES = [
     /command not found/i,
     /is not recognized as an internal or external command/i,
@@ -21,6 +43,7 @@ const ENVIRONMENT_SIGNATURES = [
     /Module (?:[\w@./-]+) in the \w+ option was not found|Preset [\w@./-]+ not found|Cannot find module '(?:ts-jest|babel-jest|@swc\/jest|ts-node|tsx)'/i,
     // Yarn Berry refuses to run scripts in a checkout that was never installed.
     /doesn't seem to have been installed - running an install there might help|Couldn't find the node_modules state file - running an install might help/i,
+    ...PLAYWRIGHT_SIGNATURES,
 ];
 /** True when a verification failure looks like a missing toolchain/dependency rather than a code defect. */
 export function isEnvironmentFailure(exitCode, output) {
@@ -40,20 +63,39 @@ const REGISTRY = String.raw `(?:registry|npmjs\.org|yarnpkg\.com|npm\.pkg\.githu
  * again). Returns a short host-facing reason, or undefined.
  */
 export function hostPreconditionFailure(output) {
+    return hostPrecondition(output)?.reason;
+}
+/** The blocker kind the matched precondition belongs to; undefined when the output is not a host precondition. */
+export function hostPreconditionKind(output) {
+    return hostPrecondition(output)?.kind;
+}
+const PLAYWRIGHT_CDN = String.raw `(?:cdn\.playwright\.dev|playwright\.azureedge\.net|playwright-akamai\.azureedge\.net|playwright-verizon\.azureedge\.net)`;
+/** Classifies a host precondition with its kind, host-facing reason and the action that unblocks it. */
+export function hostPrecondition(output) {
     const text = output.replace(/\u001b\[[0-9;?]*[A-Za-z]/g, '').slice(-16_000);
     const variable = /Environment variable not found \(([A-Za-z_][A-Za-z0-9_]*)\)/.exec(text);
     if (variable)
-        return `the environment variable ${variable[1]} is not available to verification commands, and a package-manager configuration file requires it`;
+        return { kind: 'environment-variable', reason: `the environment variable ${variable[1]} is not available to verification commands, and a package-manager configuration file requires it`,
+            requiredAction: `Make ${variable[1]} available to Specrails (for example in the login shell profile it loads), then retry the run.` };
     if (/\bYN0041\b/.test(text) || /YN0035[\s\S]{0,400}?Response Code: 40[13]\b/.test(text) || /Response code 40[13] \((?:Unauthorized|Forbidden)\)/i.test(text)
         || /npm (?:ERR!|error) code (?:E401|E403|ENEEDAUTH)\b/.test(text) || /ERR_PNPM_FETCH_40[13]\b/.test(text)
         || new RegExp(String.raw `\b40[13] (?:Unauthorized|Forbidden)\b[^\n]{0,80}https?://[^\s]*${REGISTRY}`, 'i').test(text)
         || /\b(?:401|403) Client Error: (?:Unauthorized|Forbidden) for url/.test(text))
-        return 'the package registry rejected the credentials available to verification commands (HTTP 401/403)';
+        return { kind: 'credential', reason: 'the package registry rejected the credentials available to verification commands (HTTP 401/403)',
+            requiredAction: 'Refresh the registry credentials Specrails can use (for example a new token in the login shell profile it loads), then retry the run.' };
+    // The browser download is checked before registry reachability: its CDN is
+    // not a package registry, and the fix is a different command.
+    if (/Failed to download (?:Chrome for Testing|Chromium|Firefox|WebKit|chromium|firefox|webkit|FFMPEG|ffmpeg)\b/i.test(text)
+        || new RegExp(String.raw `Error: (?:getaddrinfo ENOTFOUND|connect ETIMEDOUT|connect ECONNREFUSED|ECONNRESET|ETIMEDOUT)[^\n]{0,300}${PLAYWRIGHT_CDN}`, 'i').test(text))
+        return { kind: 'network', reason: 'the Playwright browser download cannot reach its CDN from the verification environment',
+            requiredAction: 'Download the Playwright browsers with network access (`npx playwright install`), then retry the run.' };
     if (/npm (?:ERR!|error) code (?:ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ETIMEDOUT|ECONNRESET)\b/.test(text) || /ERR_PNPM_META_FETCH_FAIL\b/.test(text)
         || new RegExp(String.raw `\b(?:ENOTFOUND|EAI_AGAIN)\b[^\n]{0,200}${REGISTRY}|${REGISTRY}[^\n]{0,200}\b(?:ENOTFOUND|EAI_AGAIN)\b`, 'i').test(text))
-        return 'the package registry cannot be reached from the verification environment';
+        return { kind: 'network', reason: 'the package registry cannot be reached from the verification environment',
+            requiredAction: 'Give the verification environment network access to the package registry, then retry the run.' };
     if (/fatal: could not read (?:Username|Password) for/.test(text) || /Permission denied \(publickey\)/.test(text))
-        return 'git credentials needed to fetch a dependency are not available to verification commands';
+        return { kind: 'credential', reason: 'git credentials needed to fetch a dependency are not available to verification commands',
+            requiredAction: 'Make the git credentials that fetch the dependency (an SSH key or credential helper) available to Specrails, then retry the run.' };
     return undefined;
 }
 /** Packages a failure output names explicitly (`Try \`npm i --save-dev @types/jest\``); the host installs exactly those. */
@@ -91,6 +133,22 @@ export function missingNodeDependencies(root) {
     }
     return [...declared].filter(name => !existsSync(path.join(root, 'node_modules', name))).slice(0, 20);
 }
+/** 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. */
+function declaresPlaywright(root) {
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    return ['dependencies', 'devDependencies', 'optionalDependencies'].some(field => {
+        const block = manifest[field];
+        return !!block && typeof block === 'object' && ['@playwright/test', 'playwright'].some(name => Object.hasOwn(block, name));
+    });
+}
 /** The installs a repository root needs, judged from its manifests and the absence of their install output. */
 export function plannedInstalls(root, failureOutput = '') {
     const plans = [];
@@ -107,6 +165,14 @@ export function plannedInstalls(root, failureOutput = '') {
         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'] });
     }
+    // After the dependency plan: a fresh worktree needs node_modules before
+    // `playwright install` can run at all.
+    if (isPlaywrightBrowserFailure(failureOutput) && declaresPlaywright(root)) {
+        const runner = has('pnpm-lock.yaml') ? 'pnpm' : has('yarn.lock') ? 'yarn' : 'npx';
+        const browser = playwrightBrowser(failureOutput);
+        plans.push({ ecosystem: 'node', root, command: runner, args: [...(runner === 'pnpm' ? ['exec'] : []), 'playwright', 'install', ...(browser ? [browser] : [])],
+            timeoutMs: PLAYWRIGHT_INSTALL_TIMEOUT_MS, installs: `Playwright ${browser ?? 'browsers'}` });
+    }
     if ((has('requirements.txt') || has('pyproject.toml')) && !has('.venv') && !has('venv')) {
         const python = process.platform === 'win32' ? 'python' : 'python3';
         plans.push({ ecosystem: 'python', root, command: python, args: has('requirements.txt') ? ['-m', 'pip', 'install', '-q', '-r', 'requirements.txt'] : ['-m', 'pip', 'install', '-q', '-e', '.'] });
@@ -143,16 +209,15 @@ 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 {
-                    return spawn(plan.command, plan.args, { cwd: root, encoding: 'utf8', timeout: io.timeoutMs ?? 5 * 60_000, windowsHide: true, env: process.env });
+                    return spawn(plan.command, plan.args, { cwd: root, encoding: 'utf8', timeout: plan.timeoutMs ?? io.timeoutMs ?? 5 * 60_000, windowsHide: true, env: process.env });
                 }
                 catch (error) {
                     return { status: null, error: error, stdout: '', stderr: '', pid: 0, output: [], signal: null };
@@ -180,9 +245,24 @@ 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.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.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}` });
             const precondition = ok ? undefined : hostPreconditionFailure(`${result.stdout ?? ''}\n${result.stderr ?? ''}`);
             outcomes.push({ ...plan, ok, detail, ...(precondition ? { precondition } : {}) });
@@ -190,6 +270,109 @@ export function installEnvironment(roots, io = {}) {
     }
     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));