@agilno-tech/rivet 0.1.0-alpha.0

package/src/runtime/application.js

@@ -0,0 +1,353 @@
+import { isExecutionCompatibleCwd, isProjectExecutable } from '../config/commands.js';
+import { createTrackerProviderFactory } from '../adapters/factory.js';
+import { createNodeProviderTransport } from '../adapters/node-transport.js';
+import * as filesystem from 'node:fs';
+import { spawn as nodeSpawn } from 'node:child_process';
+import { lstat as lstatFile, realpath as realpathFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+
+import {
+  createClaudeClient,
+  createClaudePlanningClient,
+  CLAUDE_ADAPTER_SYNTAX,
+} from '../clients/claude.js';
+import {
+  createCodexClient,
+  createCodexPlanningClient,
+  CODEX_ADAPTER_SYNTAX,
+} from '../clients/codex.js';
+import {
+  CLAUDE_FEATURE_PROFILE,
+  FEATURE_PLANNING_TIMEOUT_MS,
+  clientProfileFor,
+  matchesClientProfile,
+} from '../feature/client-profile.js';
+import { collectEvidenceBundle } from '../evidence/collect.js';
+import { createFeatureRunStore } from '../feature/run-store.js';
+import { createFeatureExecutor } from '../feature/runtime-bridge.js';
+import { createHostExecution } from '../feature/host-execution.js';
+import { discoverHarnesses } from './harness-discovery.js';
+import { createFeatureWorkflow } from '../feature/workflow.js';
+import { createGitClient } from '../git/client.js';
+import { createReservedWorktree } from '../git/worktrees.js';
+import { buildLaunchContract } from '../prompts/launch-contract.js';
+import { runQualityGates } from '../quality/runner.js';
+import { resolveFeatureRunPaths } from '../state/paths.js';
+import { createOrchestrator } from './orchestrator.js';
+
+const INPUT_KEYS = new Set(['cwd', 'env', 'fs', 'fetch', 'spawn', 'now', 'featureWorkflow', 'providerTransport']);
+const FEATURE_WORKFLOW_METHODS = Object.freeze(['propose', 'start', 'watch', 'status', 'resume', 'cancel']);
+
+export class ApplicationConfigurationError extends Error {
+  constructor(reason = 'configuration') {
+    const messages = {
+      configuration: 'Rivet runtime configuration is missing or invalid.',
+      'command-executable-unsafe': 'A configured project executable path is unsafe. Keep its working directory and executable ancestors inside the isolated checkout without directory symlinks.',
+      'command-executable-unavailable': 'A configured quality command executable is unavailable. Activate the project environment, install the required tool on PATH, or correct its RIVET_<TOOL>_EXECUTABLE override, then run rivet doctor.',
+      'git-unavailable': 'No usable Git executable was found. Install Git on PATH or set RIVET_GIT_EXECUTABLE to its absolute canonical executable path.',
+      'git-executable-invalid': 'RIVET_GIT_EXECUTABLE must be an absolute canonical path to a Git executable. Correct this setting and retry.',
+      'git-executable-unusable': 'RIVET_GIT_EXECUTABLE does not identify a usable regular Git executable. Check that the path is canonical and the file exists with execute permission, then retry.',
+    };
+    const selectedReason = Object.hasOwn(messages, reason) ? reason : 'configuration';
+    super(messages[selectedReason]);
+    this.name = 'ApplicationConfigurationError';
+    this.code = 'ERR_APPLICATION_CONFIGURATION';
+    this.safeMessage = this.message;
+    this.details = Object.freeze({ reason: selectedReason });
+  }
+}
+
+function fail(reason) { throw new ApplicationConfigurationError(reason); }
+
+function capture(input) {
+  try {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) fail();
+    const keys = Reflect.ownKeys(input);
+    if (keys.length > INPUT_KEYS.size || keys.some(key => typeof key !== 'string' || !INPUT_KEYS.has(key))) fail();
+    const output = Object.create(null);
+    for (const key of keys) {
+      const descriptor = Object.getOwnPropertyDescriptor(input, key);
+      if (!descriptor?.enumerable || !Object.hasOwn(descriptor, 'value')) fail();
+      output[key] = descriptor.value;
+    }
+    return output;
+  } catch (error) {
+    if (error instanceof ApplicationConfigurationError) throw error;
+    fail();
+  }
+}
+
+function environment(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) fail();
+  const output = Object.create(null);
+  let keys;
+  try { keys = Reflect.ownKeys(input); } catch { fail(); }
+  if (keys.length > 512 || keys.some(key => typeof key !== 'string')) fail();
+  for (const key of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+    if (!descriptor?.enumerable || typeof descriptor.value !== 'string' || descriptor.value.includes('\0')) fail();
+    output[key] = descriptor.value;
+  }
+  return Object.freeze(output);
+}
+
+function executable(value) {
+  if (typeof value !== 'string' || value.length < 2 || value.length > 1024 || !isAbsolute(value)
+    || /[\u0000\r\n]/.test(value)) fail();
+  return value;
+}
+
+function executableCandidates(runner, pathValue) {
+  const directories = typeof pathValue === 'string' ? pathValue.split(':').slice(0, 128) : [];
+  return [
+    ...directories.filter(directory => directory.length > 1 && directory.length <= 1024
+      && isAbsolute(directory) && resolve(directory) === directory && !/[\u0000\r\n]/.test(directory))
+      .map(directory => join(directory, runner)),
+    `/opt/homebrew/bin/${runner}`, `/usr/local/bin/${runner}`, `/usr/bin/${runner}`,
+  ];
+}
+
+function captureFeatureWorkflow(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) fail();
+  const keys = Reflect.ownKeys(value);
+  if (keys.length !== FEATURE_WORKFLOW_METHODS.length
+    || keys.some(key => typeof key !== 'string' || !FEATURE_WORKFLOW_METHODS.includes(key))) fail();
+  const output = {};
+  for (const method of FEATURE_WORKFLOW_METHODS) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, method);
+    if (!descriptor?.enumerable || !Object.hasOwn(descriptor, 'value') || typeof descriptor.value !== 'function') fail();
+    output[method] = descriptor.value;
+  }
+  return Object.freeze(output);
+}
+
+export function createRivetApplication(input = {}) {
+  const configured = capture(input);
+  const cwd = configured.cwd ?? (() => process.cwd());
+  const env = environment(configured.env ?? process.env);
+  const fs = configured.fs ?? filesystem;
+  const fetch = configured.fetch ?? globalThis.fetch;
+  const spawn = configured.spawn ?? nodeSpawn;
+  const now = configured.now ?? (() => new Date().toISOString());
+  if (typeof cwd !== 'function' || !fs || typeof fs !== 'object' || typeof fetch !== 'function'
+    || typeof spawn !== 'function' || typeof now !== 'function') fail();
+  let gitClientPromise;
+  const gitClient = () => {
+    gitClientPromise ??= (async () => {
+      if (env.RIVET_GIT_EXECUTABLE !== undefined) {
+        let configuredGit;
+        try {
+          configuredGit = executable(env.RIVET_GIT_EXECUTABLE);
+          if (resolve(configuredGit) !== configuredGit) fail();
+        } catch { fail('git-executable-invalid'); }
+        try { return await createGitClient({ gitExecutable: configuredGit }); }
+        catch { fail('git-executable-unusable'); }
+      }
+      for (const candidate of executableCandidates('git', env.PATH)) {
+        try { return await createGitClient({ gitExecutable: executable(await realpathFile(candidate)) }); } catch {}
+      }
+      fail('git-unavailable');
+    })();
+    return gitClientPromise;
+  };
+  let workflowPromise;
+  let executorPromise;
+  let hostExecutionPromise;
+  const selectedHarnesses = new Map();
+  const selectedVersion = kind => selectedHarnesses.get(kind)?.version;
+  const harnessSettings = kind => {
+    const selected = selectedHarnesses.get(kind);
+    return selected ? {
+      executable: selected.executable,
+      ...(selected.interpreter ? { interpreter: selected.interpreter } : {}),
+    } : {
+      executable: executable(env[`RIVET_${kind.toUpperCase()}_EXECUTABLE`]),
+      ...clientInterpreter(kind),
+    };
+  };
+  const harnesses = Object.freeze({
+    discover(projectRoot, { signal } = {}) { return discoverHarnesses({ env, projectRoot, signal }); },
+    async select(kind, projectRoot, { signal } = {}) {
+      if (!['claude', 'codex'].includes(kind)) fail();
+      const found = await discoverHarnesses({ env, projectRoot, signal });
+      const selected = found.find(item => item.kind === kind && item.executable);
+      if (!selected) fail();
+      selectedHarnesses.set(kind, selected);
+      return selected;
+    },
+  });
+  const clientEnvironment = Object.freeze(Object.fromEntries(
+    ['PATH', 'LANG', 'LC_ALL', 'TZ', 'TERM', 'TMPDIR', 'HOME', 'USER', 'LOGNAME', 'SHELL']
+      .filter(key => env[key] !== undefined)
+      .map(key => [key, env[key]]),
+  ));
+  const clientInterpreter = kind => {
+    const value = env[`RIVET_${kind.toUpperCase()}_INTERPRETER`];
+    return value === undefined ? {} : { interpreter: executable(value) };
+  };
+  const planningClientFor = async request => {
+    if (!request || typeof request !== 'object' || Array.isArray(request)
+      || Reflect.ownKeys(request).length !== 2
+      || !Object.hasOwn(request, 'client') || !Object.hasOwn(request, 'project')) fail();
+    if (request.client === 'claude') {
+      return createClaudePlanningClient({
+        ...harnessSettings('claude'),
+        expectedVersion: selectedVersion('claude'),
+        worktree: executable(request.project),
+        environment: clientEnvironment,
+        timeoutMs: FEATURE_PLANNING_TIMEOUT_MS,
+      });
+    }
+    if (request.client === 'codex') {
+      return createCodexPlanningClient({
+        ...harnessSettings('codex'),
+        expectedVersion: selectedVersion('codex'),
+        worktree: executable(request.project),
+        environment: clientEnvironment,
+        timeoutMs: FEATURE_PLANNING_TIMEOUT_MS,
+      });
+    }
+    fail();
+  };
+  const agentClientFor = (kind, clientProfile) => {
+    if (!matchesClientProfile(kind, clientProfile)) fail();
+    if (kind === 'claude') return createClaudeClient({
+      ...harnessSettings('claude'),
+      expectedVersion: selectedVersion('claude'),
+      args: [
+        ...CLAUDE_ADAPTER_SYNTAX.args.slice(0, -1),
+        '--model', CLAUDE_FEATURE_PROFILE.model,
+        '--effort', 'low',
+        '--permission-mode', 'acceptEdits',
+        '{stdin}',
+      ],
+      environment: clientEnvironment,
+    });
+    if (kind === 'codex') return createCodexClient({
+      ...harnessSettings('codex'),
+      expectedVersion: selectedVersion('codex'),
+      args: [...CODEX_ADAPTER_SYNTAX.args.slice(0, -1), '--sandbox', 'workspace-write', '{stdin}'],
+      environment: clientEnvironment,
+    });
+    fail();
+  };
+  const resolveCommandExecutable = async (runner, options = {}) => {
+    if (typeof runner !== 'string' || (!/^[a-z][a-z0-9._+-]{0,127}$/i.test(runner) && !isProjectExecutable(runner))
+      || !options || typeof options !== 'object' || Array.isArray(options)
+      || Object.keys(options).some(key => !['execution', 'worktree', 'cwd'].includes(key))
+      || (options.execution !== undefined && options.execution !== 'argv')) fail();
+    const direct = options.execution === 'argv';
+    if (runner.startsWith('./')) {
+      if (!direct || typeof options.worktree !== 'string' || !isAbsolute(options.worktree)
+        || resolve(options.worktree) !== options.worktree || !isExecutionCompatibleCwd(options.cwd ?? '.')) fail('command-executable-unsafe');
+      try {
+        const root = options.worktree;
+        const parts = [...((options.cwd ?? '.') === '.' ? [] : options.cwd.split('/')), ...runner.slice(2).split('/')];
+        let cursor = root;
+        for (const part of [null, ...parts.slice(0, -1)]) {
+          if (part !== null) cursor = join(cursor, part);
+          const metadata = await lstatFile(cursor);
+          if (!metadata.isDirectory() || metadata.isSymbolicLink() || await realpathFile(cursor) !== cursor) fail('command-executable-unsafe');
+        }
+        const invocation = executable(join(cursor, parts.at(-1)));
+        await realpathFile(invocation);
+        return invocation;
+      } catch (error) {
+        if (error?.code === 'ERR_APPLICATION_CONFIGURATION') throw error;
+        fail(error?.code === 'ENOENT' || error?.code === 'ENOTDIR' ? 'command-executable-unavailable' : 'command-executable-unsafe');
+      }
+    }
+
+    const resolveExecutable = async candidate => {
+      const path = executable(candidate);
+      const canonical = executable(await realpathFile(path));
+      // Interpreter and tool aliases can select an environment or invocation mode.
+      return direct ? executable(join(await realpathFile(dirname(path)), basename(path))) : canonical;
+    };
+    const configuredPath = env[`RIVET_${runner.toUpperCase().replaceAll('-', '_')}_EXECUTABLE`];
+    if (configuredPath !== undefined) {
+      try { return await resolveExecutable(configuredPath); }
+      catch (error) { if (direct) fail('command-executable-unavailable'); throw error; }
+    }
+    for (const candidate of executableCandidates(runner, env.PATH)) {
+      try { return await resolveExecutable(candidate); } catch {}
+    }
+    fail(direct ? 'command-executable-unavailable' : undefined);
+  };
+  const executeFeature = async (request, options) => {
+    executorPromise ??= gitClient().then(client => createFeatureExecutor({
+      gitClient: client,
+      clientFor: async (kind, profile, { project, signal }) => {
+        await harnesses.select(kind, project, { signal });
+        return agentClientFor(kind, profile);
+      },
+      resolveCommandExecutable,
+      now,
+      environment: clientEnvironment,
+    }));
+    return (await executorPromise)(request, options);
+  };
+  const resolvedWorkflow = () => {
+    if (configured.featureWorkflow !== undefined) return Promise.resolve(captureFeatureWorkflow(configured.featureWorkflow));
+    workflowPromise ??= gitClient().then(client => createFeatureWorkflow({
+      gitClient: client,
+      planningClientFor,
+      trackerAdapterFor: async ({ provider, config }) => createTrackerProviderFactory({
+        config,
+        environment: env,
+        transport: configured.providerTransport ?? createNodeProviderTransport(),
+        clock: now,
+      }).create({ tracker: provider }),
+      executeFeature,
+      now,
+    }));
+    return workflowPromise;
+  };
+  const workflow = configured.featureWorkflow !== undefined
+    ? captureFeatureWorkflow(configured.featureWorkflow)
+    : Object.freeze(Object.fromEntries(FEATURE_WORKFLOW_METHODS.map(method => [
+      method, async (...args) => (await resolvedWorkflow())[method](...args),
+    ])));
+
+  const hostExecution = Object.freeze(Object.fromEntries(
+    ['prepare', 'nextAction', 'status', 'submitResult', 'verify', 'recover'].map(method => [
+      method,
+      async (...args) => {
+        hostExecutionPromise ??= gitClient().then(client => createHostExecution({
+          gitClient: client,
+          now,
+          resolveCommandExecutable,
+          environment: clientEnvironment,
+        }));
+        const service = await hostExecutionPromise;
+        if (typeof service[method] !== 'function') fail();
+        return service[method](...args);
+      },
+    ]),
+  ));
+
+  const feature = Object.freeze({
+    ...workflow,
+    async openRun(projectRoot, runId) {
+      const paths = await resolveFeatureRunPaths(projectRoot, runId);
+      return Object.freeze({ paths, store: createFeatureRunStore(paths) });
+    },
+    createAgentClient(kind) {
+      return agentClientFor(kind, clientProfileFor(kind));
+    },
+    async prepareWorktree(request, options = {}) {
+      return createReservedWorktree(request, { ...options, gitClient: await gitClient() });
+    },
+    buildLaunchContract,
+    createOrchestrator,
+    async runQualityGates(request, options = {}) {
+      return runQualityGates(request, { ...options, gitClient: await gitClient() });
+    },
+    async collectEvidence(request) {
+      return collectEvidenceBundle({ ...request, gitClient: await gitClient() });
+    },
+  });
+
+  return Object.freeze({ cwd, env, fs, fetch, feature, work: hostExecution, harnesses, resolveCommandExecutable });
+}

