Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
69.5 KB
Raw Blame
/**
 * Shared harness for the REAL-agent "door" E2E tests — the ones that drive the
 * ACTUAL `claude` and `codex` binaries against a live gbrain brain (over MCP
 * for Claude Code, over CLI for Codex). No PATH shims, no SDK: the door tests
 * spawn the operator's installed binaries and pay real API cost, so every entry
 * point here is written to fail-SKIP (never fail-HARD) on a machine that lacks
 * a binary or its auth.
 *
 * Adapted from gstack's test/helpers/{hermetic-env,session-runner,
 * codex-session-runner,claude-pty-runner}.ts. What changed for gbrain:
 *
 *   - Hermeticity is UNCONDITIONAL here (no EVALS_HERMETIC escape hatch). A
 *     door test must NEVER see the operator's real ~/.claude, ~/.gbrain, or
 *     ~/.codex. Every spawn gets a scrubbed env pointed at temp HOME /
 *     CLAUDE_CONFIG_DIR / CODEX_HOME / GBRAIN_HOME the test owns.
 *   - promotedEnv is inlined (no dependency on gstack's conductor-env-shim):
 *     GSTACK_ANTHROPIC_API_KEY is promoted to ANTHROPIC_API_KEY when the
 *     canonical key is unset, so a Conductor workspace (which only exports the
 *     GSTACK_ form) still authenticates the child.
 *   - The stream parsers (parseClaudeStream / parseCodexJsonl) are pure and
 *     exported so the companion unit test exercises extraction with ZERO real
 *     binaries.
 *   - seedBrainForAgent + writeGbrainMcpConfig wire a real keyless PGLite brain
 *     to a spawned `gbrain serve` so a Claude Code door test can assert recall.
 *
 * The drop-list is the security contract: CONDUCTOR_* / CLAUDE_* / GSTACK_* /
 * MCP_* / GBRAIN_* never reach a child except via the explicit overrides the
 * caller passes (which spread LAST and always win). HERMES_HOME is handled the
 * same way — not in any allowlist, so it only reaches a child via an explicit
 * override (the hermes door test always sets it to a temp home).
 */

import { spawnSync } from 'node:child_process';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';

import { PGLiteEngine } from '../../src/core/pglite-engine.ts';
import { operations, type OperationContext, type Operation } from '../../src/core/operations.ts';
import { saveConfig, gbrainPath, type GBrainConfig } from '../../src/core/config.ts';
import { addSource, SourceOpError } from '../../src/core/sources-ops.ts';

// ────────────────────────────────────────────────────────────────────────────
// 1. Hermetic child environment
// ────────────────────────────────────────────────────────────────────────────

/** Exact env names a hermetic child keeps. Everything else (unless matched by
 *  a prefix rule or the caller's extraAllow) is dropped. */
const ALLOW_EXACT = new Set<string>([
  // Process basics
  'PATH', 'HOME', 'TMPDIR', 'TERM', 'COLORTERM', 'LANG', 'LC_ALL', 'SHELL',
  'USER', 'LOGNAME', 'TZ', 'NODE_ENV', 'CI',
  // Network reachability — proxied networks can't reach the Anthropic API
  // without these.
  'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY',
  'http_proxy', 'https_proxy', 'no_proxy',
  'SSL_CERT_FILE', 'SSL_CERT_DIR', 'NODE_EXTRA_CA_CERTS',
  // Auth — named, NOT the broad ANTHROPIC_* prefix (a prefix rule would smuggle
  // model/beta/debug knobs that change agent behavior).
  'ANTHROPIC_API_KEY',
  'ANTHROPIC_BASE_URL',
  'ANTHROPIC_AUTH_TOKEN',
]);

/** Prefix rules: eval-harness knobs + CI metadata. Deliberately NOT here:
 *  CONDUCTOR_* / CLAUDE_* / GSTACK_* / MCP_* / GBRAIN_* (session-context
 *  contamination) and operator credentials (GH_TOKEN, OPENAI_API_KEY, …). A
 *  provider runner re-admits its own auth via opts.extraAllow. */
const ALLOW_PREFIXES = ['EVALS_', 'GITHUB_'];

export interface HermeticEnvOpts {
  /** Additional allowed names (exact) or prefixes (entries ending in '*').
   *  Example: the codex runner passes ['OPENAI_API_KEY', 'CODEX_*']. */
  extraAllow?: string[];
}

/**
 * Pure form of the GSTACK_ → canonical promotion. Returns a copy of `base`
 * with ANTHROPIC_API_KEY / OPENAI_API_KEY filled from their GSTACK_-prefixed
 * form when the canonical is empty. Never mutates `base`.
 */
export function promotedEnv(base: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
  const out: NodeJS.ProcessEnv = { ...base };
  for (const key of ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY'] as const) {
    if (!out[key] && out[`GSTACK_${key}`]) out[key] = out[`GSTACK_${key}`];
  }
  return out;
}

/**
 * Build a scrubbed child env: promote GSTACK_ keys, keep only the allowlisted
 * names (+ caller's extraAllow), then spread the caller's overrides LAST so a
 * per-test HOME / CLAUDE_CONFIG_DIR / CODEX_HOME / GBRAIN_HOME always wins.
 * Reads process.env at CALL time.
 */
export function hermeticChildEnv(
  overrides: Record<string, string | undefined> = {},
  opts?: HermeticEnvOpts,
): NodeJS.ProcessEnv {
  const promoted = promotedEnv(process.env);

  const extraExact = new Set<string>();
  const extraPrefixes: string[] = [];
  for (const entry of opts?.extraAllow ?? []) {
    if (entry.endsWith('*')) extraPrefixes.push(entry.slice(0, -1));
    else extraExact.add(entry);
  }

  const out: NodeJS.ProcessEnv = {};
  for (const [k, v] of Object.entries(promoted)) {
    if (v === undefined) continue;
    const allowed =
      ALLOW_EXACT.has(k) ||
      extraExact.has(k) ||
      ALLOW_PREFIXES.some((p) => k.startsWith(p)) ||
      extraPrefixes.some((p) => k.startsWith(p));
    if (allowed) out[k] = v;
  }
  if (!out.TERM) out.TERM = 'xterm-256color';
  for (const [k, v] of Object.entries(overrides)) {
    if (v !== undefined) out[k] = v;
  }
  return out;
}

// ────────────────────────────────────────────────────────────────────────────
// 2. Binary resolution
// ────────────────────────────────────────────────────────────────────────────

function whichBin(name: string): string | null {
  try {
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const found = (Bun as any).which?.(name);
    return found || null;
  } catch {
    return null;
  }
}

function firstExecutable(candidates: string[]): string | null {
  for (const c of candidates) {
    if (!c) continue;
    try {
      fs.accessSync(c, fs.constants.X_OK);
      return c;
    } catch {
      /* keep searching */
    }
  }
  return null;
}

/**
 * Door-family binary resolver factory (the rule-of-three extraction, fired by
 * the 4th door agent — opencode). One shape for every agent:
 *   $<envVar> (FAIL-CLOSED validation when set) > Bun.which > landing spots
 *   (+ optional nvm/PATH sweeps) > null.
 * Fail-closed on a set-but-invalid override on purpose (the grok lesson):
 * silently falling through to `which` could bind a colliding same-name
 * binary DESPITE the operator's explicit pin.
 */
export function makeBinaryResolver(spec: {
  envVar?: string;
  binName: string;
  candidates: (home: string) => string[];
  nvmSweep?: boolean;
  pathSweep?: boolean;
}): () => string | null {
  return () => {
    if (spec.envVar) {
      const fromEnv = process.env[spec.envVar]?.trim();
      if (fromEnv) {
        if (!fromEnv.startsWith('/') || fromEnv.split('/').includes('..')) return null;
        return firstExecutable([fromEnv]);
      }
    }
    const which = whichBin(spec.binName);
    if (which) return which;
    const home = process.env.HOME ?? os.homedir();
    const candidates = [...spec.candidates(home)];
    if (spec.nvmSweep) {
      try {
        const nvmBase = path.join(home, '.nvm', 'versions', 'node');
        for (const v of fs.readdirSync(nvmBase)) {
          candidates.push(path.join(nvmBase, v, 'bin', spec.binName));
        }
      } catch {
        /* no nvm */
      }
    }
    if (spec.pathSweep) {
      for (const dir of (process.env.PATH ?? '').split(path.delimiter)) {
        if (dir) candidates.push(path.join(dir, spec.binName));
      }
    }
    return firstExecutable(candidates);
  };
}

/** Locate the real `claude` binary. Bun.which first, then known install dirs. */
export const resolveClaudeBinary = makeBinaryResolver({
  binName: 'claude',
  candidates: (home) => [
    '/opt/homebrew/bin/claude',
    '/usr/local/bin/claude',
    `${home}/.local/bin/claude`,
    `${home}/.bun/bin/claude`,
    `${home}/.npm-global/bin/claude`,
  ],
});

/** Locate the real `hermes` binary (NousResearch hermes-agent). Bun.which
 *  first, then the installer's known landing spots. */
