Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
25.9 KB
Raw Blame
/**
 * opencode-json.ts — managed `mcp.<name>` entry writer for opencode's JSONC
 * configs (see TARGETS['opencode-2026-08'] in host-specs.ts and
 * docs/mcp/OPENCODE-CLI-PIN.md for the verified format assumptions).
 *
 * Why a direct writer exists: `opencode mcp add` always targets the
 * user-global opencode.jsonc (no scope flag), cannot set file modes (the
 * harness lane's inline bearer needs 0600), and requires the binary on the
 * box — the writer covers project scope, secret hygiene, and offline/
 * pre-install registration with one code path.
 *
 * Safety invariants (codex-toml.ts analog, adapted for JSONC):
 * - ALL edits go through jsonc-parser `modify`/`applyEdits` — text splicing
 *   that preserves comments, formatting, and EOLs byte-for-byte outside the
 *   edited range. opencode's own `mcp add` preserves comments (observed);
 *   gbrain matches that bar. JSON.parse is never used on config text.
 * - Ownership is a STRUCTURAL FINGERPRINT, not a marker key (unknown keys
 *   are tolerated by opencode 1.18.18, but a future strict-schema flip must
 *   not brick the user's opencode): a local entry is ours when command[0] is
 *   gbrain-shaped AND environment.GBRAIN_SOURCE exists; source EQUALITY
 *   (not mere presence) splits `ours-same-source` from `ours-other-source`
 *   ([FIX7] parity with verifyMcpTargetsWorkspace) — callers warn before
 *   overwriting another workspace's registration. A remote entry is ours
 *   when its url matches the caller's receipt, or when its Authorization
 *   header carries the `{env:GBRAIN_REMOTE_TOKEN}` interpolation (only the
 *   connect lane writes that). Anything else under our name is FOREIGN —
 *   refuse, never guess.
 * - Read-failure classes are distinct: ENOENT → fresh file; empty/whitespace
 *   → treated as `{}`; unreadable (EACCES etc.) → refuse loudly (never
 *   clobber what cannot be read). A file that fails even JSONC parsing →
 *   refuse with a paste-by-hand snippet.
 * - Post-render validation before rename: the rendered text is re-parsed,
 *   our entry deep-asserted, and every OTHER top-level key asserted to
 *   survive; on any failure the original file is untouched.
 * - Secrets hygiene: when the entry carries an inline bearer the target is
 *   forced 0600. Backups are UNIQUE per operation (`<config>.bak-<hex>`,
 *   returned in the result) so two overlapping runs can never clobber each
 *   other's snapshot, and a backup is chmod'd 0600 whenever the COPIED
 *   content carries an inline bearer (write AND remove paths — on re-runs
 *   the backup carries the PREVIOUS token). Token-free entries inherit the
 *   file's existing mode.
 * - Concurrency: callers hold acquireBootstrapLock (config-dir →
 *   opencode-dir ordering, mirroring the codex lanes in harness.ts) — the
 *   writer itself is lock-free like codex-toml.ts.
 */

import { randomBytes } from 'node:crypto';
import { isHookLauncherPath } from '../setup/hook-launcher.ts';
import { chmodSync, copyFileSync, existsSync, readFileSync } from 'node:fs';
import { applyEdits, modify, parse as parseJsonc, printParseErrorCode, type ParseError } from 'jsonc-parser';
import { atomicWriteTextFile } from './atomic-write.ts';
import { opencodeGlobalSiblingPath } from './host-specs.ts';

export const GBRAIN_REMOTE_TOKEN_ENV = 'GBRAIN_REMOTE_TOKEN';
const ENV_INTERPOLATION = `{env:${GBRAIN_REMOTE_TOKEN_ENV}}`;

// ── Entry shapes ────────────────────────────────────────────────────────────

export interface OpencodeLocalEntry {
  kind: 'local';
  name: string;
  /** argv — command[0] is PATH-resolved "gbrain" (project scope, committed-
   * file candidate) or an absolute binary path (user scope). */
  command: string[];
  environment: Record<string, string>;
}

export interface OpencodeRemoteEntry {
  kind: 'remote';
  name: string;
  url: string;
  /** 'inline' writes `Bearer <token>` (harness lane — framework-spawned
   * opencode inherits no shell profile; file forced 0600). 'env' writes the
   * `{env:GBRAIN_REMOTE_TOKEN}` interpolation (connect lane — token never
   * enters the file). */
  tokenMode: 'inline' | 'env';
  bearerToken?: string;
}