package/src/runtime/dependency-directory.js

@@ -0,0 +1,33 @@
+import {createHash} from 'node:crypto';
+import {lstat,realpath,open} from 'node:fs/promises';
+import {constants} from 'node:fs';
+import {join} from 'node:path';
+const DIRECTORY='.rivet-deps';
+const MARKER='.rivet-owner.json';
+const hash=bytes=>createHash('sha256').update(bytes).digest('hex');
+const identity=stat=>`${stat.dev}:${stat.ino}`;
+const fail=()=>{throw new Error('Managed dependency directory is unsafe.');};
+export async function readDependencyFile(path,maxBytes) {
+ const file=await open(path,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);
+ try {
+  const before=await file.stat({bigint:true});
+  if(!before.isFile()||before.nlink!==1n||before.size>BigInt(maxBytes)||await realpath(path)!==path)fail();
+  const buffer=Buffer.alloc(maxBytes+1);let count=0;
+  while(count<buffer.length) {const result=await file.read(buffer,count,buffer.length-count,null);if(!result.bytesRead)break;count+=result.bytesRead;}
+  const after=await file.stat({bigint:true}),entry=await lstat(path,{bigint:true});
+  if(count>maxBytes||!entry.isFile()||entry.isSymbolicLink()||identity(before)!==identity(after)||identity(before)!==identity(entry)||before.size!==after.size||before.mtimeNs!==after.mtimeNs||before.ctimeNs!==after.ctimeNs||BigInt(count)!==after.size)fail();
+  return buffer.subarray(0,count);
+ }finally {await file.close();}
+}
+export async function inspectDependencyDirectory(root) {
+ const rootStat=await lstat(root,{bigint:true});
+ if(!rootStat.isDirectory()||rootStat.isSymbolicLink()||await realpath(root)!==root)fail();
+ const path=join(root,DIRECTORY);
+ let stat;try {stat=await lstat(path,{bigint:true});}catch(error){if(error.code==='ENOENT')return null;throw error;}
+ if(!stat.isDirectory()||stat.isSymbolicLink()||await realpath(path)!==path||(stat.mode&0o077n)!==0n)fail();
+ const marker=await readDependencyFile(join(path,MARKER),4096);
+ const value=JSON.parse(marker.toString('utf8'));
+ if(Object.keys(value).sort().join(',')!=='directoryIdentity,kind,root,rootIdentity,token,version'||value.kind!=='rivet-dependencies'||value.version!==1||value.root!==root||value.rootIdentity!==identity(rootStat)||value.directoryIdentity!==identity(stat)||typeof value.token!=='string'||!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(value.token))fail();
+ if((await readDependencyFile(join(path,'.gitignore'),32)).toString()!=='*\n')fail();
+ return Object.freeze({identity:identity(stat),marker:hash(marker)});
+}