export const resolveHermesBinary = makeBinaryResolver({
  binName: 'hermes',
  candidates: (home) => [
    '/opt/homebrew/bin/hermes',
    '/usr/local/bin/hermes',
    `${home}/.local/bin/hermes`, // where the official installer symlinks (observed v0.20.0)
    `${home}/.hermes/bin/hermes`,
  ],
  pathSweep: true,
});

/** Locate the real `codex` binary. Bun.which first, then known install dirs
 *  (adds ~/.nvm + common node bin dirs where the npm global lands). */
export const resolveCodexBinary = makeBinaryResolver({
  binName: 'codex',
  candidates: (home) => [
    '/opt/homebrew/bin/codex',
    '/usr/local/bin/codex',
    `${home}/.local/bin/codex`,
    `${home}/.bun/bin/codex`,
    `${home}/.npm-global/bin/codex`,
    `${home}/.cargo/bin/codex`,
  ],
  nvmSweep: true,
  pathSweep: true,
});

// ────────────────────────────────────────────────────────────────────────────
// 3. Auth probes (drive skipIf in the door tests)
// ────────────────────────────────────────────────────────────────────────────

/** Claude Code is usable if an Anthropic key is exported (either form) OR the
 *  operator has a real ~/.claude.json (subscription auth). */
export function hasClaudeAuth(): boolean {
  if (process.env.ANTHROPIC_API_KEY || process.env.GSTACK_ANTHROPIC_API_KEY) return true;
  try {
    return fs.existsSync(path.join(os.homedir(), '.claude.json'));
  } catch {
    return false;
  }
}

/** Codex is usable if the operator has a real ~/.codex/auth.json. */
export function hasCodexAuth(): boolean {
  try {
    // Either auth shape works for a spawned `codex exec`: the operator's
    // auth.json (copied into the hermetic CODEX_HOME) or an ambient
    // CODEX_API_KEY (hermeticChildEnv's extraAllow passes CODEX_* through).
    return fs.existsSync(path.join(os.homedir(), '.codex', 'auth.json'))
      || !!process.env.CODEX_API_KEY;
  } catch {
    return false;
  }
}

/** Every provider key hermes recognizes — scrubbed from child env so the
 *  seeded .env is the SINGLE auth source. Observed (v0.20.0): with model
 *  pinned to anthropic/* but MULTIPLE provider keys visible, hermes's
 *  provider-auto mis-routes the request and the turn returns
 *  "HTTP 401: Missing Authentication header" as final text (exit 0). */
const HERMES_ALL_PROVIDER_KEYS = [
  'ANTHROPIC_API_KEY', 'ANTHROPIC_BASE_URL', 'ANTHROPIC_AUTH_TOKEN',
  'OPENAI_API_KEY', 'OPENROUTER_API_KEY',
] as const;

/** Parse KEY=VALUE lines from a dotenv-style file. Ignores comments, blanks,
 *  and export prefixes; strips single/double quotes. Never throws. */
export function parseDotenvFile(file: string): Record<string, string> {
  const out: Record<string, string> = {};
  try {
    for (const rawLine of fs.readFileSync(file, 'utf-8').split('\n')) {
      const line = rawLine.trim();
      if (!line || line.startsWith('#')) continue;
      const m = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(line);
      if (!m) continue;
      let v = m[2].trim();
      if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
        v = v.slice(1, -1);
      }
      out[m[1]] = v;
    }
  } catch {
    /* unreadable → empty */
  }
  return out;
}

/**
 * Hermes is usable BY THE DOOR SUITE if an ANTHROPIC key with a NON-EMPTY
 * value is available — either exported (GSTACK_ promotion applies) or present
 * in the operator's real ~/.hermes/.env.
 *
 * Anthropic-only on purpose: the door pins model.default to anthropic/*, and
 * seeding any second provider key makes hermes's provider-auto mis-route the
 * pinned model ("HTTP 401: Missing Authentication header", observed). Bare
 * file existence is deliberately NOT auth: a blank CI secret writes an empty
 * .env, and that must produce a SKIP, not a paid failing test.
 */
export function hasHermesAuth(): boolean {
  const env = promotedEnv(process.env);
  if (env.ANTHROPIC_API_KEY?.trim()) return true;
  const parsed = parseDotenvFile(path.join(os.homedir(), '.hermes', '.env'));
  return Boolean(parsed.ANTHROPIC_API_KEY?.trim());
}

// ────────────────────────────────────────────────────────────────────────────
// 4. Stream parsers (pure — exercised by the unit test with fixtures)
// ────────────────────────────────────────────────────────────────────────────

export interface ParsedClaudeStream {
  /** The final assistant/result text of the turn. */
  finalText: string;
  /** Names of every tool_use block the assistant emitted, in order. */
  toolCalls: string[];
}

/**
 * Parse `claude -p --output-format stream-json` NDJSON. Collects tool_use
 * names from assistant events and the final answer text. Prefers the terminal
 * `result` event's `result` field; falls back to the concatenation of the last
 * assistant message's text blocks. Skips malformed lines.
 */
export function parseClaudeStream(lines: string[]): ParsedClaudeStream {
  const toolCalls: string[] = [];
  let resultText: string | null = null;
  let lastAssistantText = '';

  for (const line of lines) {
    if (!line.trim()) continue;
    let event: any;
    try {
      event = JSON.parse(line);
    } catch {
      continue;
    }
    if (event.type === 'assistant') {
      const content = event.message?.content ?? [];
      const textParts: string[] = [];
      for (const item of content) {
        if (item?.type === 'tool_use') toolCalls.push(item.name || 'unknown');
        else if (item?.type === 'text' && typeof item.text === 'string') textParts.push(item.text);
      }
      if (textParts.length > 0) lastAssistantText = textParts.join('');
    } else if (event.type === 'result') {
      if (typeof event.result === 'string') resultText = event.result;
    }
  }

  return { finalText: (resultText ?? lastAssistantText) || '', toolCalls };
}

export interface ParsedCodexJsonl {
  /** Concatenated agent_message text. */
  finalText: string;
  /** command_execution commands, in order. */
  toolCalls: string[];
  /** reasoning item text blocks, in order. */
  reasoning: string[];
  /**
   * MCP tool invocations, in order (EV12: previously discarded, forcing
   * e2e assertions onto raw-line regexes). `server` is the MCP server name
   * (e.g. 'gbrain'), `tool` the invoked tool. Fields are best-effort across
   * codex versions (`tool` falls back to `name`/`invocation.tool`).
   */
  mcpToolCalls: Array<{ server: string; tool: string }>;
}

/**
 * Parse `codex exec --json` JSONL. Extracts agent_message → finalText,
 * command_execution → toolCalls, reasoning → reasoning, mcp_tool_call →
 * mcpToolCalls. Skips malformed lines.
 */
export function parseCodexJsonl(lines: string[]): ParsedCodexJsonl {
  const outputParts: string[] = [];
  const toolCalls: string[] = [];
  const reasoning: string[] = [];
  const mcpToolCalls: Array<{ server: string; tool: string }> = [];

  for (const line of lines) {
    if (!line.trim()) continue;
    let obj: any;
    try {
      obj = JSON.parse(line);
    } catch {
      continue;
    }
    if (obj.type === 'item.completed' && obj.item) {
      const item = obj.item;
      const text = item.text || '';
      if (item.type === 'reasoning' && text) reasoning.push(text);
      else if (item.type === 'agent_message' && text) outputParts.push(text);
      else if (item.type === 'command_execution' && item.command) toolCalls.push(item.command);
      else if (item.type === 'mcp_tool_call') {
        mcpToolCalls.push({
          server: item.server ?? item.invocation?.server ?? '',
          tool: item.tool ?? item.name ?? item.invocation?.tool ?? '',
        });
      }
    }
  }

  return { finalText: outputParts.join('\n'), toolCalls, reasoning, mcpToolCalls };
}

export interface ParsedOpencodeJsonl {
  /** Concatenated text-part content, in stream order. */
  finalText: string;
  /** Tool names from tool events, in order (MCP tools: `<server>_<tool>`,
   *  e.g. `gbrain_recall` — observed v1.18.18). */
  toolCalls: string[];
  /** #6049: one line per `error` event: `<name> <statusCode> <responseBody error.type>: <message>`,
   *  so a turn the provider refused (e.g. a FreeTierError 403) says why instead of an empty reply. */
  errors: string[];
}

/**
 * Parse `opencode run --format json` NDJSON. Every event is
 * `{type, timestamp, sessionID, part}` (observed v1.18.18 —
 * OPENCODE-CLI-PIN.md §One-shot): `text` events carry `part.text`;
 * `tool_use` events carry `part.tool` + `part.state.{status,input,output}`;
 * `error` events carry `error.{name,data.{message,statusCode,responseBody}}`.
 * Skips malformed lines and unknown event types.
 */