export type OpencodeMcpEntry = OpencodeLocalEntry | OpencodeRemoteEntry;

export type OpencodeEntryKind =
  | 'absent'
  | 'ours-same-source'
  | 'ours-other-source'
  | 'foreign';

export interface OpencodeEntryExpectation {
  /** GBRAIN_SOURCE the caller is registering (local entries). */
  sourceId?: string;
  /** Serve url from the caller's receipt (remote entries). */
  url?: string;
}

export interface WriteOpencodeEntryResult {
  configPath: string;
  /** True when a prior gbrain-owned entry was replaced (idempotent re-run). */
  replacedPrior: boolean;
  /** Kind of the pre-existing entry (what was there before this write). */
  priorKind: OpencodeEntryKind;
  /** Unique per-write backup (`<config>.bak-<hex>`) of the prior file, or
   * null on a fresh file. Callers that roll back restore from THIS path. */
  backupPath: string | null;
  /** The EXACT text this write landed — rollback callers compare the current
   * file content against it before restoring (a mismatch means a newer
   * registration exists and a restore would clobber it). */
  writtenText: string;
  notes: string[];
}

export interface RemoveOpencodeEntryResult {
  configPath: string;
  removed: boolean;
  backupPath: string | null;
  notes: string[];
}

// ── Read + parse (failure classes are distinct) ─────────────────────────────

interface RawConfig {
  text: string;
  existed: boolean;
}

function readConfigRaw(configPath: string): RawConfig {
  if (!existsSync(configPath)) return { text: '', existed: false };
  let text: string;
  try {
    text = readFileSync(configPath, 'utf8');
  } catch (e) {
    throw new Error(
      `${configPath} exists but cannot be read (${(e as Error).message}) — ` +
        `refusing to touch a config that cannot be read back. Fix permissions and re-run.`,
    );
  }
  return { text, existed: true };
}

/**
 * Parse config text as JSONC (opencode's effective grammar for BOTH .json
 * and .jsonc files — OPENCODE-CLI-PIN.md §Config format). Empty/whitespace
 * text parses as `{}`. Text that fails even JSONC parsing throws with a
 * paste-by-hand snippet so the user is never stranded.
 */
export function parseOpencodeConfig(text: string, configPath: string, snippet?: string): Record<string, unknown> {
  if (text.trim() === '') return {};
  const errors: ParseError[] = [];
  const parsed = parseJsonc(text, errors, { allowTrailingComma: true }) as unknown;
  if (errors.length > 0) {
    const first = errors[0];
    throw new Error(
      `${configPath} does not parse as JSONC (${printParseErrorCode(first.error)} at offset ${first.offset}) — ` +
        `opencode itself cannot read it either. Fix the file, or add the entry by hand:\n${snippet ?? ''}`,
    );
  }
  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
    throw new Error(`${configPath} is valid JSONC but not an object — fix the file and re-run.`);
  }
  return parsed as Record<string, unknown>;
}

// ── Ownership fingerprint ───────────────────────────────────────────────────

function isGbrainShapedCommand(command: unknown): boolean {
  if (!Array.isArray(command) || command.length === 0) return false;
  const head = command[0];
  if (typeof head !== 'string') return false;
  if (isHookLauncherPath(head)) return isGbrainShapedCommand(command.slice(1)); // user scope through the hook launcher (#8435)
  if (head === 'gbrain') return true; // PATH-resolved (project scope)
  if (/[\\/]gbrain$/.test(head)) return true; // absolute binary path
  // bun-run wrapper shim lane: `bun run <...>/gbrain/src/cli.ts` etc. The
  // arg match is ANCHORED like the head-path lane: some arg must carry an
  // exact `gbrain` path segment (or a hyphen-suffixed `gbrain-*` one) — a
  // loose substring scan classified `bun run /opt/gbrainy-fork/src/cli.ts`
  // as ours (both the `gbrain` substring and a bare `src/cli.ts$` matched).
  // A gbrain-less `bun run /repo/src/cli.ts` is now NOT ours (fail-closed:
  // gbrain refuses to touch what it cannot prove it owns).
  if (head === 'bun' || head.endsWith('/bun')) {
    return command.some((a) => typeof a === 'string' && /(?:^|[\\/])gbrain(?:[\\/-]|$)/.test(a));
  }
  // staged shim named gbrain-<suffix> (e.g. gbrain-shim from stageBinDir) —
  // hyphen-anchored so a foreign /opt/bin/gbrainy is NOT ours.
  return /[\\/]gbrain-[^\\/]*$/.test(head);
}