package/src/runtime/harness-discovery.js

@@ -0,0 +1,121 @@
+import { constants } from 'node:fs';
+import { access, open, realpath, stat } from 'node:fs/promises';
+import { basename, delimiter, isAbsolute, join, relative } from 'node:path';
+
+import { missingCapabilities, validVersion } from '../clients/compatibility.js';
+import { CLAUDE_ADAPTER_SYNTAX } from '../clients/claude.js';
+import { CODEX_ADAPTER_SYNTAX } from '../clients/codex.js';
+import { createProcessRunner } from '../clients/process-runner.js';
+
+const ADAPTERS = Object.freeze({ claude: CLAUDE_ADAPTER_SYNTAX, codex: CODEX_ADAPTER_SYNTAX });
+
+function inside(root, path) {
+  const part = relative(root, path);
+  return part === '' || (part !== '..' && !part.startsWith('../') && !isAbsolute(part));
+}
+
+async function usable(path, projectRoot) {
+  if (typeof path !== 'string' || !isAbsolute(path) || path.length > 1024 || /[\u0000\r\n]/.test(path)) return null;
+  try {
+    const canonical = await realpath(path);
+    if (projectRoot && inside(projectRoot, canonical)) return null;
+    const metadata = await stat(canonical);
+    if (!metadata.isFile()) return null;
+    await access(canonical, constants.X_OK);
+    return canonical;
+  } catch { return null; }
+}
+
+async function launchForm(executable, interpreter) {
+  let handle;
+  try {
+    handle = await open(executable, 'r');
+    const header = Buffer.alloc(512);
+    const { bytesRead } = await handle.read(header, 0, header.length, 0);
+    const magic = header.subarray(0, 4).toString('hex');
+    const native = process.platform === 'linux' ? magic === '7f454c46'
+      : ['feedface', 'feedfacf', 'cefaedfe', 'cffaedfe', 'cafebabe', 'bebafeca'].includes(magic);
+    if (native) return interpreter === null ? 'eligible' : 'interpreter-unneeded';
+    if (interpreter !== null) {
+      const binary = await open(interpreter, 'r');
+      try {
+        const interpreterHeader = Buffer.alloc(4);
+        await binary.read(interpreterHeader, 0, 4, 0);
+        const interpreterMagic = interpreterHeader.toString('hex');
+        const nativeInterpreter = process.platform === 'linux' ? interpreterMagic === '7f454c46'
+          : ['feedface', 'feedfacf', 'cefaedfe', 'cffaedfe', 'cafebabe', 'bebafeca'].includes(interpreterMagic);
+        if (!nativeInterpreter) return 'interpreter-incompatible';
+      } finally { await binary.close(); }
+    }
+    const newline = header.indexOf(0x0a);
+    if (newline < 3 || newline > 256 || newline >= bytesRead) return 'executable-unsafe';
+    const firstLine = new TextDecoder('utf-8', { fatal: true }).decode(header.subarray(0, newline));
+    if (interpreter === null) return firstLine === '#!/usr/bin/env node' ? 'node-interpreter-required' : 'interpreter-required';
+    if (firstLine === `#!${interpreter}`
+      || (firstLine === '#!/usr/bin/env node' && basename(interpreter) === 'node')) return 'eligible';
+    return 'interpreter-incompatible';
+  } catch { return 'executable-unsafe'; }
+  finally { await handle?.close(); }
+}
+
+async function candidates(kind, env, projectRoot) {
+  const configured = env[`RIVET_${kind.toUpperCase()}_EXECUTABLE`];
+  const entries = configured === undefined
+    ? String(env.PATH ?? '').split(delimiter).filter(isAbsolute).map(directory => join(directory, kind))
+    : [configured];
+  const found = [];
+  for (const entry of entries.slice(0, 128)) {
+    const canonical = await usable(entry, projectRoot);
+    if (canonical !== null && !found.includes(canonical)) found.push(canonical);
+  }
+  return found;
+}
+
+export async function discoverHarnesses({ env, projectRoot, runner, signal }) {
+  const result = [];
+  for (const [kind, syntax] of Object.entries(ADAPTERS)) {
+    const paths = await candidates(kind, env, projectRoot);
+    let selected = null;
+    let reason = paths.length === 0 ? 'not-installed' : 'capability-probe-failed';
+    for (const executable of paths) {
+      const interpreterName = env[`RIVET_${kind.toUpperCase()}_INTERPRETER`];
+      let interpreter = interpreterName === undefined ? null : await usable(interpreterName, projectRoot);
+      if (interpreterName !== undefined && interpreter === null) { reason = 'interpreter-unavailable'; continue; }
+      let form = await launchForm(executable, interpreter);
+      if (interpreterName === undefined && form === 'node-interpreter-required') {
+        interpreter = await usable(process.execPath, projectRoot);
+        if (interpreter === null) { reason = 'interpreter-unavailable'; continue; }
+        form = await launchForm(executable, interpreter);
+      }
+      if (form !== 'eligible') { reason = form; continue; }
+      try {
+        const processRunner = runner ? null : await createProcessRunner({
+          executable, ...(interpreter ? { interpreter } : {}), worktree: projectRoot,
+          environment: Object.fromEntries(
+            ['PATH', 'LANG', 'LC_ALL', 'TZ', 'TERM', 'TMPDIR', 'HOME', 'USER', 'LOGNAME', 'SHELL']
+              .filter(key => env[key] !== undefined).map(key => [key, env[key]]),
+          ),
+          timeoutMs: 3_000, launchTimeoutMs: 3_000, maxOutputBytes: 64 * 1024, signal,
+        });
+        const probe = async (args, help = false) => {
+          if (!runner) return help ? processRunner.probeHelp(kind) : processRunner.probeVersion();
+          const output = await runner(interpreter ?? executable, interpreter ? [executable, ...args] : args,
+            { cwd: projectRoot, shell: false, timeoutMs: 3_000, maxOutputBytes: help ? 65536 : 4096, signal });
+          if (output.code !== 0 || output.timedOut || output.truncated?.stdout || output.truncated?.stderr) throw new Error('probe failed');
+          const text = String(output.stdout ?? '').trim();
+          if (Buffer.byteLength(text) > (help ? 65536 : 4096)) throw new Error('probe oversized');
+          return text;
+        };
+        const observed = await probe([...syntax.versionArgs]);
+        if (!validVersion(observed)) continue;
+        const help = await probe(kind === 'codex' ? ['exec', '--help'] : ['--help'], true);
+        const missing = missingCapabilities(help, syntax.requiredOptions);
+        if (missing.length) { reason = `missing-options: ${missing.join(', ')}`; continue; }
+        selected = Object.freeze({ kind, executable, ...(interpreter ? { interpreter } : {}), version: observed });
+        break;
+      } catch { if (signal?.aborted) throw signal.reason; }
+    }
+    result.push(Object.freeze(selected ?? { kind, available: false, reason }));
+  }
+  return Object.freeze(result);
+}