export function parseOpencodeJsonl(lines: string[]): ParsedOpencodeJsonl {
  const textParts: string[] = [];
  const toolCalls: string[] = [];
  const errors: string[] = [];
  for (const line of lines) {
    let evt: unknown;
    try {
      evt = JSON.parse(line);
    } catch {
      continue;
    }
    if (typeof evt !== 'object' || evt === null) continue;
    const e = evt as { type?: string; part?: { text?: unknown; tool?: unknown };
      error?: { name?: unknown; data?: { message?: unknown; statusCode?: unknown; responseBody?: unknown } } };
    if (e.type === 'text' && typeof e.part?.text === 'string') {
      textParts.push(e.part.text);
    } else if (e.type === 'tool_use' && typeof e.part?.tool === 'string') {
      toolCalls.push(e.part.tool);
    } else if (e.type === 'error') {
      const data = e.error?.data;
      let bodyType: unknown;
      try { bodyType = typeof data?.responseBody === 'string' ? JSON.parse(data.responseBody)?.error?.type : undefined; } catch { /* non-JSON body */ }
      const head = [e.error?.name, data?.statusCode, bodyType].filter((v) => typeof v === 'string' || typeof v === 'number').join(' ');
      const message = typeof data?.message === 'string' ? data.message : '';
      errors.push(head && message ? `${head}: ${message}` : head || message || 'error event without details');
    }
  }
  return { finalText: textParts.join('\n').trim(), toolCalls, errors };
}

// ────────────────────────────────────────────────────────────────────────────
// 5. Real-binary turns
// ────────────────────────────────────────────────────────────────────────────

/** Read a piped stream to a string of NDJSON/JSONL lines, calling onLine for
 *  each complete line. Returns all collected lines. */
async function streamLines(
  stream: ReadableStream<Uint8Array>,
  collected: string[],
): Promise<void> {
  const reader = stream.getReader();
  const decoder = new TextDecoder();
  let buf = '';
  try {
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      buf += decoder.decode(value, { stream: true });
      const parts = buf.split('\n');
      buf = parts.pop() || '';
      for (const line of parts) {
        if (line.trim()) collected.push(line);
      }
    }
  } catch {
    /* stream cancelled (timeout) or read error — fall through */
  }
  if (buf.trim()) collected.push(buf);
}

export interface ClaudeTurnOpts {
  prompt: string;
  cwd: string;
  home: string;
  claudeConfigDir: string;
  mcpConfigPath?: string;
  model?: string;
  timeoutMs?: number;
  /** Extra env for the child (spread LAST — wins). See CodexTurnOpts.extraEnv. */
  extraEnv?: Record<string, string>;
}

export interface ClaudeTurnResult {
  finalText: string;
  toolCalls: string[];
  rawLines: string[];
  exitCode: number | null;
  timedOut: boolean;
}

/**
 * Drive one headless `claude -p` turn against a hermetic HOME/config dir.
 * Optionally wires an MCP config (with --strict-mcp-config so ONLY that server
 * is loaded — no operator MCP contamination). Prompt is piped via stdin.
 */
export async function claudeHeadlessTurn(opts: ClaudeTurnOpts): Promise<ClaudeTurnResult> {
  const model = opts.model ?? 'claude-sonnet-4-6';
  const timeoutMs = opts.timeoutMs ?? 180_000;

  const args = [
    '-p',
    '--model', model,
    '--output-format', 'stream-json',
    '--verbose',
    '--dangerously-skip-permissions',
    ...(opts.mcpConfigPath ? ['--mcp-config', opts.mcpConfigPath, '--strict-mcp-config'] : []),
  ];

  // EV12: spawn the RESOLVED binary — the hermetic child env strips PATH
  // customizations, so a bare 'claude' can resolve differently (or not at
  // all) inside the child than the resolver reported to the skip-gate.
  const claudeBin = resolveClaudeBinary() ?? 'claude';
  const proc = Bun.spawn([claudeBin, ...args], {
    cwd: opts.cwd,
    env: hermeticChildEnv({ HOME: opts.home, CLAUDE_CONFIG_DIR: opts.claudeConfigDir, ...opts.extraEnv }),
    stdin: 'pipe',
    stdout: 'pipe',
    stderr: 'pipe',
  });

  // Write the prompt then close stdin.
  proc.stdin.write(opts.prompt);
  await proc.stdin.end();

  let timedOut = false;
  const rawLines: string[] = [];
  const stdoutDone = streamLines(proc.stdout, rawLines);
  const stderrDone = new Response(proc.stderr).text();

  const timer = setTimeout(() => {
    timedOut = true;
    try { proc.kill(); } catch { /* already dead */ }
  }, timeoutMs);

  await stdoutDone;
  await stderrDone.catch(() => '');
  const exitCode = await proc.exited;
  clearTimeout(timer);

  const parsed = parseClaudeStream(rawLines);
  return { finalText: parsed.finalText, toolCalls: parsed.toolCalls, rawLines, exitCode, timedOut };
}

export interface CodexTurnOpts {
  prompt: string;
  cwd: string;
  home: string;
  timeoutMs?: number;
  sandbox?: string;
  /** Extra env for the child (spread LAST — wins). The plugin doors use this
   *  to thread GBRAIN_BIN/GBRAIN_HOME/GBRAIN_SOURCE through codex's env_vars
   *  passthrough into the plugin-launched MCP server. */
  extraEnv?: Record<string, string>;
  /** Explicit approvals for tools on fixture-owned MCP servers only. Neither
   * global approval policy nor shell sandbox permissions are changed. */
  mcpToolApprovals?: Array<{ server: string; plugin?: string; tools: readonly string[] }>;
  /** Wait for the fixture server's bounded startup before presenting tools. */
  waitForMcpStartup?: boolean;
}

/** Codex's -c paths use literal dot-separated segments, not TOML quoted keys.
 * Reject separators so fixture names cannot change the override's scope. */
export function codexMcpApprovalArgs(approvals: CodexTurnOpts['mcpToolApprovals'] = []): string[] {
  return approvals.flatMap(({ server, plugin, tools }) => {
    for (const name of [server, ...(plugin === undefined ? [] : [plugin]), ...tools]) {
      if (!/^[A-Za-z0-9_@-]+$/.test(name)) throw new Error('Fixture MCP approval names must be single config-path segments');
    }
    const prefix = plugin === undefined ? 'mcp_servers' : `plugins.${plugin}.mcp_servers`;
    return [...new Set(tools)].flatMap((tool) => [
      '-c', `${prefix}.${server}.tools.${tool}.approval_mode="approve"`,
    ]);
  });
}

export interface CodexTurnResult {
  finalText: string;
  toolCalls: string[];
  reasoning: string[];
  /** MCP tool invocations ({server, tool}) — see ParsedCodexJsonl.mcpToolCalls. */
  mcpToolCalls: Array<{ server: string; tool: string }>;
  rawLines: string[];
  stderrText: string;
  exitCode: number | null;
  timedOut: boolean;
}

/**
 * Drive one `codex exec` turn against a hermetic HOME. Copies the operator's
 * real ~/.codex/* (except skills/) into <home>/.codex so codex authenticates
 * without touching the real config dir. Parses JSONL output.
 */
export async function codexExecTurn(opts: CodexTurnOpts): Promise<CodexTurnResult> {
  const timeoutMs = opts.timeoutMs ?? 240_000;
  const sandbox = opts.sandbox ?? 'workspace-write';

  // Seed the temp HOME's .codex from the operator's real auth (read-only copy,
  // skipping skills/ so a downstream test can install its own).
  const realCodex = path.join(os.homedir(), '.codex');
  const tempCodex = path.join(opts.home, '.codex');
  fs.mkdirSync(tempCodex, { recursive: true });
  if (fs.existsSync(realCodex)) {
    for (const entry of fs.readdirSync(realCodex)) {
      if (entry === 'skills') continue;
      const src = path.join(realCodex, entry);
      const dst = path.join(tempCodex, entry);
      if (!fs.existsSync(dst)) {
        try { fs.cpSync(src, dst, { recursive: true }); } catch { /* best-effort */ }
      }
    }
  }

  // EV12: spawn the RESOLVED binary (see claudeHeadlessTurn).
  const codexBin = resolveCodexBinary() ?? 'codex';
  const startupArgs = opts.waitForMcpStartup ? ['-c', 'mcp_optional_startup_grace_ms=0'] : [];
  const proc = Bun.spawn([codexBin, ...codexMcpApprovalArgs(opts.mcpToolApprovals), ...startupArgs, 'exec', opts.prompt, '--json', '-s', sandbox], {
    cwd: opts.cwd,
    env: hermeticChildEnv({ HOME: opts.home, ...opts.extraEnv }, { extraAllow: ['OPENAI_API_KEY', 'CODEX_*'] }),
    stdout: 'pipe',
    stderr: 'pipe',
  });

  let timedOut = false;
  const rawLines: string[] = [];
  const stdoutDone = streamLines(proc.stdout, rawLines);
  const stderrDone = new Response(proc.stderr).text();

  const timer = setTimeout(() => {
    timedOut = true;
    try { proc.kill(); } catch { /* already dead */ }
  }, timeoutMs);

  await stdoutDone;
  const stderrText = await stderrDone.catch(() => '');
  const exitCode = await proc.exited;
  clearTimeout(timer);

  const parsed = parseCodexJsonl(rawLines);
  return {
    finalText: parsed.finalText,
    toolCalls: parsed.toolCalls,
    reasoning: parsed.reasoning,
    mcpToolCalls: parsed.mcpToolCalls,
    rawLines,
    stderrText,
    exitCode: timedOut ? 124 : exitCode,
    timedOut,
  };
}