/**
 * Classify the `mcp.<name>` entry in parsed config. The arbiter every lane
 * consults before writing or removing (codexBlockOwnsName analog).
 */
export function opencodeEntryKind(
  parsed: Record<string, unknown>,
  name: string,
  expect: OpencodeEntryExpectation = {},
): OpencodeEntryKind {
  const mcp = parsed.mcp;
  if (typeof mcp !== 'object' || mcp === null) return 'absent';
  const entry = (mcp as Record<string, unknown>)[name];
  if (entry === undefined) return 'absent';
  if (typeof entry !== 'object' || entry === null) return 'foreign';
  const e = entry as Record<string, unknown>;

  if (e.type === 'local') {
    if (!isGbrainShapedCommand(e.command)) return 'foreign';
    const env = e.environment;
    const src =
      typeof env === 'object' && env !== null
        ? (env as Record<string, unknown>).GBRAIN_SOURCE
        : undefined;
    if (typeof src !== 'string' || src === '') return 'foreign';
    // Kind mismatch (red-team): a caller expecting a REMOTE entry (harness /
    // connect lanes pass expect.url) that finds a LOCAL gbrain entry is
    // looking at ANOTHER lane's registration (the workspace stdio lane's) —
    // never `ours-same-source`, or a silent replace (and a later --remove)
    // would eat it. `ours-other-source` fires the refuse/confirm machinery.
    if (expect.url !== undefined) return 'ours-other-source';
    if (expect.sourceId === undefined) return 'ours-same-source';
    return src === expect.sourceId ? 'ours-same-source' : 'ours-other-source';
  }

  if (e.type === 'remote') {
    if (expect.url !== undefined && e.url === expect.url) return 'ours-same-source';
    const headers = e.headers;
    const auth =
      typeof headers === 'object' && headers !== null
        ? (headers as Record<string, unknown>).Authorization
        : undefined;
    if (typeof auth === 'string' && auth.includes(ENV_INTERPOLATION)) {
      // Only the gbrain connect lane writes the {env:GBRAIN_REMOTE_TOKEN}
      // interpolation — unambiguously ours even without a receipt url. But a
      // url mismatch (another serve) OR a LOCAL expectation (expect.sourceId
      // — the workspace stdio lane; the kind-mismatch mirror of the local
      // branch above) is another lane's wiring: ours-other-source.
      return expect.url === undefined && expect.sourceId === undefined
        ? 'ours-same-source'
        : 'ours-other-source';
    }
    return 'foreign';
  }

  return 'foreign';
}

// ── Rendering ───────────────────────────────────────────────────────────────

function entryValue(entry: OpencodeMcpEntry): Record<string, unknown> {
  if (entry.kind === 'local') {
    return {
      type: 'local',
      command: entry.command,
      environment: entry.environment,
      enabled: true,
    };
  }
  const token =
    entry.tokenMode === 'inline'
      ? `Bearer ${entry.bearerToken ?? ''}`
      : `Bearer ${ENV_INTERPOLATION}`;
  return {
    type: 'remote',
    url: entry.url,
    headers: { Authorization: token },
    enabled: true,
  };
}

/** Copy-pasteable snippet for the refusal paths (the user is never stranded).
 * SECURITY: an inline bearer is substituted with a literal placeholder — the
 * snippet rides thrown error messages (parse refusal, foreign refusal), and an
 * error path must never embed the real secret in text that lands in logs,
 * receipts, or stderr. Only the human-facing snippet changes; the write path
 * still renders the real token. */
export function opencodeEntrySnippet(entry: OpencodeMcpEntry): string {
  const safe: OpencodeMcpEntry =
    entry.kind === 'remote' && entry.tokenMode === 'inline'
      ? { ...entry, bearerToken: '<paste-token-here>' }
      : entry;
  return JSON.stringify({ mcp: { [safe.name]: entryValue(safe) } }, null, 2);
}

function assertEntryName(name: string): void {
  if (!/^[A-Za-z0-9_-]+$/.test(name)) {
    throw new Error(
      `MCP server name "${name}" is not a simple key ([A-Za-z0-9_-]+) — pick a simpler --name`,
    );
  }
}

function entryCarriesSecret(entry: OpencodeMcpEntry): boolean {
  return entry.kind === 'remote' && entry.tokenMode === 'inline';
}

