ravensight-playtest 0.3.2 → 0.4.0

package/README.md

@@ -4,6 +4,11 @@ AI personas play your game, then file a report you can read, mark up and argue
 with. The personas run on your machine, against your build; Ravensight stores
 the reports and renders them.
 
+Simulation Runner adds seeded headless batches for mechanics, economy and
+progression checks through your own game adapter. It runs locally without
+model calls and saves bounded results to the same Playtest workspace. See
+[Simulation Runner](docs/SIMULATION.md) for the held candidate and setup.
+
 You need a Ravensight account and Node 22 or newer. You do not need an
 Anthropic API key: model calls go through Ravensight under the same token you
 log in with, so there is one credential on your machine and you can revoke it
@@ -884,3 +889,17 @@ feedback and timing-sensitive gameplay.
 ## Build adapters
 
 Browser and Godot runners share the paid playtest lifecycle with desktop, Unity/Unreal export, Android/iOS and custom JSON-RPC adapters. Native adapters require a locally configured automation server and remain experimental until validated against your build. See [adapter setup and validation boundaries](docs/ADAPTERS.md) and the [native runner starter](docs/NATIVE_RUNNER.md); `check` probes the automation server for free before a paid native run.
+
+## Simulation Runner
+
+Available in held local candidate `0.4.0`; not yet published. Simulation Runner requires macOS or Linux (including WSL); native Windows is refused before purchase.
+
+Run seeded mechanics tests through a local game adapter, compare explicit strategies and replay selected traces. A batch uses the existing standard Playtest purchase of 5 AI units from prepaid balance, confirmed against the server quote. Only the summary is uploaded; game execution and replay traces stay local. It does not automatically call a model or replace testing the player interface.
+
+```sh
+ravensight-playtest simulate --config simulation.json --driver-config bridge.json
+ravensight-playtest simulate --resume .ravensight/simulations/BATCH_ID/state.json
+ravensight-playtest simulation-replay trace-00000.json --driver-config bridge.json
+```
+
+See [Simulation Runner setup, adapter protocol and limits](docs/SIMULATION.md). The package includes `examples/simulation/economy.mjs` as a deterministic starting adapter. Local replay creates no new paid job.

package/docs/SIMULATION.md