// ────────────────────────────────────────────────────────────────────────────
// 5a-core. Door-family shared core (childEnv factory + one-shot spawn) —
//          the rule-of-three extraction, fired by the 4th door agent
//          (opencode). hermes/grok/opencode build on these; behavior for the
//          ported agents is pinned by their existing unit truth-tables.
// ────────────────────────────────────────────────────────────────────────────

/** Writable CI step-metadata files the GITHUB_ prefix rule would otherwise
 *  forward to an UNTRUSTED agent child: appending to any of them poisons
 *  later workflow steps (ENV/PATH/OUTPUT/STATE) or the run summary UI. */
const GITHUB_STEP_META_KEYS = [
  'GITHUB_ENV', 'GITHUB_PATH', 'GITHUB_OUTPUT', 'GITHUB_STATE',
  'GITHUB_STEP_SUMMARY', 'GITHUB_ACTION_PATH',
] as const;

/** CI credential material that must never reach an UNTRUSTED agent child:
 *  GITHUB_TOKEN rides the GITHUB_ prefix rule, and the ACTIONS_* runtime/OIDC
 *  tokens are scrubbed unconditionally as defense-in-depth (an exfiltrated
 *  workflow token is repo write access; the OIDC request token mints cloud
 *  credentials). */
const CI_CREDENTIAL_KEYS = [
  'GITHUB_TOKEN', 'ACTIONS_RUNTIME_TOKEN', 'ACTIONS_ID_TOKEN_REQUEST_TOKEN',
] as const;

/**
 * Per-agent hermetic child-env factory: hermeticChildEnv + the agent's home
 * overrides, then key deletion (single-auth-source discipline), the
 * GITHUB_* step-metadata scrub, and an optional staged-bin-dir PATH prepend
 * (agents whose MCP registration uses the documented bare `gbrain` command
 * need every spawn that may start the server to resolve it).
 */
export function makeAgentChildEnv(spec: {
  overrides: (home: string) => Record<string, string | undefined>;
  deleteKeys?: readonly string[];
}): (home: string, opts?: { binDir?: string }) => NodeJS.ProcessEnv {
  return (home, opts) => {
    const env = hermeticChildEnv(spec.overrides(home));
    for (const k of spec.deleteKeys ?? []) delete env[k];
    for (const k of GITHUB_STEP_META_KEYS) delete env[k];
    for (const k of CI_CREDENTIAL_KEYS) delete env[k];
    if (opts?.binDir) env.PATH = `${opts.binDir}:${env.PATH ?? ''}`;
    return env;
  };
}

export interface OneShotSpawnResult {
  /** One-shot modes print the final response text alone on stdout. */
  finalText: string;
  exitCode: number | null;
  timedOut: boolean;
  stderrText: string;
  /** The value abortWhen returned when it ended the run early. */
  abortReason?: string;
}

/** How long a killed one-shot child's output may keep draining. */
const KILL_DRAIN_GRACE_MS = 8_000;

/**
 * Shared one-shot spawn core: timeout → kill, kill(9) escalation after 5s
 * (agents may leave a daemon/MCP-server child holding the pipes open past
 * the parent's death), and a BOUNDED stream drain (timeout + 30s cap, or
 * KILL_DRAIN_GRACE_MS once the child is killed) so a grandchild holding the
 * pipe fds can never hang a retry loop. Exit 124 on timeout.
 */
export async function runOneShotSpawn(opts: {
  argv: string[];
  cwd: string;
  env: NodeJS.ProcessEnv;
  timeoutMs: number;
  /** Polled every second; a returned string kills the child like a timeout
   *  and comes back as abortReason. */
  abortWhen?: () => string | undefined;
}): Promise<OneShotSpawnResult> {
  const proc = Bun.spawn(opts.argv, {
    cwd: opts.cwd,
    env: opts.env,
    stdout: 'pipe',
    stderr: 'pipe',
    stdin: 'ignore',
  });

  let timedOut = false;
  let abortReason: string | undefined;
  let killed: () => void = () => {};
  const killedAt = new Promise<void>((r) => { killed = r; });
  const kill = () => {
    killed();
    try { proc.kill(); } catch { /* already dead */ }
    setTimeout(() => { try { proc.kill(9); } catch { /* already dead */ } }, 5_000);
  };
  const timer = setTimeout(() => {
    timedOut = true;
    kill();
  }, opts.timeoutMs);
  const abortPoll = opts.abortWhen && setInterval(() => {
    abortReason = opts.abortWhen!();
    if (abortReason === undefined) return;
    clearInterval(abortPoll);
    kill();
  }, 1_000);

  const drainCap = opts.timeoutMs + 30_000;
  // The cap timer is CLEARED when the real promise wins — an uncancelled
  // drainCap timer (timeoutMs + 30s) would keep Bun's event loop alive for
  // minutes after every successful door run. Once the child is killed, a
  // descendant that kept stdout/stderr open (an MCP server, a provider retry
  // helper) gets KILL_DRAIN_GRACE_MS, not the rest of drainCap.
  const bounded = <T>(p: Promise<T>, fallback: T): Promise<T> => {
    let capTimer: ReturnType<typeof setTimeout> | undefined;
    let graceTimer: ReturnType<typeof setTimeout> | undefined;
    let settled = false;
    const cap = new Promise<T>((r) => {
      capTimer = setTimeout(() => r(fallback), drainCap);
    });
    const grace = killedAt.then(() => new Promise<T>((r) => {
      if (!settled) graceTimer = setTimeout(() => r(fallback), KILL_DRAIN_GRACE_MS);
    }));
    return Promise.race([p, cap, grace]).finally(() => {
      settled = true;
      clearTimeout(capTimer);
      clearTimeout(graceTimer);
    }) as Promise<T>;
  };
  const [stdout, stderrText] = await Promise.all([
    bounded(new Response(proc.stdout).text(), ''),
    bounded(new Response(proc.stderr).text().catch(() => ''), ''),
  ]);
  const exitCode = await bounded(proc.exited, 124);
  clearTimeout(timer);
  clearInterval(abortPoll);

  return {
    finalText: stdout.trim(),
    exitCode: timedOut ? 124 : exitCode,
    timedOut,
    stderrText,
    ...(abortReason !== undefined ? { abortReason } : {}),
  };
}

// ────────────────────────────────────────────────────────────────────────────
// 5a-bis. Hermes home seeding + one-shot turn (mirror of the codex trio)
// ────────────────────────────────────────────────────────────────────────────

export interface SeedHermesHomeOpts {
  /** Test-only injection point: read provider keys from this dotenv file
   *  instead of the operator's real ~/.hermes/.env (lets the unit test assert
   *  the allowlist-only copy against a fixture without touching real homes). */
  sourceEnvPath?: string;
}

/**
 * Seed a hermetic <home>/.hermes for a spawned hermes. Copies EXACTLY ONE
 * key — a non-empty ANTHROPIC_API_KEY, from the operator's real ~/.hermes/.env
 * when present, falling back to the (promoted) process env. One key on
 * purpose: the door pins an anthropic/* model, and a second provider key
 * flips hermes's provider-auto into a mis-routed request (observed 401).
 * Never the whole .env file (other creds / endpoints / behavior knobs stay
 * behind), NEVER config.yaml (the operator's private MCP servers). The model
 * pin is a separate step (`pinHermesModel`) because hermes owns config.yaml's
 * schema — hand-writing it risks drift; `hermes config set` round-trips
 * safely.
 */
export function seedHermesHome(home: string, opts?: SeedHermesHomeOpts): string {
  const hermesHome = path.join(home, '.hermes');
  fs.mkdirSync(hermesHome, { recursive: true });

  const fromFile = parseDotenvFile(opts?.sourceEnvPath ?? path.join(os.homedir(), '.hermes', '.env'));
  const env = promotedEnv(process.env);
  const key = fromFile.ANTHROPIC_API_KEY?.trim() || env.ANTHROPIC_API_KEY?.trim();
  if (key) {
    fs.writeFileSync(path.join(hermesHome, '.env'), `ANTHROPIC_API_KEY=${key}\n`, { mode: 0o600 });
  }
  return hermesHome;
}

/**
 * Hermetic env for spawning hermes itself: standard scrub + HOME/HERMES_HOME
 * overrides, then ALL provider keys deleted so the seeded .env is the single
 * auth source (provider-auto determinism — see HERMES_ALL_PROVIDER_KEYS).
 * Via the shared factory, hermes now ALSO gets the GITHUB_* step-metadata
 * scrub (the filed backport from grokChildEnv — the prefix rule forwarded
 * writable CI step files to an untrusted agent child).
 */