package/src/runtime/heartbeat.js

@@ -0,0 +1,47 @@
+const ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+export class HeartbeatError extends Error {
+  constructor(reason = 'invalid-heartbeat') {
+    super('Runtime heartbeat is invalid.');
+    this.name = 'HeartbeatError';
+    this.code = 'ERR_RUNTIME_HEARTBEAT';
+    this.safeMessage = this.message;
+    this.details = Object.freeze({ reason });
+  }
+}
+
+function fail(reason) { throw new HeartbeatError(reason); }
+function id(value) { if (typeof value !== 'string' || value.length > 64 || !ID.test(value)) fail('invalid-heartbeat'); return value; }
+
+function capture(input, keys) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) fail('invalid-heartbeat');
+  const own = Reflect.ownKeys(input);
+  if (own.length !== keys.length || own.some(key => typeof key !== 'string' || !keys.includes(key))) fail('invalid-heartbeat');
+  const result = {};
+  try { for (const key of own) result[key] = input[key]; } catch { fail('invalid-heartbeat'); }
+  return result;
+}
+
+export function createHeartbeat(input) {
+  try {
+    const value = capture(input, ['version', 'instanceId', 'nodeId', 'actorId', 'leaseId', 'sequence', 'timestampMs', 'intervalMs']);
+    if (value.version !== 1 || !Number.isSafeInteger(value.sequence) || value.sequence < 1
+      || !Number.isSafeInteger(value.timestampMs) || value.timestampMs < 0
+      || !Number.isSafeInteger(value.intervalMs) || value.intervalMs < 100 || value.intervalMs > 3_600_000) fail('invalid-heartbeat');
+    return Object.freeze({ version: 1, instanceId: id(value.instanceId), nodeId: id(value.nodeId), actorId: id(value.actorId), leaseId: id(value.leaseId), sequence: value.sequence, timestampMs: value.timestampMs, intervalMs: value.intervalMs });
+  } catch (error) { if (error instanceof HeartbeatError) throw error; fail('invalid-heartbeat'); }
+}
+
+export function heartbeatStatus(heartbeat, input) {
+  try {
+    const value = capture(input, ['nowMs', 'expected']);
+    const stable = createHeartbeat(heartbeat);
+    const expected = capture(value.expected, ['instanceId', 'nodeId', 'actorId', 'leaseId']);
+    if (!Number.isSafeInteger(value.nowMs) || value.nowMs < stable.timestampMs || value.nowMs > Number.MAX_SAFE_INTEGER
+      || stable.instanceId !== id(expected.instanceId) || stable.nodeId !== id(expected.nodeId)
+      || stable.actorId !== id(expected.actorId) || stable.leaseId !== id(expected.leaseId)) fail('heartbeat-binding');
+    const maximumAge = stable.intervalMs * 2;
+    if (!Number.isSafeInteger(maximumAge)) fail('invalid-heartbeat');
+    return Object.freeze({ status: value.nowMs - stable.timestampMs > maximumAge ? 'stalled' : 'alive', ageMs: value.nowMs - stable.timestampMs });
+  } catch (error) { if (error instanceof HeartbeatError) throw error; fail('invalid-heartbeat'); }
+}