@@ -0,0 +1,91 @@
+# Simulation Runner
+
+Held local candidate: `0.4.0`. This package has not been published; use a reviewed local tarball with the matching held server implementation.
+
+Simulation Runner exercises game mechanics through a developer-owned local adapter. It can run seeded games across explicit strategies, summarize outcomes and metrics, and save selected replay traces. Use it for questions such as whether an economy supports several viable strategies or whether a progression rule traps a simulated player. It does not judge animation, interface usability, feel or subjective fun.
+
+A batch uses the existing standard Playtest purchase: **5 AI units from prepaid balance**. The CLI obtains the current server quote and asks for confirmation before registration. One batch is one purchase, not one purchase per simulated game. It does not consume the monthly shared AI allowance. Local replay is a debugging operation with no new job or purchase. Automatic AI interpretation is not included; an agent can use the existing report tools when explicitly asked to interpret the summary.
+
+## Setup and run
+
+Run Simulation Runner on macOS or Linux, including WSL. Native Windows is rejected during preflight before quoting or registering a purchase because this feature requires POSIX process-group cleanup. This restriction applies to Simulation Runner, not every Playtest adapter. The recorded real-process and 10,000-game validation was run on macOS; native Windows and WSL execution were not validated in this review.
+
+Sign in and initialize your Ravensight project as usual. Implement the protocol below, or start with the packaged `examples/simulation/economy.mjs`. The example is deterministic and contains no networking or telemetry.
+
+Create `bridge.json` with absolute paths for the Node executable and adapter:
+
+```json
+{
+  "command": "/absolute/path/to/node",
+  "args": ["/absolute/path/to/economy.mjs"],
+  "cwd": "/absolute/path/to/game"
+}
+```
+
+The adapter is trusted local code, **not a sandbox**. No shell is used to spawn it. Account/provider credential environment variables are stripped. Paid execution injects a synthetic Playtest token and run/job IDs; preflight and replay inject an invalid token sentinel so an inherited token cannot accidentally mark the session as production.
+
+Create `simulation.json`:
+
+```json
+{
+  "version": 1,
+  "seed": "economy-review-1",
+  "runs": 100,
+  "max_steps": 12,
+  "workers": 4,
+  "strategies": [
+    { "name": "random", "policy": "random" },
+    { "name": "collector", "policy": "scored" },
+    { "name": "saver", "policy": "scripted", "actions": ["earn", "earn", "earn", "earn", "earn", "earn", "earn", "earn"] }
+  ]
+}
+```
+
+```sh
+ravensight-playtest simulate --config simulation.json --driver-config bridge.json
+```
+
+A `driver_config` path inside the simulation file may replace `--driver-config`. The CLI probes the adapter before purchasing. A probe only starts a game and validates its first observation; it does not run the batch. Keep adapter initialization free of destructive side effects.
+
+Strategy names start with a lowercase letter and contain at most 64 lowercase letters, digits, underscores or hyphens. Strategies are assigned round-robin. Each run receives a seed derived from the root seed and its zero-based run index. Worker count changes concurrency, not action selection. `random` chooses among legal action IDs deterministically. `scripted` follows supplied IDs and fails on an illegal action or exhaustion before a terminal state. `scored` chooses the highest score supplied by the game for that strategy name, with a deterministic action-ID tie break. Names such as "aggressive" have no built-in gameplay meaning.
+
+## Adapter protocol
+
+Use one JSON-RPC 2.0 JSON object per line on stdout. Send diagnostics to stderr. The runner starts a fresh subprocess for each game, with one request outstanding at a time.
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"simulation.start","params":{"version":1,"seed":"derived-seed","strategy":"collector","max_steps":12}}
+{"jsonrpc":"2.0","id":1,"result":{"done":false,"state_hash":"state-0","actions":[{"id":"earn","scores":{"collector":1}},{"id":"buy","scores":{"collector":3}}],"metrics":{"coins":4}}}
+{"jsonrpc":"2.0","id":2,"method":"simulation.step","params":{"action":"buy"}}
+{"jsonrpc":"2.0","id":2,"result":{"done":true,"state_hash":"state-1","actions":[],"metrics":{"coins":2,"inventory":1},"outcome":"collected"}}
+```
+
+The game owns state hashing and must include every state component relevant to reproducibility. Return `done` as a boolean, a nonempty `state_hash` of at most 128 characters, and at most 256 unique action IDs of at most 128 characters. Nonterminal observations need legal actions. Optional action scores contain at most 16 finite numeric values keyed by strategy. Optional metrics contain at most 32 finite numeric values between -1e15 and 1e15 with keys of at most 80 characters. Optional outcomes are nonempty strings of at most 80 characters. Reserved names `__proto__`, `constructor` and `prototype` are rejected.
+
+## Limits and results
+
+- 1 to 10,000 requested games, 1 to 10,000 actions per game, 1 to 16 workers and 1 to 16 strategies.
+- At most 1,000,000 actions across a batch and at most 15 minutes of execution, subject to the registered server budget.
+- At most 30 seconds per response and 256 KiB per response. Cancellation terminates the subprocess group, escalating from SIGTERM to SIGKILL.
+- At most ten selected traces: the first ten run indices, not an exhaustive failure archive. Each trace is bounded to 4 MiB and 10,000 actions.
+- Per-strategy summaries retain at most 32 distinct metric names and 128 outcome buckets. Additional outcome names are grouped as `other`; keep metric names stable between games.
+
+`duration_ms` reports execution time within the batch deadline, excluding any cleanup or post-stop serialization beyond that deadline. `results.jsonl` streams one local result per requested run. `summary.json` contains completed, failed and truncated totals, total actions, terminal outcome counts and terminal metric count/min/max/mean by strategy. Metrics are run-level terminal values, not a mean across every observation. A terminal result without an outcome uses `unspecified`. Reaching `max_steps` is **truncated**, never a successful terminal outcome. Games not started because of cancellation or a batch limit count as failed, with the stop reason retained in the local report.
+
+Only the bounded summary is uploaded to the existing Playtest job. Adapter scripts, raw states, per-game rows, replay traces and scripted action lists remain local. The public configuration hash covers the registered configuration and strategy names/policies; trace metadata also includes a separate full local configuration hash covering scripts.
+
+## Recovery and replay
+
+The CLI prints a durable recovery journal path. Recover the same purchase rather than starting another batch:
+
+```sh
+ravensight-playtest simulate --resume .ravensight/simulations/BATCH_ID/state.json
+```
+
+Resume preserves the API host, game, configuration and purchase identity. Do not combine it with a new config or bridge argument. A changed bridge configuration is rejected. Keep the adapter build and its dependencies unchanged for reproducible recovery. After a process interruption, any restarted local attempt has its own output directory. If the summary was already saved, resume uploads that summary without executing the games again. A terminal server job is not restarted.
+
+```sh
+ravensight-playtest simulation-replay /absolute/path/to/trace-00000.json --driver-config bridge.json
+```
+
+Replay checks each recorded state hash, terminal flag, outcome and metrics and reports the first divergence. A matching replay verifies that recording with the current adapter; it does not prove the game is deterministic. External services, clocks, platform differences and ignored seeds can cause divergence. A trace from a max-step-truncated game only covers the recorded window, not a finished game. Size-capped or failed recordings can verify their captured prefix, reported as `matched_prefix: true` and `fully_replayed: false`. A recorded failed protocol action is retried after that prefix; `failure_reproduced` states whether the same sanitized protocol error recurred. A failed initial start has no state prefix to verify. Policy failures such as an exhausted script only support prefix replay, not recreation of the policy failure. These results never claim a fully reproduced terminal game.

package/examples/simulation/economy.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Trusted local adapter example. It has no networking or telemetry.
+import readline from 'node:readline';
+import { createHash } from 'node:crypto';
+let seed, turn, coins, inventory;
+function observe() {
+  const done = turn >= 8;
+  return { done, state_hash: createHash('sha256').update(JSON.stringify([seed, turn, coins, inventory])).digest('hex'),
+    actions: done ? [] : [{ id: 'earn', scores: { saver: 2, collector: 1 } }, ...(coins >= 2 ? [{ id: 'buy', scores: { saver: 0, collector: 3 } }] : [])],
+    metrics: { coins, inventory }, ...(done ? { outcome: inventory >= 2 ? 'collected' : 'saved' } : {}) };
+}
+for await (const line of readline.createInterface({ input: process.stdin })) {
+  let request;
+  try {
+    request = JSON.parse(line);
+    if (request.method === 'simulation.start') { seed = request.params.seed; turn = 0; inventory = 0; coins = parseInt(createHash('sha256').update(seed).digest('hex').slice(0, 4), 16) % 3; }
+    else if (request.method === 'simulation.step' && !observe().done && observe().actions.some(a => a.id === request.params.action)) {
+      turn++; if (request.params.action === 'earn') coins++; else { coins -= 2; inventory++; }
+    } else throw new Error('Illegal simulation request');
+    process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: request.id, result: observe() }) + '\n');
+  } catch { process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: request?.id, error: { code: -32602, message: 'Invalid request' } }) + '\n'); }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ravensight-playtest",
-  "version": "0.3.2",
-  "description": "AI personas play your game and file reports to Ravensight.",
+  "version": "0.4.0",
+  "description": "Local AI playtests and seeded game simulations with reports in Ravensight.",
   "license": "MIT",
   "homepage": "https://ravensight.io/docs/#playtest",
   "bugs": {
@@ -12,6 +12,8 @@
     "playtest",
     "game-analytics",
     "ai-personas",
+    "simulation",
+    "game-balance",
     "ravensight"
   ],
   "type": "module",
@@ -27,6 +29,8 @@
     "addons",
     "docs/ADAPTERS.md",
     "docs/NATIVE_RUNNER.md",
+    "docs/SIMULATION.md",
+    "examples/simulation",
     "README.md",
     "LICENSE",
     "!src/**/*.test.js",

package/src/api/client.js

@@ -194,9 +194,9 @@ export function createClient(options = {}) {
      * persona run's price; anything else leaves `run_length` out, which the
      * server reads as a standard run.
      */
-    estimate: (gameId, { modules = [], personas = [], runLength = null } = {}) =>
+    estimate: (gameId, { modules = [], personas = [], runLength = null, simulation } = {}) =>
       request('POST', `${gameBase(gameId)}/estimate`, {
-        body: { modules, personas, ...(runLength === 'long' ? { run_length: 'long' } : {}) }
+        body: { modules, personas, ...(runLength === 'long' ? { run_length: 'long' } : {}), ...(simulation ? { simulation } : {}) }
       }).then(answer => answer.body),
 
     /**

package/src/cli.js

@@ -316,6 +316,24 @@ export function buildProgram() {
       return run(flagsFrom(options, { game: options.game, argv: command.args }));
     }));
 
+  common(program.command('simulate').description('run a paid, seeded batch against a local headless game'))
+    .option('--game <gameId>', 'the game, when this repo is not linked')
+    .option('--config <file>', 'simulation JSON: seed, runs, max_steps, workers and strategies')
+    .option('--driver-config <file>', 'local JSON-RPC executable configuration')
+    .option('--resume <file>', 'resume the same paid batch from its state.json, without another charge')
+    .action(capture(slot, async options => {
+      const { simulateCommand } = await import('./commands/simulate.js');
+      return simulateCommand(flagsFrom(options, { game: options.game, configFile: options.config, driverConfig: options.driverConfig, resume: options.resume }));
+    }));
+
+  common(program.command('simulation-replay').description('verify a recorded simulation trace locally; creates no paid job'))
+    .argument('<trace>', 'a selected trace.json written by simulate')
+    .requiredOption('--driver-config <file>', 'local JSON-RPC executable configuration')
+    .action(capture(slot, async (trace, options) => {
+      const { replayCommand } = await import('./commands/simulate.js');
+      return replayCommand(trace, flagsFrom(options, { driverConfig: options.driverConfig }));
+    }));
+
   return program;
 }
 

package/src/commands/simulate.js

@@ -0,0 +1,298 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createContext, resolveGameId, CLI_VERSION, ui } from '../api/index.js';
+import { createHeartbeat } from '../run/heartbeat.js';
+import { readBridgeConfig } from '../run/drivers/stdio.js';
+import { runBatch, replayTrace, validateConfig, probeBridge } from '../simulation/index.js';
+import { jobLink } from '../dashboard.js';
+import { CliError } from '../errors.js';
+import EXIT from '../run/exit.js';
+
+const MODULES = ['balance_sim', 'aggregate_report'];
+const TERMINAL = new Set(['succeeded', 'failed', 'canceled', 'budget_exceeded', 'skipped', 'stalled']);
+const money = cents => `$${(cents / 100).toFixed(2)}`;
+const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+async function loadBridge(file) {
+  const bridge = await readBridgeConfig(file);
+  return { ...bridge, cwd: bridge.cwd || path.dirname(file) };
+}
+
+export function publicConfig(config) {
+  return { version: config.version, seed: config.seed, runs: config.runs, max_steps: config.max_steps,
+    workers: config.workers, strategies: config.strategies.map(({ name, policy }) => ({ name, policy })) };
+}
+
+async function jsonFile(file, maxBytes = 64000) {
+  if ((await stat(file)).size > maxBytes) throw new CliError(`File exceeds ${maxBytes} bytes: ${file}`);
+  return JSON.parse(await readFile(file, 'utf8'));
+}
+
+async function save(file, value) {
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+    await rename(temporary, file);
+  } finally { await unlink(temporary).catch(() => {}); }
+}
+
+// Exclusive per-journal execution. A dead process's lock is recoverable; a live
+// process cannot have its paid run restarted underneath it by another shell.
+async function acquire(file) {
+  const lock = `${file}.lock`;
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const handle = await open(lock, 'wx', 0o600);
+      await handle.writeFile(String(process.pid));
+      await handle.close();
+      return () => unlink(lock).catch(() => {});
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const pid = Number(await readFile(lock, 'utf8'));
+      if (!Number.isInteger(pid) || pid < 1) throw new CliError(`Unreadable simulation lock: ${lock}`);
+      try { process.kill(pid, 0); }
+      catch (probe) {
+        if (probe.code === 'ESRCH' && attempt === 0) { await unlink(lock); continue; }
+      }
+      throw new CliError('This simulation journal is already in use. Wait for the other runner to stop.');
+    }
+  }
+}
+
+function assertQuote(quote) {
+  if (quote?.execution_mode !== 'direct_command_batch' || !quote.simulation_limits ||
+      !Number.isSafeInteger(quote.estimate_cents) || quote.estimate_cents <= 0 ||
+      quote.breakdown?.length !== 1 || quote.breakdown[0].unit !== 'playtest_run' ||
+      quote.breakdown[0].count !== 1 || quote.breakdown[0].unit_cents !== quote.estimate_cents) {
+    throw new CliError('This server did not quote a paid Simulation Runner batch. Nothing was registered or charged. Update the server and CLI together.');
+  }
+}
+
+/** One confirmed purchase, a local batch, then bounded evidence to the same job. */
+export async function simulateCommand(flags = {}, injected = {}) {
+  const output = injected.ui || ui;
+  const repoRoot = path.resolve(flags.repoRoot || process.cwd());
+  let journal, file;
+  if (flags.resume) {
+    if (flags.configFile || flags.driverConfig) throw new CliError('Resume uses the original config and bridge. Do not combine --resume with --config or --driver-config.');
+    file = path.resolve(repoRoot, flags.resume);
+    journal = await jsonFile(file, 2 * 1024 * 1024);
+    if (journal.version !== 1 || journal.kind !== 'simulation' || !journal.idempotency_key ||
+        !journal.game_id || !journal.api_url || !journal.config || !journal.registration) {
+      throw new CliError('This is not a Simulation Runner journal.');
+    }
+    if (flags.game && flags.game !== journal.game_id) throw new CliError('Resume must use the original game.');
+    if (flags.apiUrl && flags.apiUrl.replace(/\/+$/, '') !== journal.api_url) throw new CliError('Resume must use the original API host.');
+  } else {
+    if (!flags.configFile) throw new CliError('Supply --config simulation.json, or --resume <state.json>.');
+    const configFile = path.resolve(repoRoot, flags.configFile);
+    const { driver_config: configDriver, ...raw } = await jsonFile(configFile);
+    const config = validateConfig(raw);
+    const driverFile = flags.driverConfig ? path.resolve(repoRoot, flags.driverConfig)
+      : typeof configDriver === 'string' ? path.resolve(path.dirname(configFile), configDriver) : null;
+    if (!driverFile) throw new CliError('Supply --driver-config bridge.json or driver_config in the simulation config.');
+    const bridge = await loadBridge(driverFile);
+    journal = { version: 1, kind: 'simulation', idempotency_key: randomUUID(), config,
+      bridge_file: driverFile, bridge_hash: hash(bridge), created_at: new Date().toISOString(), finished: false };
+    file = path.join(repoRoot, '.ravensight', 'simulations', journal.idempotency_key, 'state.json');
+  }
+  validateConfig(journal.config);
+  const context = await (injected.createContext || createContext)({ apiUrl: journal.api_url || flags.apiUrl, repoRoot, requireAuth: true });
+  if (journal.api_url && context.apiUrl.replace(/\/+$/, '') !== journal.api_url) throw new CliError('The API host changed. Resume was refused.');
+  const api = context.api;
+  const gameId = journal.game_id || resolveGameId(flags, context.config);
+  const release = await acquire(file);
+  const controller = new AbortController();
+  const target = injected.process || process;
+  const stop = () => controller.abort(new Error('Simulation canceled.'));
+  target.once('SIGINT', stop);
+  target.once('SIGTERM', stop);
+  let heartbeat;
+  const persist = () => save(file, journal);
+  const settledExit = state => journal.canceled || state === 'canceled' ? EXIT.CANCELED
+    : state !== 'succeeded' || (journal.summary && (!journal.summary.completed_runs || journal.summary.failed_runs || journal.summary.truncated_runs)) ? EXIT.FAILED : EXIT.OK;
+  const recover = () => output.error(`Recover this same purchase with: ravensight-playtest simulate --resume ${JSON.stringify(file)}`);
+  try {
+    if (journal.finished) {
+      if (flags.json) output.json({ job_id: journal.job_id, finished: true, summary: journal.summary });
+      else output.info(`This batch is already finished: ${jobLink(gameId, journal.job_id, context.apiUrl)}`);
+      return journal.exit_code ?? EXIT.OK;
+    }
+    if (journal.job_id) {
+      const { job } = await api.jobs.get(gameId, journal.job_id);
+      if (TERMINAL.has(job.state)) {
+        journal.finished = true;
+        journal.exit_code = settledExit(job.state);
+        await persist();
+        if (flags.json) output.json({ job_id: journal.job_id, finished: true, state: job.state });
+        else output.info(`The server already settled this batch as ${job.state}. No simulation was restarted.`);
+        return journal.exit_code;
+      }
+      // A completed run can await job settlement after an interrupted finish.
+      // Neither adapter files nor local execution are needed to settle it.
+      if (!journal.summary && journal.run_id) {
+        const { run: existing } = await api.runs.get(gameId, journal.job_id, journal.run_id);
+        if (TERMINAL.has(existing.state)) {
+          await api.jobs.finish(gameId, journal.job_id, {});
+          journal.finished = true; journal.exit_code = settledExit(existing.state); await persist();
+          if (flags.json) output.json({ job_id: journal.job_id, finished: true, state: existing.state });
+          else output.info(`This run already finished as ${existing.state}; its job is now settled.`);
+          return journal.exit_code;
+        }
+      }
+      if (job.cancel_requested) controller.abort(new Error('Simulation canceled on the server.'));
+    }
+    let bridge;
+    if (!journal.summary) {
+      bridge = await loadBridge(journal.bridge_file);
+      if (hash(bridge) !== journal.bridge_hash) throw new CliError('The bridge configuration changed. Restore it before resuming this purchase.');
+      if (!controller.signal.aborted) await (injected.probeBridge || probeBridge)({ bridge, seed: journal.config.seed,
+        strategy: journal.config.strategies[0].name, max_steps: journal.config.max_steps, signal: controller.signal });
+    }
+    if (!journal.registration) {
+      const simulation = publicConfig(journal.config);
+      const quote = await api.jobs.estimate(gameId, { modules: MODULES, personas: [], simulation });
+      assertQuote(quote);
+      output.info(`One simulation batch: ${journal.config.runs} games across ${journal.config.strategies.length} strategies, ${money(quote.estimate_cents)} total from prepaid balance.`);
+      output.info('Game execution and replay traces stay local. Only the bounded summary is uploaded. This is a mechanics test, not a test of the player interface.');
+      if (quote.ok === false) throw new CliError(`Insufficient prepaid balance (${money(quote.balance_cents)}). Nothing was charged.`, EXIT.ENVIRONMENT);
+      if (!flags.yes && !await (injected.confirm || output.confirm)(`Start this batch for ${money(quote.estimate_cents)}?`)) return EXIT.CANCELED;
+      if (controller.signal.aborted) return EXIT.CANCELED;
+      journal.api_url = context.apiUrl.replace(/\/+$/, '');
+      journal.game_id = gameId;
+      journal.limits = quote.simulation_limits;
+      journal.registration = { modules: MODULES, personas: [], driver: 'cli_stdio', simulation,
+        cli_version: CLI_VERSION, confirm_price_cents: quote.estimate_cents,
+        build: { kind: 'simulation', ref: hash(simulation) } };
+      // Durable BEFORE the money request. A lost register response replays the
+      // same idempotency key, even when no job_id ever reached this machine.
+      await persist();
+      output.info(`Recovery journal: ${file}`);
+    }
+
+    let registered;
+    try { registered = await api.jobs.register(gameId, journal.registration, { idempotencyKey: journal.idempotency_key }); }
+    catch (error) { recover(); throw error; }
+    journal.job_id = registered.job_id;
+    const run = registered.runs?.find(entry => entry.module === 'balance_sim');
+    if (!run || !run.playtest_token) {
+      await api.jobs.finish(gameId, journal.job_id, { state: 'failed', reason: 'Simulation run or synthetic token missing.' });
+      throw new CliError('The server did not create an executable simulation run. The job was stopped.');
+    }
+    journal.run_id = run.run_id;
+    await persist();
+    let current = flags.resume ? (await api.runs.get(gameId, journal.job_id, run.run_id)).run : run;
+    if (TERMINAL.has(current.state)) {
+      await api.jobs.finish(gameId, journal.job_id, {});
+      journal.finished = true;
+      journal.exit_code = settledExit(current.state);
+      await persist();
+      if (flags.json) output.json({ job_id: journal.job_id, finished: true, state: current.state });
+      else output.info(`This run already finished as ${current.state}; its job is now settled.`);
+      return journal.exit_code;
+    }
+    const transition = async state => {
+      if (current.state !== state) {
+        await api.runs.transition(gameId, journal.job_id, run.run_id, state);
+        current = { ...current, state };
+      }
+    };
+    heartbeat = (injected.createHeartbeat || createHeartbeat)({ api, gameId, jobId: journal.job_id, runId: run.run_id,
+      onCancel: stop, onError: error => {
+        if ([401, 403, 404, 409].includes(error.status)) controller.abort(new Error('The server closed this run.'));
+      } });
+    heartbeat.start();
+    await heartbeat.beat();
+    if (!journal.summary) {
+      if (['reporting', 'uploading'].includes(current.state)) throw new CliError('The local simulation summary is missing. Restore the journal before finishing this paid run.');
+      if (['queued', undefined].includes(current.state)) await transition('launching');
+      await transition('playing');
+      try {
+        // A crash can leave an incomplete results.jsonl. Preserve it and use a
+        // new directory for the deterministic restart of the same paid run.
+        journal.attempt_directory = path.join(path.dirname(file), `attempt-${randomUUID()}`);
+        await persist();
+        const result = await (injected.runBatch || runBatch)({ config: journal.config,
+          bridge: { ...bridge, batchTimeoutMs: Math.min(900000, (run.limits?.wall_seconds || run.budget?.wall_seconds_max || journal.limits?.wall_seconds_max || 900) * 1000) },
+          outputDir: journal.attempt_directory,
+          playtest: { token: run.playtest_token, runId: run.run_id, jobId: journal.job_id }, signal: controller.signal,
+          onProgress: progress => {
+            if (progress.finished_runs % 100 === 0 || progress.finished_runs === progress.requested_runs) {
+              output.info(`${progress.finished_runs}/${progress.requested_runs} games processed; ${progress.completed_runs} completed, ${progress.failed_runs} failed, ${progress.truncated_runs} reached a limit.`);
+              void heartbeat.beat({ actionsTaken: progress.total_steps, checkpointStep: progress.finished_runs });
+            }
+          } });
+        journal.summary = result.summary;
+        journal.traces = result.traces;
+        journal.local_report = result.report;
+        journal.canceled = controller.signal.aborted;
+        await persist();
+      } catch (error) {
+        // No usable local result exists. Complete and settle through the same
+        // server refund path; neither a second charge nor a local refund.
+        try {
+          await api.runs.complete(gameId, journal.job_id, run.run_id, { state: 'failed', quit_reason: 'error', reason: 'Local simulation could not produce a summary.' });
+          await api.jobs.finish(gameId, journal.job_id, { reason: 'Local simulation failed.' });
+          journal.finished = true; journal.exit_code = EXIT.FAILED; await persist();
+        } catch { recover(); }
+        throw error;
+      }
+    }
+    const useful = journal.summary.completed_runs > 0;
+    try {
+      if (useful) {
+        if (current.state !== 'uploading') await transition('reporting');
+        await transition('uploading');
+      }
+      await api.runs.complete(gameId, journal.job_id, run.run_id, {
+        state: useful ? 'succeeded' : 'failed', simulation: journal.summary,
+        actions_taken: journal.summary.total_steps, quit_reason: useful ? 'goal_reached' : 'error'
+      });
+      await api.jobs.finish(gameId, journal.job_id, {});
+    } catch (error) {
+      // Keep valid results for retry. A dropped complete/finish response is
+      // ambiguous, so do not overwrite success with failed or buy another job.
+      recover();
+      throw error;
+    }
+    journal.finished = true;
+    journal.exit_code = journal.canceled ? EXIT.CANCELED :
+      (!useful || journal.summary.failed_runs || journal.summary.truncated_runs) ? EXIT.FAILED : EXIT.OK;
+    await persist();
+    if (flags.json) output.json({ job_id: journal.job_id, summary: journal.summary, traces: journal.traces, journal: file });
+    else {
+      output.info(`Simulation report: ${jobLink(gameId, journal.job_id, context.apiUrl)}`);
+      output.info(`Local summary and replay traces: ${path.dirname(file)}`);
+      if (!useful) output.info('No game reached a terminal result. The server settles this batch without keeping its Playtest unit.');
+    }
+    return journal.exit_code;
+  } finally {
+    heartbeat?.stop();
+    target.removeListener('SIGINT', stop);
+    target.removeListener('SIGTERM', stop);
+    await release();
+  }
+}
+
+export async function replayCommand(trace, flags = {}, injected = {}) {
+  const output = injected.ui || ui;
+  const repo = path.resolve(flags.repoRoot || process.cwd());
+  const bridge = await loadBridge(path.resolve(repo, flags.driverConfig));
+  const controller = new AbortController();
+  const stop = () => controller.abort(new Error('Replay canceled.'));
+  const target = injected.process || process;
+  target.once('SIGINT', stop); target.once('SIGTERM', stop);
+  try {
+    const result = await (injected.replayTrace || replayTrace)({ trace: path.resolve(repo, trace), bridge, signal: controller.signal });
+    if (flags.json) output.json(result);
+    else output.info(result.matched
+      ? result.fully_replayed === false
+        ? result.failure_reproduced ? 'Replay matched the recorded prefix and reproduced the recorded failure.'
+          : 'Replay matched the recorded prefix only. The trace does not establish a complete playthrough.'
+        : 'Replay matched every recorded state, outcome and metric.'
+      : `Replay diverged: ${JSON.stringify(result.first_divergence)}. Check the game seed, build and external dependencies.`);
+    return result.matched ? EXIT.OK : EXIT.FAILED;
+  } finally { target.removeListener('SIGINT', stop); target.removeListener('SIGTERM', stop); }
+}

package/src/simulation/index.js

@@ -0,0 +1,176 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { boundedString, bridgeOptions, observation, openBridge } from './protocol.js';
+const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const MAX_TRACE_BYTES = 4 * 1024 * 1024;
+const MAX_ACTIONS = 1000000;
+const compareText = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+export function validateConfig(input) {
+  if (!input || input.version !== 1 || !boundedString(input.seed, 128)) throw new Error('Simulation config needs version 1 and a seed of 1 to 128 characters.');
+  for (const [key, max] of [['runs', 10000], ['max_steps', 10000], ['workers', 16]]) if (!Number.isInteger(input[key]) || input[key] < 1 || input[key] > max) throw new Error(`Invalid simulation ${key}.`);
+  if (!Array.isArray(input.strategies) || !input.strategies.length || input.strategies.length > 16) throw new Error('Choose 1 to 16 simulation strategies.');
+  const strategies = input.strategies.map(strategy => {
+    if (!strategy || typeof strategy.name !== 'string' || !/^[a-z][a-z0-9_-]{0,63}$/.test(strategy.name) || !['random', 'scripted', 'scored'].includes(strategy.policy)) throw new Error('Invalid simulation strategy.');
+    if (strategy.policy === 'scripted' && (!Array.isArray(strategy.actions) || !strategy.actions.length || strategy.actions.length > 10000 || strategy.actions.some(id => !boundedString(id, 128)))) throw new Error('Scripted strategy needs 1 to 10000 action IDs.');
+    return { name: strategy.name, policy: strategy.policy, ...(strategy.policy === 'scripted' ? { actions: [...strategy.actions] } : {}) };
+  });
+  if (new Set(strategies.map(s => s.name)).size !== strategies.length) throw new Error('Strategy names must be unique.');
+  const config = { version: 1, seed: input.seed, runs: input.runs, max_steps: input.max_steps, workers: input.workers, strategies };
+  if (Buffer.byteLength(JSON.stringify(config)) > 2 * 1024 * 1024) throw new Error('Simulation configuration exceeds 2 MiB.');
+  return config;
+}
+export function configHash(config) { return hash({ version: 1, seed: config.seed, runs: config.runs, max_steps: config.max_steps, workers: config.workers, strategies: config.strategies.map(({ name, policy }) => ({ name, policy })) }); }
+export function deriveSeed(seed, index) { return hash([seed, index]); }
+function choose(state, strategy, index, seed) {
+  if (strategy.policy === 'scripted') {
+    const id = strategy.actions[index];
+    if (!id) throw new Error('Scripted strategy exhausted before terminal state.');
+    if (!state.actions.some(action => action.id === id)) throw new Error('Scripted strategy selected an illegal action.');
+    return id;
+  }
+  if (strategy.policy === 'scored') {
+    const choices = state.actions.filter(action => Number.isFinite(action.scores?.[strategy.name]));
+    if (!choices.length) throw new Error('Game supplied no scores for this strategy.');
+    return choices.sort((a, b) => b.scores[strategy.name] - a.scores[strategy.name] || compareText(a.id, b.id))[0].id;
+  }
+  const choices = [...state.actions].sort((a, b) => compareText(a.id, b.id));
+  return choices[parseInt(hash([seed, index]).slice(0, 12), 16) % choices.length].id;
+}
+function stateRecord(state) { return { done: state.done, state_hash: state.state_hash, ...(state.outcome === undefined ? {} : { outcome: state.outcome }), ...(state.metrics === undefined ? {} : { metrics: state.metrics }) }; }
+async function writeJson(file, value) { await fs.writeFile(file, JSON.stringify(value) + '\n', { flag: 'wx', mode: 0o600 }); }
+export async function probeBridge({ bridge, seed = 'preflight', strategy = 'random', max_steps = 1, signal }) {
+  if (!boundedString(seed, 128) || !boundedString(strategy, 80) || !Number.isInteger(max_steps) || max_steps < 1 || max_steps > 10000) throw new Error('Invalid simulation probe.');
+  const client = openBridge(bridge, { signal });
+  try { return await client.request('simulation.start', { version: 1, seed, strategy, max_steps }); }
+  finally { await client.stop(); }
+}
+export async function runBatch({ config: rawConfig, bridge: rawBridge, outputDir, playtest, signal, onProgress }) {
+  const config = validateConfig(rawConfig); const bridge = bridgeOptions(rawBridge);
+  if (typeof outputDir !== 'string' || !outputDir) throw new Error('Simulation output directory is required.');
+  outputDir = path.resolve(outputDir); await fs.mkdir(outputDir, { recursive: true });
+  const resultsPath = path.join(outputDir, 'results.jsonl'); const file = await fs.open(resultsPath, 'wx', 0o600);
+  const started = Date.now(); const controller = new AbortController(); let stopReason = null;
+  const cancel = () => { stopReason ||= 'cancelled'; controller.abort(); };
+  signal?.addEventListener('abort', cancel, { once: true }); if (signal?.aborted) cancel();
+  const timer = setTimeout(() => { stopReason ||= 'batch_deadline'; controller.abort(); }, bridge.batchTimeoutMs);
+  let next = 0, reservedSteps = 0, writeChain = Promise.resolve(), commitTail = Promise.resolve();
+  const traces = [];
+  const summary = { version: 1, seed: config.seed, config_hash: configHash(config), requested_runs: config.runs, completed_runs: 0, failed_runs: 0, truncated_runs: 0, total_steps: 0, strategies: config.strategies.map(s => ({ name: s.name, runs: 0, completed: 0, failed: 0, truncated: 0, outcomes: {}, metrics: {} })), trace_count: 0, duration_ms: 0 };
+  async function execute(index, priorCommit) {
+    const strategy = config.strategies[index % config.strategies.length]; const seed = deriveSeed(config.seed, index);
+    const row = { version: 1, run_index: index, seed, strategy: strategy.name, status: 'failed', steps: 0 };
+    const trace = index < 10 ? { version: 1, run_index: index, seed, strategy: strategy.name, max_steps: config.max_steps, local_config_hash: hash(config), states: [], actions: [] } : null;
+    let traceBytes = 1024, client, pendingAction, phase = 'start';
+    const record = state => {
+      if (!trace) return;
+      const item = stateRecord(state); traceBytes += Buffer.byteLength(JSON.stringify(item)) + 1;
+      if (traceBytes > MAX_TRACE_BYTES) { trace.truncated = true; return; }
+      trace.states.push(item);
+    };
+    try {
+      if (controller.signal.aborted) throw new Error('Simulation stopped before run started.');
+      client = openBridge(bridge, { signal: controller.signal, playtest });
+      let state = await client.request('simulation.start', { version: 1, seed, strategy: strategy.name, max_steps: config.max_steps }); record(state);
+      while (!state.done && row.steps < config.max_steps) {
+        if (reservedSteps >= MAX_ACTIONS) { stopReason ||= 'action_budget'; controller.abort(); throw new Error('Batch action budget exhausted.'); }
+        phase = 'policy';
+        const action = choose(state, strategy, row.steps, seed); reservedSteps++;
+        pendingAction = action; phase = 'step';
+        state = await client.request('simulation.step', { action }); pendingAction = undefined; row.steps++; summary.total_steps++;
+        if (trace && !trace.truncated) { trace.actions.push(action); traceBytes += Buffer.byteLength(JSON.stringify(action)) + 1; }
+        record(state);
+      }
+      row.status = state.done ? 'completed' : 'truncated';
+      if (state.done) { row.outcome = state.outcome || 'unspecified'; row.metrics = state.metrics || {}; }
+    } catch (error) { row.error = error.message.slice(0, 200); if (trace) { trace.failure_phase = phase; if (pendingAction) trace.failed_action = pendingAction; } }
+    finally { if (client) await client.stop(); }
+    // Commit in run-index order, retaining at most one result per worker. This
+    // makes floating-point aggregate order independent of process scheduling.
+    await priorCommit;
+    const aggregate = summary.strategies[index % config.strategies.length]; aggregate.runs++;
+    summary[`${row.status}_runs`]++; aggregate[row.status]++;
+    if (row.status === 'completed') {
+      // Bound aggregate cardinality even if a malicious adapter invents a new
+      // metric/outcome name in every run. Raw per-run values remain on disk.
+      const outcome = Object.hasOwn(aggregate.outcomes, row.outcome) || Object.keys(aggregate.outcomes).length < 127 ? row.outcome : 'other';
+      aggregate.outcomes[outcome] = (Object.hasOwn(aggregate.outcomes, outcome) ? aggregate.outcomes[outcome] : 0) + 1;
+      for (const [key, value] of Object.entries(row.metrics)) {
+        if (!Object.hasOwn(aggregate.metrics, key) && Object.keys(aggregate.metrics).length >= 32) continue;
+        if (!Object.hasOwn(aggregate.metrics, key)) aggregate.metrics[key] = { count: 0, min: value, max: value, mean: 0 };
+        const metric = aggregate.metrics[key];
+        metric.count++; metric.min = Math.min(metric.min, value); metric.max = Math.max(metric.max, value);
+        // Weighted arithmetic avoids overflow from subtracting opposite extremes.
+        metric.mean = Math.max(metric.min, Math.min(metric.max, metric.mean * ((metric.count - 1) / metric.count) + value / metric.count));
+      }
+    }
+    if (trace) { if (trace.truncated) trace.actions = trace.actions.slice(0, Math.max(0, trace.states.length - 1)); trace.status = row.status; trace.error = row.error; const target = path.join(outputDir, `trace-${String(index).padStart(5, '0')}.json`); await writeJson(target, trace); traces.push(target); }
+    writeChain = writeChain.then(() => file.write(JSON.stringify(row) + '\n')); await writeChain;
+    if (onProgress) await onProgress({ finished_runs: summary.completed_runs + summary.failed_runs + summary.truncated_runs, requested_runs: config.runs, completed_runs: summary.completed_runs, failed_runs: summary.failed_runs, truncated_runs: summary.truncated_runs, total_steps: summary.total_steps });
+  }
+  try {
+    const workers = Array.from({ length: Math.min(config.workers, config.runs) }, async () => {
+      try {
+        while (next < config.runs) {
+          const index = next++; const prior = commitTail; let release;
+          commitTail = new Promise(resolve => { release = resolve; });
+          try { await execute(index, prior); } finally { release(); }
+        }
+      }
+      catch (error) { controller.abort(); throw error; }
+    });
+    const outcomes = await Promise.allSettled(workers);
+    const failure = outcomes.find(item => item.status === 'rejected');
+    if (failure) throw failure.reason;
+  }
+  finally { clearTimeout(timer); signal?.removeEventListener('abort', cancel); controller.abort(); try { await writeChain; } finally { await file.close(); } }
+  summary.trace_count = traces.length; summary.duration_ms = Math.min(bridge.batchTimeoutMs, Date.now() - started);
+  traces.sort();
+  const report = { results_path: resultsPath, stop_reason: stopReason, determinism_note: 'Replay verifies recorded observations. Reproducibility requires the game to honor its seed; this runner cannot prove determinism.' };
+  await writeJson(path.join(outputDir, 'summary.json'), summary);
+  return { summary, traces, report };
+}
+export async function replayTrace({ trace, bridge, signal, outputDir }) {
+  if (typeof trace === 'string') { if ((await fs.stat(trace)).size > MAX_TRACE_BYTES + 1024) throw new Error('Trace exceeds replay limit.'); trace = JSON.parse(await fs.readFile(trace, 'utf8')); }
+  const failedStart = trace?.status === 'failed' && trace?.failure_phase === 'start' && trace?.states?.length === 0;
+  if (!trace || trace.version !== 1 || !boundedString(trace.seed, 128) || !boundedString(trace.strategy, 80) || !Number.isInteger(trace.max_steps) || trace.max_steps < 1 || trace.max_steps > 10000 || !Array.isArray(trace.actions) || trace.actions.length > 10000 || trace.actions.some(action => !boundedString(action, 128)) || !Array.isArray(trace.states) || (!failedStart && trace.states.length !== trace.actions.length + 1) || (failedStart && trace.actions.length) || (trace.failed_action !== undefined && !boundedString(trace.failed_action, 128))) throw new Error('Trace is invalid for replay.');
+  if (Buffer.byteLength(JSON.stringify(trace)) > MAX_TRACE_BYTES + 1024) throw new Error('Trace exceeds replay limit.');
+  for (const state of trace.states) observation({ ...state, actions: state.done ? [] : [{ id: 'replay-validation' }] });
+  const options = bridgeOptions(bridge);
+  const deadline = AbortSignal.timeout(options.batchTimeoutMs);
+  const replaySignal = signal ? AbortSignal.any([signal, deadline]) : deadline;
+  const client = openBridge(options, { signal: replaySignal });
+  let result = { matched: true, matched_prefix: false, fully_replayed: false, failure_reproduced: null, first_divergence: null };
+  const start = () => client.request('simulation.start', { version: 1, seed: trace.seed, strategy: trace.strategy, max_steps: trace.max_steps });
+  async function reproduce(request, step) {
+    try {
+      const actual = await request(); result.matched = false; result.failure_reproduced = false;
+      result.first_divergence = { step, reason: 'Recorded protocol failure did not recur.', actual: stateRecord(actual) };
+    } catch (error) {
+      result.failure_reproduced = error.message === trace.error;
+      result.matched = result.failure_reproduced;
+      if (!result.matched) result.first_divergence = { step, expected_error: trace.error, actual_error: error.message };
+    }
+  }
+  try {
+    if (failedStart) await reproduce(start, 0);
+    else {
+      for (let i = 0; i < trace.states.length; i++) {
+        let state;
+        try { state = i === 0 ? await start() : await client.request('simulation.step', { action: trace.actions[i - 1] }); }
+        catch (error) { result.matched = false; result.first_divergence = { step: i, actual_error: error.message }; break; }
+        const expected = trace.states[i]; const actual = stateRecord(state);
+        const canonical = value => JSON.stringify([value.state_hash, value.done, value.outcome ?? null, Object.entries(value.metrics || {}).sort(([a], [b]) => compareText(a, b))]);
+        if (canonical(expected) !== canonical(actual)) { result.matched = false; result.first_divergence = { step: i, expected, actual }; break; }
+        if (i < trace.actions.length && !state.actions.some(action => action.id === trace.actions[i])) { result.matched = false; result.first_divergence = { step: i, reason: 'Recorded action is no longer legal.' }; break; }
+      }
+      if (result.matched) {
+        result.matched_prefix = true;
+        result.fully_replayed = !trace.truncated && trace.status !== 'failed';
+        if (trace.status === 'failed' && trace.failed_action && !trace.truncated) await reproduce(() => client.request('simulation.step', { action: trace.failed_action }), trace.states.length);
+      }
+    }
+  } finally { await client.stop(); }
+  if (outputDir) { await fs.mkdir(outputDir, { recursive: true }); const file = path.resolve(outputDir, 'replay.json'); await writeJson(file, result); result.report_path = file; }
+  return result;
+}

package/src/simulation/protocol.js

@@ -0,0 +1,90 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+const forbidden = new Set(['__proto__', 'constructor', 'prototype']);
+export const MAX_RESPONSE = 256 * 1024;
+export function boundedString(value, max) { return typeof value === 'string' && value.length > 0 && value.length <= max && !forbidden.has(value); }
+export function observation(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || typeof value.done !== 'boolean' || !boundedString(value.state_hash, 128) || !Array.isArray(value.actions) || value.actions.length > 256) throw new Error('Invalid simulation observation.');
+  const numbers = (map, limit, maxAbsolute = Infinity) => {
+    if (!map || typeof map !== 'object' || Array.isArray(map) || Object.keys(map).length > limit || Object.entries(map).some(([key, n]) => !boundedString(key, 80) || typeof n !== 'number' || (!Number.isFinite(n) || Math.abs(n) > maxAbsolute))) throw new Error('Invalid simulation numeric map.');
+    return { ...map };
+  };
+  const actions = value.actions.map(action => {
+    if (!action || !boundedString(action.id, 128)) throw new Error('Invalid simulation action.');
+    return { id: action.id, ...(action.scores === undefined ? {} : { scores: numbers(action.scores, 16) }) };
+  });
+  if (new Set(actions.map(action => action.id)).size !== actions.length) throw new Error('Duplicate simulation action.');
+  if (!value.done && !actions.length) throw new Error('Nonterminal simulation needs legal actions.');
+  if (value.outcome !== undefined && !boundedString(value.outcome, 80)) throw new Error('Invalid simulation outcome.');
+  return { done: value.done, state_hash: value.state_hash, actions, ...(value.metrics === undefined ? {} : { metrics: numbers(value.metrics, 32, 1e15) }), ...(value.outcome === undefined ? {} : { outcome: value.outcome }) };
+}
+export function bridgeOptions(bridge) {
+  // Native Windows has no POSIX process-group kill. Do not buy a batch whose
+  // adapter descendants we cannot reliably stop; WSL uses the Linux path.
+  if (process.platform === 'win32') throw new Error('Simulation Runner is not supported on native Windows. Run it in WSL, Linux or macOS so cancellation can stop the adapter process group.');
+  if (!bridge || !path.isAbsolute(bridge.command || '') || (bridge.args !== undefined && (!Array.isArray(bridge.args) || bridge.args.length > 256 || bridge.args.some(arg => typeof arg !== 'string' || arg.length > 8192))) || (bridge.cwd !== undefined && !path.isAbsolute(bridge.cwd))) throw new Error('Bridge needs an absolute command, string arguments and optional absolute cwd.');
+  const timeoutMs = bridge.timeoutMs ?? 30000; const batchTimeoutMs = bridge.batchTimeoutMs ?? 900000;
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || !Number.isInteger(batchTimeoutMs) || batchTimeoutMs < 1 || batchTimeoutMs > 900000) throw new Error('Invalid simulation deadline.');
+  if (bridge.env !== undefined && (!bridge.env || typeof bridge.env !== 'object' || Array.isArray(bridge.env) || Object.entries(bridge.env).some(([k, v]) => !boundedString(k, 128) || typeof v !== 'string' || v.length > 8192))) throw new Error('Invalid bridge environment.');
+  return { ...bridge, timeoutMs, batchTimeoutMs };
+}
+export function childEnvironment(extra = {}, playtest = {}) {
+  // Local adapters are trusted code, not a security sandbox. Avoid accidentally
+  // forwarding account/provider credentials or inherited synthetic identities.
+  const env = {};
+  for (const [key, value] of Object.entries({ ...process.env, ...extra })) {
+    if (/TOKEN|SECRET|PASSWORD|CREDENTIAL|API.?KEY|PRIVATE.?KEY|AUTH|^AWS_|^AZURE_|^GOOGLE_|^ANTHROPIC_|^OPENAI_|^NODE_OPTIONS$|^RAVENSIGHT_.*(?:RUN|JOB)/i.test(key)) continue;
+    env[key] = value;
+  }
+  env.RAVENSIGHT_PLAYTEST_TOKEN = typeof playtest.token === 'string' && playtest.token ? playtest.token : 'invalid-simulation-preflight-token';
+  env.RAVENSIGHT_PLAYTEST_RUN_ID = String(playtest.runId || 'local-simulation');
+  env.RAVENSIGHT_PLAYTEST_JOB_ID = String(playtest.jobId || 'local-simulation');
+  return env;
+}
+export function openBridge(raw, { signal, playtest } = {}) {
+  const bridge = bridgeOptions(raw);
+  const child = spawn(bridge.command, bridge.args || [], { cwd: bridge.cwd, shell: false, detached: process.platform !== 'win32', env: childEnvironment(bridge.env, playtest), stdio: ['pipe', 'pipe', 'pipe'] });
+  let buffer = Buffer.alloc(0), id = 0, pending, failure, closing;
+  const kill = sig => { try { if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, sig); else child.kill(sig); } catch {} };
+  const fail = message => { failure ||= new Error(message); if (pending) { clearTimeout(pending.timer); pending.reject(failure); pending = null; } };
+  const stop = () => {
+    if (closing) return closing;
+    fail('Simulation bridge stopped.'); signal?.removeEventListener('abort', abort);
+    kill('SIGTERM');
+    // Always escalate against the process group, including when child.killed is
+    // true or the leader exited while a descendant still owns its pipes.
+    closing = new Promise(resolve => setTimeout(() => { kill('SIGKILL'); child.stdin.destroy(); child.stdout.destroy(); child.stderr.destroy(); resolve(); }, 100));
+    return closing;
+  };
+  const abort = () => { fail('Simulation cancelled.'); void stop(); };
+  signal?.addEventListener('abort', abort, { once: true });
+  if (signal?.aborted) abort();
+  child.stderr.resume();
+  child.on('error', () => { fail('Simulation bridge could not start.'); void stop(); });
+  child.on('exit', () => { fail('Simulation bridge exited.'); });
+  child.stdin.on('error', () => { fail('Simulation bridge input failed.'); void stop(); });
+  child.stdout.on('data', chunk => {
+    buffer = Buffer.concat([buffer, chunk]);
+    if (buffer.length > MAX_RESPONSE) { fail('Simulation response exceeds 256 KB.'); void stop(); return; }
+    let end;
+    while ((end = buffer.indexOf(10)) >= 0) {
+      const line = buffer.subarray(0, end); buffer = buffer.subarray(end + 1);
+      try {
+        const message = JSON.parse(line.toString('utf8'), (key, value) => { if (forbidden.has(key)) throw new Error(); return value; });
+        if (!pending || message.jsonrpc !== '2.0' || message.id !== pending.id || message.error || !Object.hasOwn(message, 'result')) throw new Error();
+        const result = observation(message.result); const entry = pending; pending = null; clearTimeout(entry.timer); entry.resolve(result);
+      } catch { fail('Invalid simulation protocol response.'); void stop(); return; }
+    }
+  });
+  return {
+    request(method, params) {
+      if (failure) return Promise.reject(failure);
+      if (pending) return Promise.reject(new Error('Simulation request already pending.'));
+      return new Promise((resolve, reject) => {
+        const requestId = ++id;
+        pending = { id: requestId, resolve, reject, timer: setTimeout(() => { fail('Simulation response timed out.'); void stop(); }, bridge.timeoutMs) };
+        child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: requestId, method, params }) + '\n');
+      });
+    }, stop
+  };
+}