export const hermesChildEnv = makeAgentChildEnv({
  overrides: (home) => ({ HOME: home, HERMES_HOME: path.join(home, '.hermes') }),
  deleteKeys: HERMES_ALL_PROVIDER_KEYS,
});

/**
 * Non-interactive model/provider pin for a hermetic hermes home. A virgin
 * install refuses `-z` with "No inference provider configured" (exit 1,
 * observed), and `hermes model` is interactive-only — `config set` is the
 * scriptable path (observed working against v0.20.0).
 */
export function pinHermesModel(hermesBin: string, home: string, model = 'anthropic/claude-haiku-4.5'): { code: number | null; stderr: string } {
  const res = spawnSync(hermesBin, ['config', 'set', 'model.default', model], {
    env: hermesChildEnv(home),
    encoding: 'utf8',
    timeout: 60_000,
  });
  return { code: res.status, stderr: res.stderr ?? '' };
}

export interface HermesTurnOpts {
  prompt: string;
  cwd: string;
  home: string;
  timeoutMs?: number;
  /** When set, the turn passes hermes's usage-report flag targeting this path. */
  usageFile?: string;
}

export interface HermesTurnResult {
  /** hermes's one-shot mode prints ONLY the final response text on stdout. */
  finalText: string;
  exitCode: number | null;
  timedOut: boolean;
  stderrText: string;
  /** Parsed usage-report JSON when usageFile was requested and parseable. */
  usage?: unknown;
}

/**
 * Drive one `hermes -z` turn against a hermetic HOME + HERMES_HOME. The
 * RESOLVED binary path is used (never the bare literal), so resolution and
 * execution can't disagree. stdout is plain final text — NOT NDJSON; there is
 * no per-event tool-call stream to parse (door tests use a negative-control
 * prompt instead).
 */
export async function hermesOneShotTurn(opts: HermesTurnOpts): Promise<HermesTurnResult> {
  const bin = resolveHermesBinary();
  if (!bin) throw new Error('hermesOneShotTurn: hermes binary not found');
  // Shared spawn core: hermes gains the kill(9) escalation + bounded drain
  // the grok lane proved out (strictly-safer; nothing pinned the old
  // unbounded drain).
  const r = await runOneShotSpawn({
    argv: [bin, '-z', opts.prompt, ...(opts.usageFile ? ['--usage-file', opts.usageFile] : [])],
    cwd: opts.cwd,
    env: hermesChildEnv(opts.home),
    timeoutMs: opts.timeoutMs ?? 240_000,
  });

  let usage: unknown;
  if (opts.usageFile) {
    try { usage = JSON.parse(fs.readFileSync(opts.usageFile, 'utf-8')); } catch { /* best-effort */ }
  }

  return { ...r, usage };
}

// ────────────────────────────────────────────────────────────────────────────
// 5a-grok. Grok Build (xAI) — all shapes observed against v1.0.4
//          (docs/mcp/GROK-CLI-PIN.md). grok ≠ groq ≠ ngrok.
// ────────────────────────────────────────────────────────────────────────────

/** Locate the real `grok` binary (xAI Grok Build). $GROK_BIN (absolute,
 *  executable — same override the claw-test runner honors) first, then
 *  Bun.which, then the npm-global and installer landing spots. Collision
 *  note: the community superagent-ai grok-cli ships a colliding `grok`
 *  binary — the door's version-shape pin (T1) is the discriminator. */
export const resolveGrokBinary = makeBinaryResolver({
  envVar: 'GROK_BIN', // fail-closed override — see makeBinaryResolver
  binName: 'grok',
  candidates: (home) => [
    '/opt/homebrew/bin/grok',
    '/usr/local/bin/grok',
    `${home}/.local/bin/grok`,
    `${home}/.npm-global/bin/grok`,
    `${home}/.bun/bin/grok`,
  ],
  pathSweep: true,
});

/**
 * Grok is usable BY THE PAID TIER if a NON-EMPTY XAI_API_KEY is exported.
 * Env-only on purpose: the keyless one-shot exits 1 with "Not signed in …
 * set the XAI_API_KEY environment variable" (observed v1.0.4), and no
 * credential file was observed keyless — if the authed observation finds one
 * under ~/.grok, add it here as a second probe (GROK-CLI-PIN.md marks that
 * item pending auth). Blank CI secret ⇒ skip, never a paid failing test.
 */
export function hasGrokAuth(): boolean {
  return Boolean(process.env.XAI_API_KEY?.trim());
}

/**
 * Hermetic env for spawning grok itself: standard scrub + HOME/GROK_HOME
 * overrides; XAI_API_KEY re-admitted EXPLICITLY (it is deliberately not in
 * ALLOW_EXACT — default-deny stays intact for every other child). Deletes:
 *  - other providers' keys (defensive; grok is single-provider, but scrubbing
 *    is free and keeps the door single-auth-source like the hermes lane), and
 *  - GITHUB_ENV/GITHUB_PATH/GITHUB_OUTPUT/GITHUB_STATE — the GITHUB_ prefix
 *    rule would forward these CI step-metadata files to an UNTRUSTED agent
 *    child, which could append to them and poison later workflow steps.
 */
export const grokChildEnv = makeAgentChildEnv({
  overrides: (home) => ({
    HOME: home,
    GROK_HOME: path.join(home, '.grok'),
    XAI_API_KEY: process.env.XAI_API_KEY?.trim() || undefined,
  }),
  deleteKeys: ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'OPENAI_API_KEY'],
});

/**
 * Seed a hermetic <home>/.grok/config.toml BEFORE any grok spawn:
 *  - `[cli] auto_update = false` — auto-update is config-only and defaults ON
 *    (observed); without this seed a door run can self-update mid-suite and
 *    break the version pin.
 *  - `[models] default = <model>` when given — `grok mcp add` PRESERVES
 *    pre-existing sections (observed), so the seed survives registration.
 * No credentials are written: auth travels via XAI_API_KEY env only.
 */
export function seedGrokConfig(home: string, opts?: { defaultModel?: string }): string {
  const grokHome = path.join(home, '.grok');
  fs.mkdirSync(grokHome, { recursive: true });
  const model = opts?.defaultModel;
  const doc = `[cli]\nauto_update = false\n${model ? `\n[models]\ndefault = "${model}"\n` : ''}`;
  fs.writeFileSync(path.join(grokHome, 'config.toml'), doc, 'utf-8');
  return grokHome;
}

/**
 * Stage a `gbrain` binary into a fresh bin dir so the DOCUMENTED registration
 * shape (`grok mcp add gbrain -- gbrain serve --surface verbs`, bare command
 * resolved via PATH — observed working v1.0.4) is what the door exercises.
 * Compiled binary copy when available; otherwise an executable sh wrapper
 * exec'ing `bun run src/cli.ts` so the fallback lane survives staging.
 */