package/src/runtime/instance-store.js

@@ -0,0 +1,112 @@
+import { basename } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+import { immutableJson } from '../clients/contract.js';
+import { acquireLock, LockBusyError } from '../state/lock.js';
+import { assertResolvedStatePaths } from '../state/paths.js';
+import { createSnapshotStore } from '../state/snapshot-store.js';
+
+const ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+export class RuntimeInstanceStoreError extends Error {
+  constructor(reason = 'invalid-instance') {
+    const messages = {
+      'invalid-instance': 'Runtime instance configuration is invalid.',
+      'lock-required': 'Runtime instance operation requires the acquired outer lock.',
+      'version-conflict': 'Runtime instance state version changed concurrently.',
+    };
+    super(messages[reason] ?? messages['invalid-instance']);
+    this.name = 'RuntimeInstanceStoreError';
+    this.code = reason === 'version-conflict' ? 'ERR_STATE_VERSION_CONFLICT' : `ERR_RUNTIME_INSTANCE_${reason.replaceAll('-', '_').toUpperCase()}`;
+    this.safeMessage = this.message;
+    this.details = Object.freeze({ reason });
+  }
+}
+
+function fail(reason) { throw new RuntimeInstanceStoreError(reason); }
+
+function capture(input) {
+  try {
+    if (!input || typeof input !== 'object' || Array.isArray(input)
+      || ![Object.prototype, null].includes(Object.getPrototypeOf(input))) fail('invalid-instance');
+    const allowed = new Set(['id', 'paths', 'initialState']);
+    const keys = Reflect.ownKeys(input);
+    if (keys.length !== 3 || keys.some(key => typeof key !== 'string' || !allowed.has(key))) fail('invalid-instance');
+    const result = Object.create(null);
+    for (const key of keys) {
+      const descriptor = Object.getOwnPropertyDescriptor(input, key);
+      if (!descriptor?.enumerable || !Object.hasOwn(descriptor, 'value')) fail('invalid-instance');
+      result[key] = descriptor.value;
+    }
+    return result;
+  } catch (error) {
+    if (error instanceof RuntimeInstanceStoreError) throw error;
+    fail('invalid-instance');
+  }
+}
+
+async function acquireOuter(path) {
+  const deadline = Date.now() + 2_000;
+  while (true) {
+    try { return await acquireLock(path); } catch (error) {
+      if (!(error instanceof LockBusyError) || Date.now() >= deadline) throw error;
+      await delay(5);
+    }
+  }
+}
+
+export function createRuntimeInstance(input) {
+  const value = capture(input);
+  if (typeof value.id !== 'string' || value.id.length > 64 || !ID.test(value.id)) fail('invalid-instance');
+  try { assertResolvedStatePaths(value.paths); } catch { fail('invalid-instance'); }
+  if (basename(value.paths.instanceDir) !== value.id
+    || typeof value.paths.runtimeLockPath !== 'string') fail('invalid-instance');
+  const initialState = immutableJson(value.initialState, 'invalid-contract');
+  if (!initialState || typeof initialState !== 'object' || Array.isArray(initialState)
+    || initialState.version !== 0) fail('invalid-instance');
+  const snapshots = createSnapshotStore(value.paths, { environment: {} });
+  let held = false;
+
+  async function rawSnapshot() {
+    let snapshot = await snapshots.read();
+    if (snapshot === null) snapshot = await snapshots.write(initialState, { expectedVersion: 0, environment: {} });
+    return snapshot;
+  }
+
+  return Object.freeze({
+    id: value.id,
+    async acquire() {
+      const outer = await acquireOuter(value.paths.runtimeLockPath);
+      held = true;
+      let released = false;
+      return Object.freeze({
+        async release() {
+          if (released) return;
+          await outer.release();
+          released = true;
+          held = false;
+        },
+      });
+    },
+    async read() {
+      if (!held) fail('lock-required');
+      return immutableJson((await rawSnapshot()).data, 'invalid-contract');
+    },
+    async commit(expectedVersion, nextState) {
+      if (!held) fail('lock-required');
+      if (!Number.isSafeInteger(expectedVersion) || expectedVersion < 0) fail('invalid-instance');
+      const next = immutableJson(nextState, 'invalid-contract');
+      if (!next || typeof next !== 'object' || Array.isArray(next)
+        || next.version !== expectedVersion + 1) fail('invalid-instance');
+      const current = await rawSnapshot();
+      if (current.data?.version !== expectedVersion) fail('version-conflict');
+      try {
+        const persisted = await snapshots.write(next, { expectedVersion: current.version, environment: {} });
+        return immutableJson(persisted.data, 'invalid-contract');
+      } catch (error) {
+        if (/state version conflict/i.test(error?.message ?? '')) fail('version-conflict');
+        throw error;
+      }
+    },
+  });
+}