@magnusekdahl/parallix 1.0.0

package/lib/agents/codex.js

@@ -0,0 +1,219 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnAndTee } = require('../core/spawn-tee');
+const { extractCodexTelemetry } = require('./codex-telemetry');
+const sessions = require('../tools/sessions');
+
+// Injectable I/O for tests. Production uses the real spawn-tee / export capture.
+let _spawnAndTee = spawnAndTee;
+let _sessions = sessions;
+
+// Test hooks: override the launcher's I/O without touching the public signature.
+function __setSpawnAndTeeForTest(fn) { _spawnAndTee = fn || spawnAndTee; }
+function __setSessionsForTest(mod) { _sessions = mod || sessions; }
+
+// Codex outputs "To continue this session, run codex resume <id>" at the end.
+// Also captures the session ID from the "Interaction Summary" block.
+const CODEX_SESSION_ID_RE = /codex\s+resume\s+([0-9a-f-]+)/i;
+const CODEX_SESSION_ID_ALT_RE = /Session ID:\s*([0-9a-f-]+)/i;
+
+function extractCodexSessionId(stdout) {
+  if (!stdout) return null;
+  const m = CODEX_SESSION_ID_RE.exec(stdout);
+  if (m) return m[1];
+  const m2 = CODEX_SESSION_ID_ALT_RE.exec(stdout);
+  if (m2) return m2[1];
+  return null;
+}
+
+function resolveCodexCommand() {
+  return 'codex';
+}
+
+function hasLiveTty() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+function buildCodexDraftInvocation({ prompt, worktree, interactive = hasLiveTty(), env = {}, resume = false, sessionId = null, model = null }) {
+  if (resume) {
+    const args = ['exec', 'resume'];
+    if (sessionId) {
+      args.push(sessionId);
+    } else {
+      args.push('--last');
+    }
+    if (model) args.push('-m', model);
+    args.push(prompt);
+    return {
+      command: resolveCodexCommand(),
+      args,
+      options: {
+        stdio: 'inherit',
+        cwd: worktree,
+        env: { ...process.env, ...env, HOME: codexHomeRoot(worktree) }
+      }
+    };
+  }
+
+  const modelArgs = model ? ['-m', model] : [];
+  const args = interactive
+    ? ['--full-auto', ...modelArgs, '--cd', worktree, prompt]
+    : ['exec', '--sandbox', 'danger-full-access', ...modelArgs, '--cd', worktree, prompt];
+
+  const baseEnv = { ...process.env };
+  if (!interactive) {
+    baseEnv.HOME = codexHomeRoot(worktree);
+  }
+
+  return {
+    command: resolveCodexCommand(),
+    args,
+    options: {
+      stdio: 'inherit',
+      cwd: worktree,
+      env: { ...baseEnv, ...env }
+    }
+  };
+}
+
+function startCodexDraftAgent({ prompt, worktree, env = {}, resume = false, sessionId = null, model = null, teeOptions = {}, slug = null, role = null }) {
+  // The launcher always tees through spawnAndTee for limit-hit detection, which
+  // forces child stdio to ['inherit', 'pipe', 'pipe']. Codex's `--full-auto`
+  // interactive UI requires a TTY on stdout, so we always use the headless
+  // `exec` path here regardless of whether the parent has a TTY.
+  ensureCodexHome(worktree);
+
+  function isStaleSessionResult(result) {
+    if (!result) return false;
+    const stderr = result.stderr || '';
+    const stdout = result.stdout || '';
+    return (stderr.includes('Session not found') || stdout.includes('Session not found'));
+  }
+
+  function processResult(result) {
+    if (result && result.stdout) {
+      result.sessionId = extractCodexSessionId(result.stdout);
+    }
+    if (result) {
+      // Real usage telemetry comes from the codex rollout JSONL written under the
+      // worktree-scoped codex-home, not the stdout stream (see codex-telemetry.js).
+      try {
+        const telemetry = extractCodexTelemetry(codexHomeRoot(worktree), { sinceMs: Date.now() });
+        if (telemetry) {
+          result.telemetry = telemetry;
+          if (telemetry.model) result.model = telemetry.model;
+          if (telemetry.provider) result.provider = telemetry.provider;
+        }
+      } catch (_) {
+        // Telemetry is best-effort; never let it break the launch result.
+      }
+    }
+    return result;
+  }
+
+  function staleSessionHandler(invocation) {
+    return _spawnAndTee(invocation.command, invocation.args, { ...invocation.options, ...teeOptions })
+      .then(result => {
+        if (isStaleSessionResult(result) && worktree && resume) {
+          try {
+            _sessions.clearSession(worktree, slug, role);
+          } catch (_) { /* best-effort */ }
+          const freshInv = buildCodexDraftInvocation({ prompt, worktree, interactive: false, env, resume: false, sessionId: null, model });
+          return _spawnAndTee(freshInv.command, freshInv.args, { ...freshInv.options, ...teeOptions });
+        }
+        return result;
+      })
+      .then(processResult);
+  }
+
+  const startedMs = Date.now();
+  const invocation = buildCodexDraftInvocation({ prompt, worktree, interactive: false, env, resume, sessionId, model });
+  const resultPromise = staleSessionHandler(invocation);
+
+  return { invocation, resultPromise };
+}
+
+function codexHomeRoot(worktree) {
+  return path.join(worktree, '.workflow', 'codex-home');
+}
+
+function codexConfigPath(worktree) {
+  return path.join(codexHomeRoot(worktree), '.codex', 'config.toml');
+}
+
+function codexAuthPath(worktree) {
+  return path.join(codexHomeRoot(worktree), '.codex', 'auth.json');
+}
+
+function userCodexAuthPath() {
+  return path.join(os.homedir(), '.codex', 'auth.json');
+}
+
+function tomlString(value) {
+  return `"${String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+// Graphify's Codex skill requires multi_agent = true for spawn_agent subagent
+// dispatch (skill-codex.md line 233). Without this, the copied Graphify skill
+// cannot launch semantic extraction subagents and parallel graph building fails.
+function headlessCodexConfig(worktree) {
+  const worktreeParent = path.dirname(path.resolve(worktree));
+  return [
+    'sandbox_mode = "danger-full-access"',
+    '',
+    '[features]',
+    'multi_agent = true',
+    '',
+    `[projects.${tomlString(worktreeParent)}]`,
+    'trust_level = "trusted"',
+    'approval_policy = "never"',
+    '',
+    `[projects.${tomlString(path.resolve(worktree))}]`,
+    'trust_level = "trusted"',
+    'approval_policy = "never"',
+    ''
+  ].join('\n');
+}
+
+function ensureCodexHome(worktree) {
+  fs.mkdirSync(codexHomeRoot(worktree), { recursive: true });
+  fs.mkdirSync(path.dirname(codexConfigPath(worktree)), { recursive: true });
+  fs.writeFileSync(codexConfigPath(worktree), headlessCodexConfig(worktree), 'utf8');
+
+  const sourceAuthPath = userCodexAuthPath();
+  if (fs.existsSync(sourceAuthPath)) {
+    fs.copyFileSync(sourceAuthPath, codexAuthPath(worktree));
+  }
+
+  // Seed the globally-installed Graphify skill into the isolated worktree HOME,
+  // the same way auth.json is carried over from the operator's real home. Codex
+  // runs with HOME=codexHomeRoot, so it looks for skills under
+  // <home>/.agents/skills; without this copy the one-time global install at
+  // ~/.agents/skills is invisible to codex. This is a plain filesystem copy of
+  // an existing install, not a `graphify install` invocation, and skips cleanly
+  // when the skill is absent.
+  const sourceSkillPath = path.join(os.homedir(), '.agents', 'skills', 'graphify');
+  if (fs.existsSync(sourceSkillPath)) {
+    fs.cpSync(
+      sourceSkillPath,
+      path.join(codexHomeRoot(worktree), '.agents', 'skills', 'graphify'),
+      { recursive: true }
+    );
+  }
+}
+
+module.exports = {
+  codexAuthPath,
+  buildCodexDraftInvocation,
+  codexConfigPath,
+  codexHomeRoot,
+  ensureCodexHome,
+  extractCodexSessionId,
+  extractCodexTelemetry,
+  headlessCodexConfig,
+  resolveCodexCommand,
+  startCodexDraftAgent,
+  __setSpawnAndTeeForTest,
+  __setSessionsForTest
+};

package/lib/agents/limit-hit.js

@@ -0,0 +1,252 @@
+'use strict';
+
+const DEFAULT_FALLBACK_HOURS = 1;
+const SIGINT_SHORT_BLOCK_MINUTES = 15;
+
+const PATTERN_SETS = Object.freeze({
+  claude: [
+    /claude (?:ai )?usage limit reached/i,
+    /\b5-hour limit (?:reached|exceeded)\b/i,
+    /you(?:'|')?ve hit your limit(?:\b|$)/i,
+    /you(?:'|')?ve hit your (?:weekly|daily|monthly|usage) limit/i,
+    /(?:usage|rate)\s*limit (?:has been )?(?:reached|exceeded)/i,
+    /\b429\b[^\n]*?\b(?:rate|usage|quota)\b/i
+  ],
+  codex: [
+    /you(?:'|’)?ve hit your (?:weekly|daily|monthly|usage) limit/i,
+    /\brate[_ ]?limit(?:_| )?(?:exceeded|reached)\b/i,
+    /\bweekly (?:codex )?usage limit\b/i,
+    /\b429\b[^\n]*?\b(?:rate|quota|usage)\b/i,
+    /resource_exhausted/i
+  ],
+
+  qwen: [
+    /\b(?:rate|usage|quota)\s*limit\s*(?:reached|exceeded)\b/i,
+    /\b429\b[^\n]*?\b(?:rate|quota|usage)\b/i,
+    /\b429\b/i,
+    /\binsufficient[_ ]quota\b/i
+  ],
+  mistral: [
+    /\bmistral (?:ai )?usage limit reached/i,
+    /\bmistral (?:ai )?quota exceeded/i,
+    /\bmistral (?:ai )?rate limit(?: reached| exceeded)/i,
+    /you(?:'|')?ve hit your (?:mistral|vibe) (?:weekly|daily|monthly|usage) limit/i,
+    /\b429\b[^\n]*?\b(?:rate|quota|usage)\b/i,
+    /\bvibe\b[^\n]*?\b(?:quota exceeded|rate limit exceeded)\b/i,
+    /\bmistral\b[^\n]*?\b(?:quota exceeded|rate limit exceeded)\b/i,
+    /\bresource[_ ]has[_ ]been[_ ]exhausted\b/i,
+    /\bresource_exhausted\b/i
+  ]
+});
+
+function getPatternsForAgent(agent) {
+  return PATTERN_SETS[agent] || [];
+}
+
+function findLimitHitMatch(agent, text) {
+  const patterns = getPatternsForAgent(agent);
+  for (const pattern of patterns) {
+    const match = pattern.exec(text);
+    if (match) {
+      return { pattern, index: match.index, length: match[0].length };
+    }
+  }
+  return null;
+}
+
+function clipContext(text, index, length) {
+  const before = Math.max(0, index - 200);
+  const after = Math.min(text.length, index + length + 200);
+  return text.slice(before, after);
+}
+
+const ISO_PATTERN = /(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?(?:\.\d+)?(Z|[+-]\d{2}:?\d{2})?/;
+const TWELVE_HOUR_PATTERN = /\b(\d{1,2})(?::(\d{2}))?\s*(am|pm|AM|PM)\b/;
+const TWENTY_FOUR_HOUR_PATTERN = /\b([01]?\d|2[0-3]):([0-5]\d)\b/;
+const RELATIVE_PATTERN = /\bin\s+(\d+)\s+(hour|hours|minute|minutes|second|seconds)\b/i;
+const RETRY_AFTER_PATTERN = /retry[- ]?after[:\s]+(\d+)\s*(seconds?|s|minutes?|m)?/i;
+const RETRY_AT_DATE_PATTERN = /(?:retry|reset|try again|reset(?:s)? at)[^\n]{0,40}?(\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2})?(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)/i;
+
+function parseIsoOffset(value) {
+  if (!value) return null;
+  if (value === 'Z') return 0;
+  const m = /([+-])(\d{2}):?(\d{2})/.exec(value);
+  if (!m) return null;
+  const sign = m[1] === '-' ? -1 : 1;
+  return sign * (Number(m[2]) * 60 + Number(m[3]));
+}
+
+function parseIso(text) {
+  const m = ISO_PATTERN.exec(text);
+  if (!m) return null;
+  const [, year, month, day, hour, minute, second, offset] = m;
+  const offsetMinutes = parseIsoOffset(offset);
+  if (offsetMinutes === null) {
+    return new Date(Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second || 0), 0);
+  }
+  const utcMs = Date.UTC(Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second || 0), 0);
+  return new Date(utcMs - offsetMinutes * 60 * 1000);
+}
+
+function parseTwelveHour(text, now) {
+  const m = TWELVE_HOUR_PATTERN.exec(text);
+  if (!m) return null;
+  let hour = Number(m[1]);
+  const minute = Number(m[2] || 0);
+  const meridiem = m[3].toLowerCase();
+  if (hour < 1 || hour > 12) return null;
+  if (meridiem === 'pm' && hour !== 12) hour += 12;
+  if (meridiem === 'am' && hour === 12) hour = 0;
+  return projectClockTime(now, hour, minute);
+}
+
+function parseTwentyFourHour(text, now) {
+  const m = TWENTY_FOUR_HOUR_PATTERN.exec(text);
+  if (!m) return null;
+  const hour = Number(m[1]);
+  const minute = Number(m[2]);
+  return projectClockTime(now, hour, minute);
+}
+
+function parseRelative(text, now) {
+  const m = RELATIVE_PATTERN.exec(text);
+  if (!m) return null;
+  const amount = Number(m[1]);
+  const unit = m[2].toLowerCase();
+  let ms;
+  if (unit.startsWith('hour')) ms = amount * 60 * 60 * 1000;
+  else if (unit.startsWith('minute')) ms = amount * 60 * 1000;
+  else ms = amount * 1000;
+  return new Date(now.getTime() + ms);
+}
+
+function parseRetryAfter(text, now) {
+  const m = RETRY_AFTER_PATTERN.exec(text);
+  if (!m) return null;
+  const amount = Number(m[1]);
+  const unit = (m[2] || 's').toLowerCase();
+  let ms;
+  if (unit.startsWith('m') && unit !== 's') ms = amount * 60 * 1000;
+  else ms = amount * 1000;
+  return new Date(now.getTime() + ms);
+}
+
+function parseRetryAtDate(text) {
+  const m = RETRY_AT_DATE_PATTERN.exec(text);
+  if (!m) return null;
+  return parseIso(m[1]);
+}
+
+function projectClockTime(now, hour, minute) {
+  const candidate = new Date(now.getFullYear(), now.getMonth(), now.getDate(), hour, minute, 0, 0);
+  if (candidate.getTime() <= now.getTime()) {
+    candidate.setDate(candidate.getDate() + 1);
+  }
+  return candidate;
+}
+
+function parseResetTime(text, now = new Date()) {
+  if (!text) return null;
+  return (
+    parseRetryAtDate(text) ||
+    parseIso(text) ||
+    parseTwelveHour(text, now) ||
+    parseTwentyFourHour(text, now) ||
+    parseRelative(text, now) ||
+    parseRetryAfter(text, now)
+  );
+}
+
+function formatBlockUntil(date) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  const hour = String(date.getHours()).padStart(2, '0');
+  return `${year}-${month}-${day} ${hour}`;
+}
+
+function ceilToNextHour(date) {
+  const ceil = new Date(date.getTime());
+  if (ceil.getMinutes() === 0 && ceil.getSeconds() === 0 && ceil.getMilliseconds() === 0) {
+    return ceil;
+  }
+  ceil.setMinutes(0, 0, 0);
+  ceil.setHours(ceil.getHours() + 1);
+  return ceil;
+}
+
+function detectLimitHit({
+  agent,
+  stdout = '',
+  stderr = '',
+  status,
+  signal,
+  error,
+  now = new Date()
+} = {}) {
+  if (!agent) return null;
+  // Gate detection on a failed launcher invocation. A successful child (exit 0,
+  // no signal, no spawn error) means any limit-hit phrases in the transcript
+  // are quoted text — typically when the agent itself reviewed code, tests, or
+  // logs containing those strings. Treating that as a real limit hit would
+  // wrongly block a healthy agent in agents.local.json.
+  // `status === undefined` means the caller did not pass exit metadata; preserve
+  // the legacy behavior so callers that haven't been updated still get detection.
+  const launcherFailed =
+    error != null ||
+    signal != null ||
+    (typeof status === 'number' && status !== 0) ||
+    typeof status === 'undefined';
+  if (!launcherFailed) return null;
+
+  const combined = `${stdout || ''}\n${stderr || ''}`;
+  const match = findLimitHitMatch(agent, combined);
+
+  let target;
+  let source;
+
+  if (match) {
+    const context = clipContext(combined, match.index, match.length);
+    const parsed = parseResetTime(context, now);
+
+    if (parsed && !Number.isNaN(parsed.getTime()) && parsed.getTime() > now.getTime()) {
+      target = parsed;
+      source = 'parsed';
+    } else {
+      target = new Date(now.getTime() + DEFAULT_FALLBACK_HOURS * 60 * 60 * 1000);
+      source = 'fallback';
+    }
+  } else if (signal != null) {
+    // Agent was killed by a signal (e.g. SIGINT/Ctrl-C) but no limit-hit
+    // pattern matched. Apply a short-term block so the next invocation
+    // selects a different agent instead of re-picking the same one.
+    target = new Date(now.getTime() + SIGINT_SHORT_BLOCK_MINUTES * 60 * 1000);
+    source = 'sigint';
+  } else {
+    return null;
+  }
+
+  const ceiled = ceilToNextHour(target);
+  return { until: formatBlockUntil(ceiled), source };
+}
+
+module.exports = {
+  detectLimitHit,
+  parseResetTime,
+  formatBlockUntil,
+  ceilToNextHour,
+  findLimitHitMatch,
+  clipContext,
+  parseIsoOffset,
+  parseIso,
+  parseTwelveHour,
+  parseTwentyFourHour,
+  parseRelative,
+  parseRetryAfter,
+  parseRetryAtDate,
+  projectClockTime,
+  getPatternsForAgent,
+  PATTERN_SETS,
+  DEFAULT_FALLBACK_HOURS,
+  SIGINT_SHORT_BLOCK_MINUTES
+};

package/lib/agents/mistral-telemetry.js

@@ -0,0 +1,44 @@
+/**
+ * Mistral (Vibe) Telemetry Stub
+ *
+ * Mistral Vibe in programmatic mode does not output token-usage data to
+ * stdout/stderr, and has no CLI endpoint for querying session usage.
+ * This stub records honest zeros for all token columns so the stats CSV
+ * never contains fabricated data.
+ *
+ * Provider and model fields are set to "mistral" to indicate the agent family.
+ * The actual model is determined at runtime via VIBE_ACTIVE_MODEL env var
+ * but is not captured per-session, so model falls back to "mistral".
+ *
+ * See task-1285 for the full telemetry credibility design. The blocked
+ * verification is tracked as follow-up task-1288 ("Verify vibe/mistral
+ * telemetry once usage-unblocked"), which names the missing evidence and the
+ * reason it could not be collected in the task-1285 environment.
+ */
+
+/**
+ * Attempt to extract telemetry from a mistral launcher result.
+ * Since mistral/vibe provides no parseable usage data, always returns null.
+ *
+ * @param {object} result - The launcher result object
+ * @returns {null} Always null — mistral/vibe has no telemetry parser
+ */
+function extractMistralTelemetry(result) {
+  // Mistral Vibe does not emit token usage data. Honest zero.
+  return null;
+}
+
+/**
+ * Return the provider/model pair for mistral tasks.
+ * Used as fallback when telemetry is null.
+ *
+ * @returns {{provider: string, model: string}}
+ */
+function getMistralProviderModel() {
+  return { provider: 'mistral', model: 'mistral' };
+}
+
+module.exports = {
+  extractMistralTelemetry,
+  getMistralProviderModel,
+};

package/lib/agents/mistral.js

@@ -0,0 +1,68 @@
+const { spawnAndTee } = require('../core/spawn-tee');
+
+// Mistral Vibe in programmatic mode (-p/--prompt) does NOT output a resume
+// hint to stdout/stderr like other agents do. Session IDs are stored in
+// ~/.vibe/logs/session/session_<timestamp>_<short_id>/meta.json with UUID format,
+// but there is no reliable stdout pattern to extract. Therefore, Mistral is
+// NOT marked as RESUME_CAPABLE in agents.js. If future Vibe versions add
+// a resume hint, update this regex and add 'mistral' to RESUME_CAPABLE.
+// Current session ID format in meta.json: UUID like "a3dd3d4d-f97d-d57d-4942-a1f694e3a922"
+// Directory naming uses first 8 chars: session_20260521_162703_a3dd3d4d
+// No stdout marker detected in testing, so we leave this as null.
+// Telemetry: mistral/vibe does not expose token-usage data. See mistral-telemetry.js
+// for the honest-zero stub. Stats hooks in active.js and review-loop.js call
+// recordStageStats which defaults to '0' for tokens when telemetry is null.
+const MISTRAL_SESSION_ID_RE = null;
+
+function extractMistralSessionId(stdout) {
+  // Vibe does not currently emit a resume hint in programmatic mode.
+  // Return null to indicate no resume capability via stdout parsing.
+  return null;
+}
+
+function resolveMistralCommand() {
+  return 'vibe';
+}
+
+function buildMistralInvocation({ prompt, worktree, env, resume = false, sessionId = null, model = null }) {
+  const args = ['--prompt', prompt, '--trust', '--output', 'text'];
+
+  // Vibe programmatic mode does not support --resume flag in the same way
+  // as other agents. The --resume flag exists but requires interactive selection
+  // or a session picker. Since we cannot reliably pass a session ID via
+  // programmatic mode, we do not add resume flags here.
+  // If resume capability is proven in a future version, update this.
+
+  // Vibe has no CLI model flag in programmatic mode; the active model is
+  // selected via the VIBE_ACTIVE_MODEL env var (verified from `vibe --help`).
+  const modelEnv = model ? { VIBE_ACTIVE_MODEL: model } : {};
+
+  return {
+    command: resolveMistralCommand(),
+    args,
+    options: {
+      stdio: 'inherit',
+      cwd: worktree,
+      env: { ...process.env, ...env, ...modelEnv }
+    }
+  };
+}
+
+function startMistralAgent({ prompt, worktree, env, resume = false, sessionId = null, model = null, teeOptions = {} }) {
+  const invocation = buildMistralInvocation({ prompt, worktree, env, resume, sessionId, model });
+  const resultPromise = spawnAndTee(invocation.command, invocation.args, { ...invocation.options, ...teeOptions }).then(result => {
+    if (result && result.stdout) {
+      result.sessionId = extractMistralSessionId(result.stdout);
+    }
+    return result;
+  });
+
+  return { invocation, resultPromise };
+}
+
+module.exports = {
+  buildMistralInvocation,
+  extractMistralSessionId,
+  resolveMistralCommand,
+  startMistralAgent
+};

package/lib/agents/opencode-export.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const childProcess = require('child_process');
+
+/**
+ * Capture the complete `opencode export <sessionId>` JSON document.
+ *
+ * Unlike the limit-hit tail buffer in spawn-tee.js, telemetry needs the WHOLE
+ * export document (it is a single JSON object beginning with `{`), so a tail
+ * buffer would discard the prefix and yield invalid JSON. This collector keeps
+ * the full stdout in memory up to an explicit cap and, critically:
+ *
+ *   - Enforces a timeout that kills a hung/non-exiting export child so the
+ *     launcher can never block on it (mission risk + stop rule).
+ *   - Fails explicitly (resolves null) when output exceeds `maxBytes` rather
+ *     than silently truncating into unparseable JSON.
+ *
+ * Never rejects: any error/timeout/oversize resolves to null so telemetry
+ * capture stays best-effort and cannot break the launch.
+ *
+ * @param {string} sessionId - opencode session id (e.g. ses_...)
+ * @param {object} opts
+ * @param {string} [opts.worktree] - cwd for the export process
+ * @param {object} [opts.env] - extra env vars
+ * @param {number} [opts.timeoutMs] - hard timeout before the child is killed
+ * @param {number} [opts.maxBytes] - explicit byte cap; exceeding it fails
+ * @param {Function} [opts.spawn] - injectable spawn (defaults to child_process.spawn)
+ * @returns {Promise<string|null>} Full JSON string, or null on failure
+ */
+function captureOpencodeExport(sessionId, opts = {}) {
+  const {
+    worktree,
+    env,
+    timeoutMs = 30000,
+    maxBytes = 32 * 1024 * 1024,
+    spawn = childProcess.spawn,
+  } = opts;
+
+  return new Promise((resolve) => {
+    if (!sessionId) {
+      resolve(null);
+      return;
+    }
+
+    let settled = false;
+    let timer = null;
+    const chunks = [];
+    let size = 0;
+
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(value);
+    };
+
+    const killChild = (child) => {
+      try { child.kill('SIGKILL'); } catch (_) { /* already gone */ }
+    };
+
+    let child;
+    try {
+      child = spawn('opencode', ['export', sessionId], {
+        cwd: worktree,
+        env: { ...process.env, ...(env || {}) },
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+    } catch (_) {
+      finish(null);
+      return;
+    }
+
+    timer = setTimeout(() => {
+      // Hung or slow export: kill it and degrade to null. Do not block.
+      killChild(child);
+      finish(null);
+    }, timeoutMs);
+    // Intentionally NOT unref'd: the caller always awaits this Promise, and the
+    // timer is cleared via finish() the moment the export resolves. Leaving it
+    // ref'd keeps the timeout deterministic under Node's test runner (an unref'd
+    // timer can be skipped when the loop is otherwise idle, cancelling the test).
+
+    if (!child || !child.stdout) {
+      finish(null);
+      return;
+    }
+
+    child.stdout.on('data', (chunk) => {
+      if (settled) return;
+      size += chunk.length;
+      if (size > maxBytes) {
+        // Explicit failure rather than silent truncation: a partial JSON
+        // document would parse to null/garbage and fabricate zero telemetry.
+        killChild(child);
+        finish(null);
+        return;
+      }
+      chunks.push(chunk);
+    });
+
+    child.on('error', () => finish(null));
+
+    child.on('close', () => {
+      if (settled) return;
+      finish(Buffer.concat(chunks).toString('utf8'));
+    });
+  });
+}
+
+module.exports = { captureOpencodeExport };