export function stageGbrainBinDir(repoRoot: string, dir: string): { kind: 'compiled' | 'bun-run' } {
  fs.mkdirSync(dir, { recursive: true });
  const target = path.join(dir, 'gbrain');
  const { binPath } = ensureCompiledGbrain(repoRoot);
  if (binPath) {
    fs.copyFileSync(binPath, target);
    fs.chmodSync(target, 0o755);
    return { kind: 'compiled' };
  }
  const cli = path.join(repoRoot, 'src', 'cli.ts');
  // The path is interpolated single-quoted into an sh shim — reject the same
  // metachar set validateBinPathEnv guards, rather than trying to escape.
  if (/['"`$\\\n\r]/.test(cli)) {
    throw new Error(`stageGbrainBinDir: repo path contains shell-active characters unsafe for the shim: ${cli}`);
  }
  fs.writeFileSync(target, `#!/bin/sh\nexec bun run '${cli}' "$@"\n`, { mode: 0o755 });
  return { kind: 'bun-run' };
}

export interface GrokTurnOpts {
  prompt: string;
  cwd: string;
  home: string;
  timeoutMs?: number;
  /** Per-call model pin (authoritative — immune to config rewrites). */
  model?: string;
  /** Disable grok's built-in web search + fetch tools (observed flag). */
  disableWebSearch?: boolean;
  /** Staged gbrain bin dir — PATH-prepended so the bare-`gbrain` MCP
   *  registration resolves when grok spawns the server DURING the turn
   *  (without this the doctor preflight passes but the paid turn cannot
   *  start the server on a clean runner). */
  binDir?: string;
}

export interface GrokTurnResult {
  /** plain output format: stdout is the final response text. */
  finalText: string;
  exitCode: number | null;
  timedOut: boolean;
  stderrText: string;
}

/**
 * Drive one `grok -p` turn against a hermetic HOME + GROK_HOME. Plain output
 * format (final text on stdout — observed). The permission posture is
 * deliberately unset pending the authed observation (GROK-CLI-PIN.md); the
 * JSON event-stream shapes are also unobserved, so there is no parseGrokJson
 * yet — the door's tool-call assertion stays gated on that observation.
 */
export async function grokOneShotTurn(opts: GrokTurnOpts): Promise<GrokTurnResult> {
  const bin = resolveGrokBinary();
  if (!bin) throw new Error('grokOneShotTurn: grok binary not found');
  return runOneShotSpawn({
    argv: [
      bin, '-p', opts.prompt, '--output-format', 'plain',
      ...(opts.model ? ['-m', opts.model] : []),
      ...(opts.disableWebSearch ? ['--disable-web-search'] : []),
    ],
    cwd: opts.cwd,
    env: grokChildEnv(opts.home, { binDir: opts.binDir }),
    timeoutMs: opts.timeoutMs ?? 240_000,
  });
}

// ────────────────────────────────────────────────────────────────────────────
// 5a-opencode. opencode (SST, opencode.ai) — all shapes observed against
//              v1.18.18 (docs/mcp/OPENCODE-CLI-PIN.md). First consumer of the
//              5a-core door-family factories. opencode ≠ OpenClaw ≠ the
//              renamed-to-Crush ancestor sharing the binary name.
// ────────────────────────────────────────────────────────────────────────────

/** Locate the real `opencode` binary. $OPENCODE_BIN (fail-closed) first —
 *  the binary name has colliding claimants, and the bare-semver `--version`
 *  shape (T1) is the runtime discriminator. */
export const resolveOpencodeBinary = makeBinaryResolver({
  envVar: 'OPENCODE_BIN',
  binName: 'opencode',
  candidates: (home) => [
    '/opt/homebrew/bin/opencode',
    '/usr/local/bin/opencode',
    `${home}/.local/bin/opencode`,
    `${home}/.npm-global/bin/opencode`,
    `${home}/.bun/bin/opencode`,
  ],
  nvmSweep: true,
  pathSweep: true,
});

/**
 * The opencode door's PAID leg gates on a NON-EMPTY ANTHROPIC key (GSTACK_
 * promotion applies). Deliberately NOT an "is opencode usable" probe — the
 * keyless anonymous free tier answers headless runs AND drives MCP tool
 * calls (observed; the door's core SMOKE rides it), so the paid leg is an
 * optional hardening tier, and a blank CI secret ⇒ skip, never a paid
 * failing test. auth.json probing is deliberately absent until its shape is
 * observed post-login (OPENCODE-CLI-PIN.md §Pending auth).
 */
export function hasOpencodeAuth(): boolean {
  return Boolean(promotedEnv(process.env).ANTHROPIC_API_KEY?.trim());
}

/**
 * Hermetic env for spawning opencode itself: HOME + BOTH XDG dirs redirected
 * (config/auth/data all move — verified on macOS; belt-and-suspenders), the
 * env half of the double autoupdate kill, ANTHROPIC_API_KEY re-admitted
 * only with paid: true (default-deny stays intact for every other
 * child). Deletes the OTHER providers' keys (single-auth-source discipline —
 * the paid leg pins an anthropic/* model) and the OPENCODE_CONFIG* trio
 * (observed inert in 1.18.18, but a future release activating them must not
 * let ambient values shadow the hermetic config). GITHUB_* step-metadata
 * scrub via the shared factory.
 */
const keylessOpencodeChildEnv = makeAgentChildEnv({
  overrides: (home) => ({
    HOME: home,
    XDG_CONFIG_HOME: path.join(home, '.config'),
    XDG_DATA_HOME: path.join(home, '.local', 'share'),
    OPENCODE_DISABLE_AUTOUPDATE: '1',
  }),
  deleteKeys: [
    'ANTHROPIC_API_KEY', 'ANTHROPIC_BASE_URL',
    'OPENAI_API_KEY', 'XAI_API_KEY', 'OPENROUTER_API_KEY',
    'GOOGLE_GENERATIVE_AI_API_KEY', 'GEMINI_API_KEY', 'ANTHROPIC_AUTH_TOKEN',
    'OPENCODE_CONFIG', 'OPENCODE_CONFIG_DIR', 'OPENCODE_CONFIG_CONTENT',
  ],
});

export function opencodeChildEnv(home: string, opts?: { binDir?: string; paid?: boolean }): NodeJS.ProcessEnv {
  const env = keylessOpencodeChildEnv(home, opts);
  if (opts?.paid) env.ANTHROPIC_API_KEY = promotedEnv(process.env).ANTHROPIC_API_KEY?.trim() || undefined;
  return env;
}

/**
 * Seed a hermetic <XDG_CONFIG_HOME>/opencode/opencode.json BEFORE any
 * opencode spawn:
 *  - `"autoupdate": false` — the config half of the double kill (the env
 *    half rides opencodeChildEnv); a door run must never self-update
 *    mid-suite and break the version pin.
 *  - `"model": <model>` when given (provider/model form). Per-call `-m`
 *    stays authoritative; the seed covers spawns that take no flag.
 * Plain JSON (comments legal but not needed here); `opencode mcp add`
 * preserves pre-existing keys (observed), so the seed survives registration.
 * No credentials are written: paid auth travels via ANTHROPIC_API_KEY only.
 */
export function seedOpencodeConfig(home: string, opts?: { defaultModel?: string }): string {
  const cfgDir = path.join(home, '.config', 'opencode');
  fs.mkdirSync(cfgDir, { recursive: true });
  const doc: Record<string, unknown> = {
    $schema: 'https://opencode.ai/config.json',
    autoupdate: false,
    ...(opts?.defaultModel ? { model: opts.defaultModel } : {}),
  };
  const cfgPath = path.join(cfgDir, 'opencode.json');
  fs.writeFileSync(cfgPath, `${JSON.stringify(doc, null, 2)}\n`, 'utf-8');
  return cfgPath;
}

export interface OpencodeTurnOpts {
  prompt: string;
  cwd: string;
  home: string;
  timeoutMs?: number;
  /** Per-call model pin (provider/model — authoritative over the config seed). */
  model?: string;
  /** 'json' emits the NDJSON event stream parseOpencodeJsonl pins. */
  format?: 'default' | 'json';
  /** Staged gbrain bin dir — PATH-prepended so a PATH-resolved registration
   *  resolves when opencode spawns the server during the turn. */
  binDir?: string;
  paid?: boolean;
}

export interface OpencodeTurnResult extends OneShotSpawnResult {
  /** error.error of each main-turn `stream error` opencode logged during this turn. */
  streamErrors: string[];
  /** The quota/rate-limit refusal that ended the turn early, if any. */
  providerRefusal?: string;
}

/** #6049: opencode answers a quota refusal (free tier: "Free usage limit
 *  reached", HTTP 429) by retrying after the server's retry-after, hours
 *  later, with nothing on stdout. Waiting can never produce an answer. A
 *  provider rate limit ("rate limit exceeded", Anthropic's 429) clears in
 *  seconds and opencode's retry recovers from it, so it never matches. */
const OPENCODE_QUOTA_REFUSAL = /usage limit|quota/i;

/** Main-turn (`small=false`) `stream error` lines appended to opencode's
 *  file log (<XDG_DATA_HOME>/opencode/log) since `offsets` was taken. */
function opencodeStreamErrorsSince(logDir: string, offsets: Map<string, number>): string[] {
  let files: string[];
  try { files = fs.readdirSync(logDir).sort(); } catch { return []; }
  const errors: string[] = [];
  for (const name of files) {
    let text: string;
    try { text = fs.readFileSync(path.join(logDir, name)).subarray(offsets.get(name) ?? 0).toString('utf-8'); } catch { continue; }
    for (const line of text.split('\n')) {
      if (!line.includes('message="stream error"') || !line.includes(' small=false ')) continue;
      const m = line.match(/error\.error="((?:[^"\\]|\\.)*)"/);
      errors.push(m ? m[1].replace(/\\(.)/g, '$1') : line);
    }
  }
  return errors;
}

function opencodeLogOffsets(logDir: string): Map<string, number> {
  const offsets = new Map<string, number>();
  try {
    for (const name of fs.readdirSync(logDir)) offsets.set(name, fs.statSync(path.join(logDir, name)).size);
  } catch { /* no log yet */ }
  return offsets;
}

/**
 * Drive one `opencode run` turn against a hermetic HOME + XDG dirs. Default
 * format prints the final answer ALONE on stdout (banner/UI on stderr —
 * observed); no permission flag is needed for MCP tool calls (observed:
 * --auto not passed, deliberately). Shared spawn core: kill(9) escalation +
 * bounded drain. Provider stream errors come from opencode's own file log;
 * a quota refusal ends the turn at once instead of at the timeout.
 */