/** True when config text carries an INLINE bearer credential (any
 * `Bearer <value>` that is not the `{env:…}` interpolation) — the rule that
 * decides whether a backup copy must be tightened to 0600. */
export function textCarriesInlineBearer(text: string): boolean {
  return /Bearer\s+(?!\{env:)\S/.test(text);
}

/** Unique-suffix backup (`<config>.bak-<hex>`): two overlapping runs can
 * never clobber each other's snapshot. The config-dir lock covers the WRITE,
 * but a backup must survive until the caller's post-write verification (the
 * harness network smoke) — which runs AFTER the lock is released, so a fixed
 * `.bak` name would let run B's writer overwrite run A's snapshot and a
 * failed run A would then restore (and revoke against) run B's state.
 * chmod 0600 whenever the copied content carries an inline bearer
 * (copyFileSync onto a fresh path takes the source mode, but a hand-loosened
 * source must not propagate a loose mode to a token-bearing backup). */
function createUniqueBackup(configPath: string, priorText: string): string {
  const backupPath = `${configPath}.bak-${randomBytes(6).toString('hex')}`;
  copyFileSync(configPath, backupPath);
  if (textCarriesInlineBearer(priorText)) chmodSync(backupPath, 0o600);
  return backupPath;
}

// No explicit eol: jsonc-parser detects and preserves the file's own EOLs
// (verified: a CRLF config keeps CRLF through modify/applyEdits).
const FORMATTING = { formattingOptions: { insertSpaces: true, tabSize: 2 } };

// ── Write ───────────────────────────────────────────────────────────────────

/**
 * Idempotently write the managed `mcp.<name>` entry via a comment-preserving
 * surgical edit. Refuses foreign entries; replaces ours-same-source silently;
 * replaces ours-other-source only when `allowReplaceOtherSource` (callers
 * warn first). Validates the render before the atomic swap.
 */
export function writeOpencodeMcpEntry(
  configPath: string,
  entry: OpencodeMcpEntry,
  opts: { expect?: OpencodeEntryExpectation; allowReplaceOtherSource?: boolean } = {},
): WriteOpencodeEntryResult {
  assertEntryName(entry.name);
  if (entry.kind === 'remote' && entry.tokenMode === 'inline' && !entry.bearerToken) {
    throw new Error('inline token mode requires a bearerToken');
  }
  const notes: string[] = [];
  const snippet = opencodeEntrySnippet(entry);

  const { text, existed } = readConfigRaw(configPath);
  const parsed = parseOpencodeConfig(text, configPath, snippet);

  const priorKind = opencodeEntryKind(parsed, entry.name, opts.expect);
  if (priorKind === 'foreign') {
    throw new Error(
      `mcp.${entry.name} in ${configPath} is not a gbrain-managed entry — refusing to overwrite it. ` +
        `Remove it (or pick another --name) and re-run.`,
    );
  }
  if (priorKind === 'ours-other-source' && !opts.allowReplaceOtherSource) {
    // Caller-appropriate refusal text: on the REMOTE path (expect.url — the
    // harness/connect lanes) no GBRAIN_SOURCE is involved, and connect's
    // documented escape hatch is --force; the GBRAIN_SOURCE wording belongs
    // to the local/workspace lane only.
    throw new Error(
      opts.expect?.url !== undefined
        ? `mcp.${entry.name} in ${configPath} is a gbrain registration that does not match this endpoint ` +
            `(${opts.expect.url}) — another install or lane owns it; pass --force to replace it, or pick another --name.`
        : `mcp.${entry.name} in ${configPath} belongs to a DIFFERENT gbrain workspace ` +
            `(GBRAIN_SOURCE mismatch) — re-run with the overwrite confirmation to reroute it, or pick another --name.`,
    );
  }
  if (priorKind === 'ours-other-source') {
    notes.push(
      opts.expect?.url !== undefined
        ? `replaced a gbrain registration that did not match this endpoint (url/lane mismatch).`
        : `replaced a gbrain registration that pointed at a different workspace (source mismatch).`,
    );
  }

  const baseText = text.trim() === '' ? '{\n  "$schema": "https://opencode.ai/config.json"\n}\n' : text;
  const edits = modify(baseText, ['mcp', entry.name], entryValue(entry), FORMATTING);
  const nextText = applyEdits(baseText, edits);

  // Post-render validation: parse + deep-assert our entry + assert every
  // OTHER top-level key survives. Any failure leaves the original untouched.
  const rendered = parseOpencodeConfig(nextText, configPath, snippet);
  const renderedMcp = rendered.mcp as Record<string, unknown> | undefined;
  const ours = renderedMcp?.[entry.name];
  if (JSON.stringify(ours) !== JSON.stringify(entryValue(entry))) {
    throw new Error(
      `post-render validation failed: mcp.${entry.name} did not round-trip — original file left untouched.`,
    );
  }
  for (const key of Object.keys(parsed)) {
    if (key === 'mcp') continue;
    if (JSON.stringify(rendered[key]) !== JSON.stringify(parsed[key])) {
      throw new Error(
        `post-render validation failed: top-level key "${key}" changed — original file left untouched.`,
      );
    }
  }
  if (typeof parsed.mcp === 'object' && parsed.mcp !== null) {
    for (const key of Object.keys(parsed.mcp as Record<string, unknown>)) {
      if (key === entry.name) continue;
      const before = (parsed.mcp as Record<string, unknown>)[key];
      const after = renderedMcp?.[key];
      if (JSON.stringify(after) !== JSON.stringify(before)) {
        throw new Error(
          `post-render validation failed: mcp.${key} (not ours) changed — original file left untouched.`,
        );
      }
    }
  }

  const secret = entryCarriesSecret(entry);
  let backupPath: string | null = null;
  if (existed) {
    backupPath = createUniqueBackup(configPath, text);
    if (secret) chmodSync(backupPath, 0o600); // re-runs: the backup carries the previous token
  }
  atomicWriteTextFile(configPath, nextText, secret ? { forceMode: 0o600 } : { freshMode: 0o644 });
  if (secret && existed) {
    notes.push(`${configPath} tightened to 0600 — it now carries a bearer token.`);
  }

  return {
    configPath,
    replacedPrior: priorKind !== 'absent',
    priorKind,
    backupPath,
    writtenText: nextText,
    notes,
  };
}

// ── Remove ──────────────────────────────────────────────────────────────────

/**
 * Remove the managed entry (fingerprint-keyed; everything else survives
 * byte-for-byte). Absent file / absent entry are calm no-ops. Foreign
 * entries refuse — removal never deletes what gbrain does not own.
 * `skipOtherSource` turns an `ours-other-source` match into a calm skip-with-
 * note instead of a removal (the uninstall sweep passes it: a gbrain entry
 * from a DIFFERENT workspace is not this uninstall's to delete).
 */
export function removeOpencodeMcpEntry(
  configPath: string,
  name: string,
  expect: OpencodeEntryExpectation = {},
  opts: { skipOtherSource?: boolean } = {},
): RemoveOpencodeEntryResult {
  assertEntryName(name);
  const notes: string[] = [];
  if (!existsSync(configPath)) {
    return { configPath, removed: false, backupPath: null, notes: ['no opencode config — nothing to remove'] };
  }
  const { text } = readConfigRaw(configPath);
  const parsed = parseOpencodeConfig(text, configPath);

  const kind = opencodeEntryKind(parsed, name, expect);
  if (kind === 'absent') {
    return { configPath, removed: false, backupPath: null, notes: ['no gbrain-managed entry — nothing to remove'] };
  }
  if (kind === 'foreign') {
    throw new Error(
      `mcp.${name} in ${configPath} is not a gbrain-managed entry — refusing to remove it.`,
    );
  }
  if (kind === 'ours-other-source' && opts.skipOtherSource) {
    return {
      configPath,
      removed: false,
      backupPath: null,
      notes: [
        `mcp.${name} in ${configPath} belongs to a DIFFERENT gbrain workspace (source mismatch) — left in place.`,
      ],
    };
  }
  if (kind === 'ours-other-source') {
    notes.push('removed a gbrain registration that pointed at a different workspace (source mismatch).');
  }

  const edits = modify(text, ['mcp', name], undefined, FORMATTING);
  const nextText = applyEdits(text, edits);
  parseOpencodeConfig(nextText, configPath); // never leave opencode unreadable

  // Unique backup, 0600 when the copied content carries an inline bearer —
  // the removed entry may BE the token-bearing one, and a fixed-name copy
  // onto a pre-existing loose-mode backup would keep the loose mode.
  const backupPath = createUniqueBackup(configPath, text);
  atomicWriteTextFile(configPath, nextText);
  return { configPath, removed: true, backupPath, notes };
}

// ── Sibling-global reconcile (the two-filename merge blind spot) ────────────

/**
 * opencode merges the user-global `opencode.json` AND `opencode.jsonc` when
 * both exist. Before writing `mcp.<name>` into one of them, reconcile the
 * SIBLING file: an ours-classified entry there is removed (one owner per
 * name — left in place it survives as a shadow registration whose merge
 * winner is ambiguous, and a later removal of the primary "reveals" it); a
 * FOREIGN entry refuses loudly naming BOTH files (same refusal posture as
 * the primary-file foreign case — the merge winner is not ours to fight
 * over). No-op when the path is not a global-pair member or the sibling is
 * absent/entry-less. Callers hold the opencode config-dir bootstrap lock
 * (both files share the dir — one lock covers both) and call this ONLY for
 * user-global writes (project-scope sibling semantics are unobserved).
 */
export function reconcileOpencodeSiblingGlobal(
  configPath: string,
  name: string,
  expect: OpencodeEntryExpectation = {},
): { siblingPath: string | null; removed: boolean; notes: string[] } {
  const siblingPath = opencodeGlobalSiblingPath(configPath);
  if (!siblingPath || !existsSync(siblingPath)) return { siblingPath, removed: false, notes: [] };
  const { text } = readConfigRaw(siblingPath);
  const parsed = parseOpencodeConfig(text, siblingPath);
  const kind = opencodeEntryKind(parsed, name, expect);
  if (kind === 'absent') return { siblingPath, removed: false, notes: [] };
  if (kind === 'foreign') {
    throw new Error(
      `mcp.${name} in ${siblingPath} is not a gbrain-managed entry — opencode merges ${siblingPath} AND ` +
        `${configPath} when both exist, so writing mcp.${name} into ${configPath} would fight it with an ` +
        `ambiguous merge winner. Remove it (or pick another --name) and re-run.`,
    );
  }
  const r = removeOpencodeMcpEntry(siblingPath, name, expect);
  const notes = [
    `removed the gbrain mcp.${name} entry from ${siblingPath} — opencode merges both global filenames, and the ` +
      `registration being written lands in ${configPath} (one owner per name).`,
    ...r.notes,
  ];
  return { siblingPath, removed: r.removed, notes };
}

/**
 * True when `mcp.<name>` exists as a REMOTE-type entry (regardless of
 * ownership). The workspace stdio lane consults this before writing a local
 * entry into the user-global config: a remote entry under our name is either
 * the harness lane's (bootstrap harness) or foreign — either way the stdio
 * lane must not fight it (the codexBlockOwnsName analog, #4043 ownership
 * rule). Best-effort: unreadable/unparseable configs return false (the write
 * path re-checks with full refusal semantics).
 */
export function opencodeRemoteEntryExists(configPath: string, name: string): boolean {
  try {
    const { text, existed } = readConfigRaw(configPath);
    if (!existed) return false;
    const parsed = parseOpencodeConfig(text, configPath);
    const mcp = parsed.mcp;
    if (typeof mcp !== 'object' || mcp === null) return false;
    const entry = (mcp as Record<string, unknown>)[name];
    return typeof entry === 'object' && entry !== null && (entry as Record<string, unknown>).type === 'remote';
  } catch {
    return false;
  }
}

// ── Status/recovery helpers ─────────────────────────────────────────────────

/**
 * Recover the inline bearer from OUR remote entry (harness `--status` token
 * liveness — the receipt never stores the token). Returns null when the file
 * or entry is absent, foreign, env-mode, or unreadable as JSONC.
 */
export function parseOpencodeEntryBearer(configPath: string, name: string, expectUrl?: string): string | null {
  try {
    const { text, existed } = readConfigRaw(configPath);
    if (!existed) return null;
    const parsed = parseOpencodeConfig(text, configPath);
    const kind = opencodeEntryKind(parsed, name, { url: expectUrl });
    if (kind !== 'ours-same-source') return null;
    const entry = (parsed.mcp as Record<string, unknown>)[name] as Record<string, unknown>;
    if (entry.type !== 'remote') return null;
    const auth = (entry.headers as Record<string, unknown> | undefined)?.Authorization;
    if (typeof auth !== 'string' || !auth.startsWith('Bearer ')) return null;
    const token = auth.slice('Bearer '.length);
    if (token.includes('{env:')) return null; // env-interpolated — no inline token to recover
    return token || null;
  } catch {
    return null;
  }
}