@yemi33/minions 0.1.2381 → 0.1.2383

package/engine/restart-health.js

@@ -32,6 +32,14 @@ function readEngineControl(minionsHome) {
   }
 }
 
+function readSupervisorPid(minionsHome) {
+  try {
+    return normalizePid(fs.readFileSync(path.join(minionsHome, 'engine', 'supervisor.pid'), 'utf8').trim());
+  } catch {
+    return null;
+  }
+}
+
 function normalizePid(pid) {
   const n = Number(pid);
   return Number.isInteger(n) && n > 0 ? n : null;
@@ -122,7 +130,10 @@ async function checkRestartHealth(options = {}) {
     dashboardUrl,
     dashboardPid,
     dashboardPort = 7331,
+    expectedEnginePid,
+    supervisorPid,
     readControl = readEngineControl,
+    readSupervisorPid: readSupPid = readSupervisorPid,
     isProcessAlive: isAlive = isProcessAlive,
     isPortListening: portCheck = isPortListening,
     httpGetJson: getJson = httpGetJson,
@@ -130,8 +141,10 @@ async function checkRestartHealth(options = {}) {
 
   const control = readControl(minionsHome);
   const pid = normalizePid(control && control.pid);
+  const expectedEngine = normalizePid(expectedEnginePid);
   const engineAlive = pid ? isAlive(pid) : false;
-  const engineOk = control && control.state === 'running' && engineAlive;
+  const engineOwned = expectedEngine == null || pid === expectedEngine;
+  const engineOk = control && control.state === 'running' && engineAlive && engineOwned;
 
   // Two strategies for the dashboard check:
   //   1) Process + port-listening (preferred from `minions restart` since
@@ -196,11 +209,54 @@ async function checkRestartHealth(options = {}) {
     dashboardSnapshot = { kind: 'http', url, ok: !!(dashboard && dashboard.ok), statusCode: dashboard && dashboard.statusCode, status: dashboardStatus };
   }
 
+  let supervisorOk = true;
+  let supervisorSnapshot = null;
+  if (supervisorPid != null) {
+    const expectedSupervisor = normalizePid(supervisorPid);
+    const recordedSupervisor = normalizePid(readSupPid(minionsHome));
+    const supervisorAlive = expectedSupervisor ? isAlive(expectedSupervisor) : false;
+    supervisorOk = !!(expectedSupervisor && supervisorAlive && recordedSupervisor === expectedSupervisor);
+    supervisorSnapshot = {
+      pid: expectedSupervisor,
+      alive: supervisorAlive,
+      recordedPid: recordedSupervisor,
+      owned: recordedSupervisor === expectedSupervisor,
+    };
+  }
+
+  let topologyOk = true;
+  let topologySnapshot = null;
+  if (engineOk && dashboardOk && supervisorOk && options.requireExactTopology) {
+    const listPids = options.listProcessPids;
+    const scripts = options.topologyScripts || {};
+    if (typeof listPids !== 'function') {
+      topologyOk = false;
+      topologySnapshot = { error: 'process enumerator unavailable' };
+    } else {
+      const expected = {
+        engine: expectedEngine,
+        dashboard: normalizePid(dashboardPid),
+        supervisor: normalizePid(supervisorPid),
+      };
+      const actual = {};
+      for (const kind of ['engine', 'dashboard', 'supervisor']) {
+        try {
+          actual[kind] = [...new Set((listPids(scripts[kind]) || []).map(normalizePid).filter(Boolean))];
+        } catch {
+          actual[kind] = [];
+        }
+      }
+      topologyOk = Object.keys(expected).every(kind =>
+        expected[kind] != null && actual[kind].length === 1 && actual[kind][0] === expected[kind]);
+      topologySnapshot = { expected, actual };
+    }
+  }
+
   const errors = [];
   if (!engineOk) {
     const state = control && control.state ? control.state : 'unknown';
     const pidLabel = pid || 'none';
-    errors.push(`Engine is not healthy (state=${state}, pid=${pidLabel}, alive=${engineAlive ? 'yes' : 'no'})`);
+    errors.push(`Engine is not healthy (state=${state}, pid=${pidLabel}, alive=${engineAlive ? 'yes' : 'no'}, owned=${engineOwned ? 'yes' : 'no'})`);
   }
   if (!dashboardOk) {
     const where = dashboardKind === 'http'
@@ -208,11 +264,19 @@ async function checkRestartHealth(options = {}) {
       : `dashboard pid=${normalizePid(dashboardPid) || 'none'} port=${dashboardPort}`;
     errors.push(`Dashboard failed health check at ${where} (${dashboardDetail})`);
   }
+  if (!supervisorOk) {
+    errors.push(`Supervisor is not healthy (pid=${supervisorSnapshot.pid || 'none'}, alive=${supervisorSnapshot.alive ? 'yes' : 'no'}, recordedPid=${supervisorSnapshot.recordedPid || 'none'}, owned=${supervisorSnapshot.owned ? 'yes' : 'no'})`);
+  }
+  if (!topologyOk) {
+    errors.push(`Minions process topology is not exclusive (${JSON.stringify(topologySnapshot)})`);
+  }
 
   return {
-    ok: engineOk && dashboardOk,
-    engine: { state: control && control.state, pid, alive: engineAlive },
+    ok: engineOk && dashboardOk && supervisorOk && topologyOk,
+    engine: { state: control && control.state, pid, alive: engineAlive, owned: engineOwned },
     dashboard: dashboardSnapshot,
+    supervisor: supervisorSnapshot,
+    topology: topologySnapshot,
     errors,
   };
 }
@@ -310,6 +374,7 @@ module.exports = {
     isProcessAlive,
     isPortListening,
     readEngineControl,
+    readSupervisorPid,
     normalizePid,
   },
 };

package/engine/runtimes/claude.js

@@ -6,23 +6,9 @@
  * everything Claude-CLI-specific: binary resolution, arg construction, prompt
  * preparation, output parsing, and error normalization.
  *
- * Adapter contract (all runtimes must implement):
- *   - name: string
- *   - capabilities: { ... } feature flags consumed by engine code
- *   - resolveBinary() → { bin, native, leadingArgs }
- *   - capsFile: absolute path of the binary-resolution cache for this runtime
- *   - listModels() → Promise<{id,name,provider}[] | null>
- *   - modelsCache: absolute path of the model-list cache for this runtime
- *   - spawnScript: absolute path of the spawn wrapper (or null if direct-only)
- *   - buildArgs(opts) → string[] — CLI args excluding the binary
- *   - buildPrompt(promptText, sysPromptText) → string — final prompt delivered
- *   - getUserAssetDirs(opts) → string[] — runtime-native global asset roots
- *   - getSkillRoots(opts) → {scope,dir,projectName?}[] — skill discovery roots
- *   - getSkillWriteTargets(opts) → {personal,project} — extraction targets
- *   - resolveModel(input) → string|undefined — shorthand expansion / passthrough
- *   - parseOutput(raw) → { text, usage, sessionId, model }
- *   - parseStreamChunk(line) → parsed event object or null
- *   - parseError(rawOutput) → { message, code, retriable }
+ * The versioned adapter contract and compatibility defaults live in
+ * engine/runtimes/contract.js. Keep harness-specific argv, prompt, parser,
+ * workspace, and persistent-worker behavior in this module.
  */
 
 const fs = require('fs');
@@ -36,6 +22,8 @@ const MINIONS_DIR = path.resolve(ENGINE_DIR, '..');
 const _CACHE_DIR = resolveEngineCacheDir(ENGINE_DIR);
 
 const isWin = process.platform === 'win32';
+const RUNTIME_NAME = 'claude';
+const SPAWN_STARTUP_SUBTYPES = new Set(['init', 'hook_started', 'hook_response']);
 
 // ── Binary Resolution ────────────────────────────────────────────────────────
 // Mirrors engine/spawn-agent.js:26-91. Cached at engine/claude-caps.json so the
@@ -253,7 +241,7 @@ function buildArgs(opts = {}) {
 }
 
 function buildSpawnFlags(opts = {}) {
-  const flags = ['--runtime', 'claude'];
+  const flags = ['--runtime', RUNTIME_NAME];
   if (opts.maxTurns != null) flags.push('--max-turns', String(opts.maxTurns));
   if (opts.model) flags.push('--model', String(opts.model));
   if (opts.allowedTools) flags.push('--allowedTools', String(opts.allowedTools));
@@ -268,12 +256,13 @@ function buildSpawnFlags(opts = {}) {
   return flags;
 }
 
-// Stamped into every session.json this adapter writes so the pre-spawn resume
-// path can detect "session was produced by a different runtime" — Claude
-// rejects Copilot session IDs (and vice versa) with "No conversation found",
-// which would otherwise burn a retry slot before the post-failure cleanup at
-// engine.js:1195 fires. See W-mot9fwya000d09cb.
-const RUNTIME_NAME = 'claude';
+function resolveInvocationOptions({ options = {}, engineConfig = {} } = {}) {
+  const resolved = { ...options };
+  if (resolved.fallbackModel == null && engineConfig.claudeFallbackModel) {
+    resolved.fallbackModel = engineConfig.claudeFallbackModel;
+  }
+  return resolved;
+}
 
 /**
  * Compute the directory Claude CLI uses to persist a project's conversation
@@ -838,6 +827,12 @@ const capabilities = {
   budgetCap: true,
   // Supports `--bare` (suppress CLAUDE.md auto-discovery)
   bareMode: true,
+  // The Claude Code CLI reads repo-authored CLAUDE.md files itself at startup
+  // (unless `--bare`). TRUE here tells the engine's CLAUDE.md-propagation layer
+  // (engine/claude-md-context.js, injected in engine/playbook.js) to SKIP this
+  // runtime — re-injecting CLAUDE.md content into the prompt would double it.
+  // Copilot/Codex set this false because they have no native CLAUDE.md auto-load.
+  claudeMdNativeDiscovery: true,
   // Supports `--fallback-model <id>`
   fallbackModel: true,
   // Engine controls session persistence (writes session.json on completion)
@@ -928,6 +923,81 @@ function getMcpConfigPaths({ homeDir = os.homedir(), project = null } = {}) {
   return paths;
 }
 
+function prepareWorkspace({
+  worktreePath,
+  homeDir,
+  engineConfig,
+  mutateJsonFileLocked,
+  existsSync = fs.existsSync,
+  readFileSync = fs.readFileSync,
+} = {}) {
+  if (engineConfig && engineConfig.claudePreApproveWorkspaceMcps === false) {
+    return { wrote: false, reason: 'flag-off', servers: [] };
+  }
+  if (!worktreePath || typeof worktreePath !== 'string') {
+    return { wrote: false, reason: 'no-worktree', servers: [] };
+  }
+  const workspaceMcpPath = path.join(worktreePath, '.mcp.json');
+  if (!existsSync(workspaceMcpPath)) {
+    return { wrote: false, reason: 'no-workspace-mcp', servers: [] };
+  }
+  let workspaceMcp;
+  try {
+    workspaceMcp = JSON.parse(readFileSync(workspaceMcpPath, 'utf8'));
+  } catch {
+    return { wrote: false, reason: 'invalid-workspace-mcp', servers: [] };
+  }
+  const serversObj = workspaceMcp && typeof workspaceMcp === 'object' ? workspaceMcp.mcpServers : null;
+  const servers = serversObj && typeof serversObj === 'object' && !Array.isArray(serversObj)
+    ? Object.keys(serversObj).filter(name => typeof name === 'string' && name.length > 0)
+    : [];
+  if (servers.length === 0) {
+    return { wrote: false, reason: 'no-servers', servers: [] };
+  }
+  if (!homeDir || typeof mutateJsonFileLocked !== 'function') {
+    return { wrote: false, reason: 'no-home-or-mutator', servers };
+  }
+
+  const claudeJsonPath = path.join(homeDir, '.claude.json');
+  let didWrite = false;
+  mutateJsonFileLocked(claudeJsonPath, (data) => {
+    const root = data && typeof data === 'object' ? data : {};
+    if (!root.projects || typeof root.projects !== 'object') root.projects = {};
+    const projectState = root.projects[worktreePath] && typeof root.projects[worktreePath] === 'object'
+      ? root.projects[worktreePath]
+      : {};
+    const enabled = Array.isArray(projectState.enabledMcpjsonServers)
+      ? projectState.enabledMcpjsonServers.slice()
+      : [];
+    const disabled = Array.isArray(projectState.disabledMcpjsonServers)
+      ? projectState.disabledMcpjsonServers.slice()
+      : [];
+    const enabledSet = new Set(enabled.filter(name => typeof name === 'string'));
+    let mutated = false;
+    for (const name of servers) {
+      if (!enabledSet.has(name)) {
+        enabledSet.add(name);
+        mutated = true;
+      }
+    }
+    const nextDisabled = disabled.filter(name => typeof name === 'string' && !servers.includes(name));
+    if (nextDisabled.length !== disabled.length) mutated = true;
+    if (!mutated) return data;
+    projectState.enabledMcpjsonServers = [...enabledSet];
+    projectState.disabledMcpjsonServers = nextDisabled;
+    root.projects[worktreePath] = projectState;
+    didWrite = true;
+    return root;
+  }, { defaultValue: {}, skipWriteIfUnchanged: true });
+
+  return { wrote: didWrite, reason: 'ok', servers, target: claudeJsonPath };
+}
+
+function isSpawnStartupEvent(event) {
+  if (!event || event.type !== 'system') return false;
+  return SPAWN_STARTUP_SUBTYPES.has(typeof event.subtype === 'string' ? event.subtype : '');
+}
+
 // Heuristic: does `model` look like a Claude model identifier? Powers the
 // preflight "stale model after CLI switch" warning in cli.js. Returning false
 // means "this looks wrong for Claude" — gpt-5.4 / o3-* / codex etc. Keep this
@@ -942,7 +1012,8 @@ function modelLooksFamiliar(model) {
 }
 
 module.exports = {
-  name: 'claude',
+  apiVersion: 1,
+  name: RUNTIME_NAME,
   capabilities,
   resolveBinary,
   capsFile: CAPS_FILE,
@@ -950,6 +1021,7 @@ module.exports = {
   modelsCache: MODELS_CACHE,
   spawnScript: path.join(ENGINE_DIR, 'spawn-agent.js'),
   installHint: INSTALL_HINT,
+  resolveInvocationOptions,
   buildSpawnFlags,
   buildArgs,
   buildPrompt,
@@ -958,6 +1030,8 @@ module.exports = {
   getSkillWriteTargets,
   getCommandRoots,
   getMcpConfigPaths,
+  prepareWorkspace,
+  isSpawnStartupEvent,
   getResumeSessionId,
   saveSession,
   detectPermissionGate,
@@ -975,4 +1049,5 @@ module.exports = {
   _CLAUDE_SHORTHANDS,
   _extractInvalidModelName,
   THINKING_BLOCK_TYPES,
+  SPAWN_STARTUP_SUBTYPES,
 };

package/engine/runtimes/codex.js

@@ -840,6 +840,20 @@ function getModelCacheKey({ env = process.env, timeoutMs = 10000 } = {}) {
   }
 }
 
+function getModelCacheKey({ env = process.env, timeoutMs = 10000 } = {}) {
+  const resolved = resolveBinary({ env });
+  if (!resolved) return null;
+  try {
+    return _execFileCapture(resolved.bin, [...(resolved.leadingArgs || []), '--version'], {
+      env,
+      timeoutMs,
+      native: resolved.native,
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
 function createStreamConsumer(ctx) {
   let deltaText = '';
   let terminalText = '';
@@ -901,6 +915,10 @@ const capabilities = {
   budgetCap: false,
   bareMode: false,
   fallbackModel: false,
+  // Codex has no native CLAUDE.md auto-load — FALSE opts it into the engine's
+  // CLAUDE.md-propagation layer (engine/claude-md-context.js) so repo-authored
+  // CLAUDE.md guidance reaches the agent prompt.
+  claudeMdNativeDiscovery: false,
   sessionPersistenceControl: false,
   resumePromptCarryover: true,
   streamConsumer: true,
@@ -911,6 +929,7 @@ const INSTALL_HINT = 'install Codex CLI with `npm install -g @openai/codex` or `
 const PERMISSION_BYPASS_FLAGS = ['--sandbox'];
 
 module.exports = {
+  apiVersion: 1,
   name: RUNTIME_NAME,
   capabilities,
   resolveBinary,

package/engine/runtimes/contract.js

@@ -0,0 +1,239 @@
+'use strict';
+
+const ADAPTER_API_VERSION = 1;
+const RUNTIME_OPTIONS_FLAG = '--runtime-options';
+const RUNTIME_IMAGES_FILE_OPTION = '_minionsImagesFile';
+const legacyAdapters = new WeakSet();
+
+const CORE_METHODS = Object.freeze([
+  'resolveBinary',
+  'listModels',
+  'buildArgs',
+  'buildPrompt',
+  'resolveModel',
+  'parseOutput',
+  'parseStreamChunk',
+  'parseError',
+]);
+
+function normalizeRuntimeAdapter(name, adapter, { strict = false } = {}) {
+  if (!name || typeof name !== 'string') {
+    throw new Error('registerRuntime: name must be a non-empty string');
+  }
+  if (!adapter || typeof adapter !== 'object' || Array.isArray(adapter)) {
+    throw new Error('registerRuntime: adapter must be an object');
+  }
+  if (adapter.name != null && adapter.name !== name) {
+    throw new Error(`registerRuntime: adapter name "${adapter.name}" does not match registry key "${name}"`);
+  }
+  const hasExplicitApiVersion = adapter.apiVersion != null;
+  if (strict && !hasExplicitApiVersion) {
+    throw new Error(`Runtime "${name}" adapter must declare apiVersion ${ADAPTER_API_VERSION}`);
+  }
+  if (hasExplicitApiVersion && adapter.apiVersion !== ADAPTER_API_VERSION) {
+    throw new Error(
+      `Runtime "${name}" adapter API version ${adapter.apiVersion} is unsupported; expected ${ADAPTER_API_VERSION}`
+    );
+  }
+
+  adapter.name = name;
+  adapter.apiVersion = ADAPTER_API_VERSION;
+  if (!hasExplicitApiVersion) legacyAdapters.add(adapter);
+  if (adapter.capabilities == null) {
+    adapter.capabilities = {};
+  } else if (typeof adapter.capabilities !== 'object' || Array.isArray(adapter.capabilities)) {
+    throw new Error(`Runtime "${name}" adapter member capabilities must be an object`);
+  }
+
+  for (const method of CORE_METHODS) {
+    if (adapter[method] != null && typeof adapter[method] !== 'function') {
+      throw new Error(`Runtime "${name}" adapter member ${method} must be a function`);
+    }
+    if (strict && typeof adapter[method] !== 'function') {
+      throw new Error(`Runtime "${name}" adapter is missing required method ${method}()`);
+    }
+  }
+
+  if (adapter.capabilities.streamConsumer === true && typeof adapter.createStreamConsumer !== 'function') {
+    throw new Error(`Runtime "${name}" declares streamConsumer but does not implement createStreamConsumer()`);
+  }
+  if (adapter.capabilities.acpWorkerPool === true) {
+    for (const method of ['buildWorkerArgs', 'encodePooledOutput']) {
+      if (typeof adapter[method] !== 'function') {
+        throw new Error(`Runtime "${name}" declares acpWorkerPool but does not implement ${method}()`);
+      }
+    }
+  }
+  return adapter;
+}
+
+function sanitizeInvocationOptions(runtime, options = {}) {
+  const caps = runtime?.capabilities || {};
+  const sanitized = { ...(options || {}) };
+  if (!caps.effortLevels) delete sanitized.effort;
+  if (!caps.sessionResume
+      || typeof sanitized.sessionId !== 'string'
+      || !sanitized.sessionId.trim()) {
+    delete sanitized.sessionId;
+  } else {
+    sanitized.sessionId = sanitized.sessionId.trim();
+  }
+  if (!caps.budgetCap) delete sanitized.maxBudget;
+  if (!caps.bareMode) delete sanitized.bare;
+  if (!caps.fallbackModel) delete sanitized.fallbackModel;
+  if (!caps.imageInput) {
+    delete sanitized.images;
+    delete sanitized[RUNTIME_IMAGES_FILE_OPTION];
+  }
+  return sanitized;
+}
+
+function resolveInvocationOptions(runtime, options = {}, context = {}) {
+  if (!runtime || typeof runtime !== 'object') throw new Error('resolveInvocationOptions: runtime adapter is required');
+  let resolved = { ...(options || {}) };
+  if (typeof runtime.resolveInvocationOptions === 'function') {
+    resolved = runtime.resolveInvocationOptions({
+      ...context,
+      options: resolved,
+    });
+  }
+  if (!resolved || typeof resolved !== 'object' || Array.isArray(resolved)) {
+    throw new Error(`Runtime "${runtime.name}" resolveInvocationOptions() must return an object`);
+  }
+  return sanitizeInvocationOptions(runtime, resolved);
+}
+
+function encodeRuntimeOptions(options = {}) {
+  return Buffer.from(JSON.stringify(options || {}), 'utf8').toString('base64url');
+}
+
+function decodeRuntimeOptions(encoded) {
+  if (typeof encoded !== 'string' || !encoded) {
+    throw new Error(`${RUNTIME_OPTIONS_FLAG} requires a non-empty base64url value`);
+  }
+  let decoded;
+  try {
+    decoded = JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8'));
+  } catch (err) {
+    throw new Error(`Invalid ${RUNTIME_OPTIONS_FLAG} payload: ${err.message}`);
+  }
+  if (!decoded || typeof decoded !== 'object' || Array.isArray(decoded)) {
+    throw new Error(`Invalid ${RUNTIME_OPTIONS_FLAG} payload: expected a JSON object`);
+  }
+  for (const key of ['__proto__', 'prototype', 'constructor']) {
+    if (Object.prototype.hasOwnProperty.call(decoded, key)) {
+      throw new Error(`Invalid ${RUNTIME_OPTIONS_FLAG} payload: forbidden key "${key}"`);
+    }
+  }
+  return decoded;
+}
+
+function buildSpawnFlags(runtime, options = {}) {
+  if (!runtime || typeof runtime !== 'object') throw new Error('buildSpawnFlags: runtime adapter is required');
+  const isLegacy = runtime.apiVersion !== ADAPTER_API_VERSION || legacyAdapters.has(runtime);
+  if (isLegacy && typeof runtime.buildSpawnFlags === 'function') {
+    const legacyFlags = runtime.buildSpawnFlags(options || {});
+    if (!Array.isArray(legacyFlags) || legacyFlags.some(flag => typeof flag !== 'string')) {
+      throw new Error(`Runtime "${runtime.name}" buildSpawnFlags() must return string[]`);
+    }
+    return legacyFlags;
+  }
+
+  const sanitized = sanitizeInvocationOptions(runtime, options);
+  let flags;
+  if (typeof runtime.buildSpawnFlags === 'function') {
+    flags = runtime.buildSpawnFlags(sanitized);
+  } else {
+    const caps = runtime.capabilities || {};
+    flags = ['--runtime', String(runtime.name)];
+    if (sanitized.maxTurns != null) flags.push('--max-turns', String(sanitized.maxTurns));
+    if (sanitized.model) flags.push('--model', String(sanitized.model));
+    if (sanitized.allowedTools) flags.push('--allowedTools', String(sanitized.allowedTools));
+    if (caps.effortLevels && sanitized.effort) flags.push('--effort', String(sanitized.effort));
+    if (caps.sessionResume && sanitized.sessionId) flags.push('--resume', String(sanitized.sessionId));
+    if (caps.budgetCap && sanitized.maxBudget != null) flags.push('--max-budget-usd', String(sanitized.maxBudget));
+    if (caps.bareMode && sanitized.bare === true) flags.push('--bare');
+    if (caps.fallbackModel && sanitized.fallbackModel) {
+      flags.push('--fallback-model', String(sanitized.fallbackModel));
+    }
+    if (sanitized.stream === 'on' || sanitized.stream === 'off') {
+      flags.push('--stream', sanitized.stream);
+    }
+    if (sanitized.disableBuiltinMcps === true) flags.push('--disable-builtin-mcps');
+    if (sanitized.reasoningSummaries === true) flags.push('--enable-reasoning-summaries');
+  }
+  if (!Array.isArray(flags) || flags.some(flag => typeof flag !== 'string')) {
+    throw new Error(`Runtime "${runtime.name}" buildSpawnFlags() must return string[]`);
+  }
+  if (flags[0] !== '--runtime') flags = ['--runtime', String(runtime.name), ...flags];
+  if (flags[1] !== runtime.name) {
+    throw new Error(`Runtime "${runtime.name}" buildSpawnFlags() emitted mismatched runtime "${flags[1]}"`);
+  }
+  if (isLegacy) return flags;
+  return [...flags, RUNTIME_OPTIONS_FLAG, encodeRuntimeOptions(sanitized)];
+}
+
+function prepareWorkspace(runtime, context = {}) {
+  if (!runtime || typeof runtime.prepareWorkspace !== 'function') {
+    return { wrote: false, reason: 'unsupported-runtime', servers: [] };
+  }
+  return runtime.prepareWorkspace(context);
+}
+
+function isSpawnStartupEvent(runtime, event) {
+  if (!runtime || typeof runtime.isSpawnStartupEvent !== 'function') return false;
+  try {
+    return runtime.isSpawnStartupEvent(event) === true;
+  } catch {
+    return false;
+  }
+}
+
+function shouldSuppressPostMutationError(runtime, context = {}) {
+  if (!runtime || typeof runtime.shouldSuppressPostMutationError !== 'function') return false;
+  try {
+    return runtime.shouldSuppressPostMutationError(context) === true;
+  } catch {
+    return false;
+  }
+}
+
+function buildWorkerArgs(runtime, options = {}) {
+  if (runtime?.capabilities?.acpWorkerPool !== true) {
+    throw new Error(`Runtime "${runtime?.name || '<unknown>'}" does not support persistent ACP workers`);
+  }
+  const args = runtime.buildWorkerArgs(options);
+  if (!Array.isArray(args) || args.some(arg => typeof arg !== 'string')) {
+    throw new Error(`Runtime "${runtime.name}" buildWorkerArgs() must return string[]`);
+  }
+  return args;
+}
+
+function encodePooledOutput(runtime, event) {
+  if (runtime?.capabilities?.acpWorkerPool !== true) {
+    throw new Error(`Runtime "${runtime?.name || '<unknown>'}" does not support pooled output`);
+  }
+  const encoded = runtime.encodePooledOutput(event);
+  if (typeof encoded !== 'string') {
+    throw new Error(`Runtime "${runtime.name}" encodePooledOutput() must return a string`);
+  }
+  return encoded;
+}
+
+module.exports = {
+  ADAPTER_API_VERSION,
+  RUNTIME_OPTIONS_FLAG,
+  RUNTIME_IMAGES_FILE_OPTION,
+  CORE_METHODS,
+  normalizeRuntimeAdapter,
+  sanitizeInvocationOptions,
+  resolveInvocationOptions,
+  encodeRuntimeOptions,
+  decodeRuntimeOptions,
+  buildSpawnFlags,
+  prepareWorkspace,
+  isSpawnStartupEvent,
+  shouldSuppressPostMutationError,
+  buildWorkerArgs,
+  encodePooledOutput,
+};