export async function opencodeOneShotTurn(opts: OpencodeTurnOpts): Promise<OpencodeTurnResult> {
  const bin = resolveOpencodeBinary();
  if (!bin) throw new Error('opencodeOneShotTurn: opencode binary not found');
  const logDir = path.join(opts.home, '.local', 'share', 'opencode', 'log');
  const offsets = opencodeLogOffsets(logDir);
  const res = await runOneShotSpawn({
    argv: [
      bin, 'run', opts.prompt, '--pure',
      '--format', opts.format ?? 'default',
      ...(opts.model ? ['-m', opts.model] : []),
    ],
    cwd: opts.cwd,
    env: opencodeChildEnv(opts.home, { binDir: opts.binDir, paid: opts.paid }),
    timeoutMs: opts.timeoutMs ?? 240_000,
    abortWhen: () => opencodeStreamErrorsSince(logDir, offsets).find((e) => OPENCODE_QUOTA_REFUSAL.test(e)),
  });
  const { abortReason, ...rest } = res;
  return {
    ...rest,
    streamErrors: opencodeStreamErrorsSince(logDir, offsets),
    ...(abortReason !== undefined ? { providerRefusal: abortReason } : {}),
  };
}

// ────────────────────────────────────────────────────────────────────────────
// 5b. Fast gbrain MCP server command (compiled binary, cached; bun-run fallback)
// ────────────────────────────────────────────────────────────────────────────

/**
 * A resolved launch spec for the gbrain MCP stdio server. The door tests
 * register THIS as their MCP server so the child agent's first tool call finds
 * a server that is already up. A compiled binary starts fast; `bun run
 * src/cli.ts serve` cold-transpiles the whole CLI on every spawn and can miss
 * an agent's tool-call window (the source of the codex "the available gbrain
 * mcp calls were cancelled" flake). `kind` lets the caller widen the turn
 * timeout when we fell back to the slow path.
 */
export interface GbrainServerCommand {
  command: string;
  /** Full arg vector INCLUDING the `serve` subcommand + any extra flags. */
  args: string[];
  kind: 'compiled' | 'bun-run';
}

// Module-level cache: compile the binary at most once per test process.
let _compiledBin: string | null = null;
let _compileTried = false;
let _compileReason = '';
let _compileBuildDir: string | null = null;

/**
 * Verify a freshly-built `gbrain` binary can actually stand up a PGLite brain.
 * As of the embedded-assets fix (src/core/pglite-embedded-assets.ts), `bun
 * build --compile` binaries DO carry PGLite's WASM runtime + extension tarballs
 * (`pglite.wasm`, `initdb.wasm`, `pglite.data`, `vector.tar.gz`,
 * `pg_trgm.tar.gz`) — embedded via `with { type: 'file' }` and fed to PGLite
 * through PGliteOptions — so a compiled `gbrain init --pglite` now succeeds
 * where it used to ENOENT on those assets (Bun vfs #1340). This probe is the
 * runtime backstop: it confirms the embedding held for THIS binary before we
 * trust it as the door-test MCP server (the brain is keyless PGLite). If the
 * embedding ever regresses, the probe fails and we fall back to `bun run`.
 * `init` is the cheapest exercise of the WASM path that terminates on its own
 * (unlike `serve`, which either waits on stdin or bails early on a brain-less
 * home). scripts/check-pglite-embedded.sh guards the same property in CI.
 */
function probeCompiledPglite(binPath: string): { ok: boolean; reason: string } {
  const probeHome = fs.mkdtempSync(path.join(os.tmpdir(), 'gb-agent-probe-'));
  try {
    const res = spawnSync(binPath, ['init', '--pglite', '--no-embedding', '--non-interactive'], {
      env: { ...process.env, HOME: probeHome, GBRAIN_HOME: probeHome, GBRAIN_SKIP_STARTUP_HOOKS: '1' },
      encoding: 'utf8',
      timeout: 60_000,
      stdio: ['ignore', 'pipe', 'pipe'],
    });
    const stderr = `${res.stdout ?? ''}\n${res.stderr ?? ''}`;
    const wasmBroken = /PGLite failed to initialize|Extension bundle not found|\$bunfs|pglite\.data/.test(stderr);
    if (res.error) return { ok: false, reason: `compiled \`gbrain init --pglite\` probe error: ${res.error.message}` };
    if (wasmBroken || res.status !== 0) {
      const lines = stderr.split('\n').map((l) => l.trim()).filter(Boolean);
      const markerLine =
        lines.find((l) => /PGLite failed to initialize|Extension bundle not found|\$bunfs|pglite\.data/.test(l)) ??
        lines[0] ??
        `exit ${res.status}`;
      return {
        ok: false,
        reason:
          `compiled \`gbrain\` cannot open a PGLite brain — \`bun build --compile\` does not embed ` +
          `PGLite's WASM/extension payload (Bun vfs #1340): ${markerLine.slice(0, 160)}`,
      };
    }
    return { ok: true, reason: '' };
  } catch (e) {
    return { ok: false, reason: `compiled PGLite probe threw: ${(e as Error).message}` };
  } finally {
    try { fs.rmSync(probeHome, { recursive: true, force: true }); } catch { /* best-effort */ }
  }
}

/**
 * Build a standalone `gbrain` binary once via `bun build --compile` into a
 * cached temp path AND verify it can serve a PGLite brain. Returns the path (or
 * null + a reason) — null covers both "compile unavailable in this sandbox" and
 * "compile succeeds but the binary can't open PGLite" (#1340). Mirrors
 * test/e2e/bootstrap-compiled-binary.serial.test.ts. Fail-soft: every error is
 * captured as a reason string, never thrown, so any failure degrades to the
 * bun-run fallback instead of hard-failing the door suite.
 */
export function ensureCompiledGbrain(repoRoot: string): { binPath: string | null; reason: string } {
  // CI short-circuit: a workflow can compile ONCE in a dedicated step and
  // export GBRAIN_COMPILED_BIN — the module-global cache below is per-process,
  // so two `bun test` invocations in one job would otherwise compile twice.
  const prebuilt = process.env.GBRAIN_COMPILED_BIN?.trim();
  if (prebuilt && prebuilt.startsWith('/')) {
    try {
      fs.accessSync(prebuilt, fs.constants.X_OK);
      return { binPath: prebuilt, reason: '' };
    } catch { /* fall through to the normal compile path */ }
  }
  if (_compileTried) return { binPath: _compiledBin, reason: _compileReason };
  _compileTried = true;
  try {
    const buildDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gb-agent-bin-'));
    _compileBuildDir = buildDir;
    const binPath = path.join(buildDir, 'gbrain');
    const res = spawnSync('bun', ['build', '--compile', '--outfile', binPath, 'src/cli.ts'], {
      cwd: repoRoot,
      encoding: 'utf8',
      timeout: 240_000,
      maxBuffer: 64 * 1024 * 1024,
    });
    if (res.error) {
      _compileReason = `bun build --compile unavailable: ${res.error.message}`;
    } else if (res.status !== 0) {
      _compileReason = `bun build --compile exited ${res.status}: ${(res.stderr ?? '').slice(-1000)}`;
    } else if (!fs.existsSync(binPath)) {
      _compileReason = 'bun build --compile exited 0 but produced no binary';
    } else {
      const probe = probeCompiledPglite(binPath);
      if (probe.ok) _compiledBin = binPath;
      else _compileReason = probe.reason;
    }
  } catch (e) {
    _compileReason = `bun build --compile threw: ${(e as Error).message}`;
  }
  return { binPath: _compiledBin, reason: _compileReason };
}

// Best-effort cleanup of the compiled-binary temp dir at process exit.
process.on('exit', () => {
  if (_compileBuildDir) {
    try { fs.rmSync(_compileBuildDir, { recursive: true, force: true }); } catch { /* best-effort */ }
  }
});

/**
 * Resolve the gbrain MCP server launch spec: a compiled binary
 * (`{command:<bin>, args:['serve', ...extra]}`) when `bun build --compile`
 * both succeeds AND can open a PGLite brain, else the `bun run src/cli.ts
 * serve` fallback. `extraArgs` are appended after `serve` (e.g.
 * `['--surface','full']` for the codex door). The env
 * (GBRAIN_HOME/GBRAIN_SOURCE) is layered on by the caller and stays identical
 * across both kinds.
 *
 * NOTE: the `bun build --compile` binary now embeds PGLite's WASM/extension
 * payload (src/core/pglite-embedded-assets.ts, Bun vfs #1340), so this resolves
 * to the fast `compiled` path in practice. The `bun-run` fallback stays wired
 * as a safety net for sandboxes where compile is unavailable or the probe fails
 * (its server is measured ready to answer `tools/list` in ~300ms, and the door
 * tests lean on the bounded SMOKE retry, not server speed, for robustness).
 */
export function resolveGbrainServerCommand(repoRoot: string, extraArgs: string[] = []): GbrainServerCommand {
  const { binPath, reason } = ensureCompiledGbrain(repoRoot);
  if (binPath) {
    return { command: binPath, args: ['serve', ...extraArgs], kind: 'compiled' };
  }
  console.error(
    `[agent-harness] compiled gbrain unavailable, falling back to \`bun run src/cli.ts\` ` +
      `(slower MCP startup, wider readiness window): ${reason}`,
  );
  return {
    command: 'bun',
    args: ['run', path.join(repoRoot, 'src', 'cli.ts'), 'serve', ...extraArgs],
    kind: 'bun-run',
  };
}

// ────────────────────────────────────────────────────────────────────────────
// 6. MCP config for a Claude Code door test
// ────────────────────────────────────────────────────────────────────────────

export interface GbrainMcpConfigOpts {
  path: string;
  /** Resolved server launch spec (compiled bin or bun-run fallback). */
  server: { command: string; args: string[] };
  gbrainHome: string;
  sourceId: string;
}

/**
 * Write a Claude Code `--mcp-config` JSON that runs THIS repo's gbrain over
 * stdio, pinned to a hermetic GBRAIN_HOME + source. The server command comes
 * from `resolveGbrainServerCommand` (compiled binary preferred, `bun run
 * src/cli.ts serve` fallback) so startup is fast enough that the child agent's
 * first tool call doesn't get cancelled. Mirrors `claude mcp add gbrain --
 * gbrain serve` from docs/mcp/CLAUDE_CODE.md.
 */
export function writeGbrainMcpConfig(opts: GbrainMcpConfigOpts): void {
  const cfg = {
    mcpServers: {
      gbrain: {
        command: opts.server.command,
        args: opts.server.args,
        env: {
          GBRAIN_HOME: opts.gbrainHome,
          GBRAIN_SOURCE: opts.sourceId,
        },
      },
    },
  };
  fs.mkdirSync(path.dirname(opts.path), { recursive: true });
  fs.writeFileSync(opts.path, JSON.stringify(cfg, null, 2));
}

// ────────────────────────────────────────────────────────────────────────────
// 7. Seed a real keyless PGLite brain the spawned `gbrain serve` will read
// ────────────────────────────────────────────────────────────────────────────

const put_page = operations.find((o) => o.name === 'put_page') as Operation | undefined;

export interface SeededBrain {
  fact: string;
  entity: string;
  query: string;
}

/**
 * Initialize a keyless PGLite brain at GBRAIN_HOME=<home> and seed ONE page
 * with a distinctive, 100%-synthetic fact so a door test can assert the agent
 * recalls it over MCP. Persistent on disk (so the spawned `gbrain serve`
 * subprocess reads the same brain), keyless (embedding_disabled) so it runs
 * with no API key, skills published so the verbs surface is available.
 *
 * Temporarily pins process.env.GBRAIN_HOME while creating the brain, then
 * restores it — the door test sets GBRAIN_HOME on the spawned child via the
 * MCP config's env block, not on this process.
 */
export async function seedBrainForAgent(
  home: string,
  sourceId: string,
  opts?: { entity?: string; fact?: string; query?: string; slug?: string },
): Promise<SeededBrain> {
  if (!put_page) throw new Error('seedBrainForAgent: put_page op not registered');

  // Defaults are the committed synthetic fact (hermes/claude doors). Callers
  // whose agent has filesystem/shell tools in reach pass a PER-RUN nonce fact
  // instead — the committed string is greppable in the checkout, so recall of
  // it proves nothing against an agent that can read the repo (grok door).
  const entity = opts?.entity ?? 'Summit Robotics';
  const fact = opts?.fact ?? 'Summit Robotics runs the Rivermouth fulfillment center.';
  const query = opts?.query ?? 'Where does Summit Robotics run its fulfillment center?';

  const savedHome = process.env.GBRAIN_HOME;
  process.env.GBRAIN_HOME = home;
  try {
    const dbPath = gbrainPath('brain.pglite'); // <home>/.gbrain/brain.pglite

    const engine = new PGLiteEngine();
    await engine.connect({ database_path: dbPath, engine: 'pglite' });
    await engine.initSchema();
    try {
      // Register a non-default source so GBRAIN_SOURCE routing has a real row.
      if (sourceId !== 'default') {
        const srcDir = path.join(home, `source-${sourceId}`);
        fs.mkdirSync(srcDir, { recursive: true });
        // Door tests can make HOME a Git checkout. Give this source its own
        // worktree so .gbrain/persistence remains outside the canonical root.
        const initialized = spawnSync('git', ['init', '-q', srcDir], { encoding: 'utf8' });
        if (initialized.status !== 0) throw new Error(`Cannot initialize the synthetic source worktree: ${initialized.stderr}`);
        try {
          await addSource(engine, { id: sourceId, localPath: srcDir, force: true });
        } catch (error) {
          if (!(error instanceof SourceOpError) || error.code !== 'source_id_taken') throw error;
        }
      }

      const ctx: OperationContext = {
        engine,
        config: { engine: 'pglite' } as never,
        logger: { info: () => {}, warn: () => {}, error: () => {} },
        dryRun: false,
        remote: false,
        sourceId,
      };
      await put_page.handler(ctx, {
        slug: opts?.slug ?? 'companies/summit-robotics',
        content: `# ${entity}\n\n${fact}\n`,
      });
    } finally {
      // Release the PGLite lock so the spawned `gbrain serve` can open the
      // same data dir.
      await engine.disconnect();
    }

    // Persist a keyless config so the spawned `gbrain serve` reads the same
    // engine + path and doesn't try to reach an embedding provider.
    const config: GBrainConfig = {
      engine: 'pglite',
      database_path: dbPath,
      embedding_disabled: true,
      mcp: { publish_skills: true },
    } as unknown as GBrainConfig;
    saveConfig(config);
  } finally {
    if (savedHome === undefined) delete process.env.GBRAIN_HOME;
    else process.env.GBRAIN_HOME = savedHome;
  }

  return { fact, entity, query };
}

// ────────────────────────────────────────────────────────────────────────────
// Plugin-lane probes (EV11/EV12)
// ────────────────────────────────────────────────────────────────────────────

/** True when the codex binary supports the plugin/marketplace subcommands. */
export function codexSupportsPlugins(bin: string): boolean {
  try {
    const r = spawnSync(bin, ['plugin', '--help'], { encoding: 'utf8', timeout: 15_000 });
    return r.status === 0;
  } catch {
    return false;
  }
}

/** True when the claude binary supports the plugin subcommands. */
export function claudeSupportsPlugins(bin: string): boolean {
  try {
    const r = spawnSync(bin, ['plugin', '--help'], { encoding: 'utf8', timeout: 15_000 });
    return r.status === 0;
  } catch {
    return false;
  }
}

/**
 * Deterministic MCP surface oracle (EV12): spawn an MCP stdio server command,
 * run the initialize handshake, and return the advertised tool names via a
 * real `tools/list` — never an LLM-output assertion. Used by the plugin e2e
 * to pin "the snapshot launcher serves exactly the starter surface".
 */
export async function mcpToolsListProbe(opts: {
  command: string;
  args: string[];
  cwd?: string;
  env?: Record<string, string | undefined>;
  timeoutMs?: number;
}): Promise<{ tools: string[]; stderr: string }> {
  const timeoutMs = opts.timeoutMs ?? 60_000;
  const proc = Bun.spawn([opts.command, ...opts.args], {
    cwd: opts.cwd,
    env: opts.env as Record<string, string>,
    stdin: 'pipe',
    stdout: 'pipe',
    stderr: 'pipe',
  });

  const frames = [
    { jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'gbrain-e2e-probe', version: '0' } } },
    { jsonrpc: '2.0', method: 'notifications/initialized' },
    { jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} },
  ];
  proc.stdin.write(frames.map((f) => JSON.stringify(f)).join('\n') + '\n');
  try { await proc.stdin.end(); } catch { /* already closed */ }

  const stderrDone = new Response(proc.stderr).text();
  const reader = proc.stdout.getReader();
  const decoder = new TextDecoder();
  let buf = '';
  let tools: string[] | null = null;
  const deadline = Date.now() + timeoutMs;
  // Race each read against the remaining deadline: a child that opens stdout
  // but never writes would otherwise block `reader.read()` forever, past the
  // deadline the while-condition can only check between reads.
  const readOrTimeout = () => Promise.race([
    reader.read(),
    new Promise<{ done: true; value: undefined }>((res) =>
      setTimeout(() => res({ done: true, value: undefined }), Math.max(0, deadline - Date.now())),
    ),
  ]);
  try {
    while (tools === null && Date.now() < deadline) {
      const { done, value } = await readOrTimeout();
      if (done) break;
      buf += decoder.decode(value, { stream: true });
      const parts = buf.split('\n');
      buf = parts.pop() || '';
      for (const line of parts) {
        if (!line.trim()) continue;
        try {
          const obj = JSON.parse(line);
          if (obj.id === 2 && obj.result?.tools) {
            tools = obj.result.tools.map((t: { name: string }) => t.name);
          }
        } catch {
          /* non-JSON stderr leakage or partial frame — skip */
        }
      }
    }
  } finally {
    try { proc.kill(); } catch { /* already dead */ }
  }
  const stderr = await stderrDone.catch(() => '');
  if (tools === null) {
    throw new Error(`mcpToolsListProbe: no tools/list response within ${timeoutMs}ms — stderr:\n${stderr.slice(0, 2000)}`);
  }
  return { tools, stderr };
}