Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
30.6 KB
Raw Blame
/**
 * Codex wiring for `gbrain setup codex`: the stdio MCP table
 * `[mcp_servers.<name>]` in `$CODEX_HOME/config.toml`, setup's hook groups in
 * `$CODEX_HOME/hooks.json` (SessionStart + UserPromptSubmit read context;
 * SessionEnd capture only when accepted) and, for each group, the
 * `[hooks.state."<hooks.json>:<event>:<index>:0"]` trust table Codex requires
 * before it runs a user hook (without it the hook is listed and silently
 * skipped).
 *
 * Ownership is a hash: every owned entry (the MCP table, each hooks.json
 * group, each trust table) is fingerprinted with `ownedEntryFingerprint`
 * (sha256 over canonical JSON of the exact parsed entry) and recorded per
 * entry in the connection receipt `.gbrain-connection-codex-<name>.json`
 * beside config.toml (the name `gbrain connect --install` uses; a receipt
 * carrying `client_id` is a hosted one and is never adopted). Setup replaces
 * or removes an entry only when its current fingerprint is one the receipt
 * recorded (compare-and-swap); an edited entry is preserved and reported.
 * Receipt schema: `setup_receipt_version: 2` = the claude-code receipt's
 * fields plus `hooks_path`, `gbrain_home_env` and the per-event `trust` map.
 *
 * Write order, each step idempotent and resumable from the receipt:
 *   1. receipt `prepared`: the consent record (three decisions) and the
 *      pending MCP and hook fingerprints, before anything else is written;
 *   2. the MCP table, then the receipt records its fingerprint;
 *   3. the hooks.json groups (inert until trusted), then the receipt records
 *      their fingerprints and the pending trust fingerprints;
 *   4. the config.toml trust tables (activation, last), stale owned trust
 *      tables removed first; then the receipt records them;
 *   5. receipt `installed`.
 * `--remove` runs the reverse: trust, hooks, MCP, receipt. A crash anywhere
 * leaves pending fingerprints the next run treats as owned, so a resume never
 * duplicates an entry, and an untrusted hook never runs.
 */
import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { atomicWriteTextFile } from '../bootstrap/atomic-write.ts';
import { ownedEntryFingerprint } from '../bootstrap/adopted-connections.ts';
import { acquireBootstrapLock } from '../bootstrap/lock.ts';
import { codexConfigPath } from '../bootstrap/host-specs.ts';
import { appendCodexTomlTable, readCodexTomlTable, removeCodexTomlTable, type CodexTomlValue } from '../bootstrap/codex-toml.ts';
import {
  CODEX_SETUP_EVENTS,
  CODEX_SETUP_LANE_TOKEN,
  codexHookCensus,
  codexSetupHookGroup,
  codexSetupTrustEntry,
  writeCodexSetupHooks,
  type CodexHookGroup,
  type CodexSetupEvent,
} from '../bootstrap/codex-hooks.ts';
import { stdioServeArgv } from '../mcp-registration.ts';
import { withStdioMember } from '../stdio-member-flag.ts';
import type { McpSurface } from '../../mcp/surface.ts';
import { SetupAbortInjected, type SetupConsent, type SetupStep } from './claude-code.ts';
import { ensureHookLauncher, hookLauncherPath } from './hook-launcher.ts';

export const CODEX_SETUP_RECEIPT_VERSION = 2;

type Hashes = Partial<Record<CodexSetupEvent, string>>;
interface TrustRecord { key: string; hash: string }
type TrustRecords = Partial<Record<CodexSetupEvent, TrustRecord>>;

export interface CodexSetupReceipt {
  harness: 'codex';
  connection: 'local-stdio';
  setup_receipt_version: typeof CODEX_SETUP_RECEIPT_VERSION;
  status: 'prepared' | 'installed' | 'removed';
  name: string;
  gbrain_home: string;
  gbrain_home_env?: string;
  launcher: string;
  source_id: string | null;
  surface: McpSurface;
  /** The registration's `--advertise` (absent: tools/list shows the whole surface). */
  advertise?: McpSurface;
  config_path: string;
  hooks_path: string;
  entry_hash: string | null;
  pending_entry_hash: string | null;
  mcp_adopted?: boolean;
  mcp_plugin?: string;
  hooks: { owned: Hashes; pending: Hashes; edited: Hashes };
  trust: { owned: TrustRecords; pending: TrustRecords; edited: TrustRecords };
  consent: SetupConsent & { recorded_at: string };
  brain_created_by_setup: boolean;
  native_harness_verified: false;
  created_at: string;
  updated_at: string;
}

export interface CodexSetupPlan {
  name: string;
  launcher: string;
  brainHome: string;
  gbrainHomeEnv?: string;
  sourceId: string | null;
  surface: McpSurface;
  /** `serve --advertise`; null lists the whole surface. */
  advertise: McpSurface | null;
  events: CodexSetupEvent[];
  /** GST-363: `serve --stdio-member`: this entry's sessions read as that member. Only a named --stdio-member or the entry setup already wrote sets it. */
  stdioMember?: string;
}

export type CodexSetupStep = Omit<SetupStep, 'step'> & { step: SetupStep['step'] | 'trust' };
export interface CodexPreserved { kind: 'mcp' | 'hook' | 'trust'; event?: string; reason: 'edited' | 'adopted' | 'unlocatable' | 'conflict' }

export interface CodexInspection {
  configPath: string;
  hooksPath: string;
  receiptPath: string;
  prior: CodexSetupReceipt | null;
  hostedReceipt: { mcp_url?: string } | null;
  /** stdioMember: the --stdio-member of an entry setup owns (current or owned), which a rewrite carries forward. */
  mcp: { state: 'absent' | 'current' | 'owned' | 'remote' | 'unowned'; url?: string; stdioMember?: string };
  /** Events already wired by gbrain's bootstrap Codex lane (token-owned). */
  otherLaneEvents: string[];
  /** Owned events whose group the user edited: preserved, never rewritten. */
  edited: Hashes;
  hooksCurrent: boolean;
  trustCurrent: boolean;
}

export function codexSetupPaths(name: string): { configPath: string; hooksPath: string; receiptPath: string } {
  const configPath = codexConfigPath();
  return { configPath, hooksPath: join(dirname(configPath), 'hooks.json'), receiptPath: join(dirname(configPath), `.gbrain-connection-codex-${name}.json`) };
}

export function readCodexSetupReceipt(receiptPath: string): { setup: CodexSetupReceipt | null; hosted: { mcp_url?: string } | null } {
  if (!existsSync(receiptPath)) return { setup: null, hosted: null };
  let raw: Record<string, unknown>;
  try {
    raw = JSON.parse(readFileSync(receiptPath, 'utf8')) as Record<string, unknown>;
    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('not an object');
  } catch { throw new Error(`the connection receipt ${receiptPath} is unreadable; move it aside only if you know which install wrote it, then run setup again.`); }
  if (raw.client_id) return { setup: null, hosted: { mcp_url: typeof raw.mcp_url === 'string' ? raw.mcp_url : undefined } };
  if (raw.harness === 'codex' && raw.connection === 'local-stdio' && raw.setup_receipt_version === CODEX_SETUP_RECEIPT_VERSION) return { setup: raw as unknown as CodexSetupReceipt, hosted: null };
  throw new Error(`the connection receipt ${receiptPath} was not written by gbrain setup; it is left untouched. Choose another --name.`);
}

const writeReceipt = (path: string, receipt: CodexSetupReceipt) => atomicWriteTextFile(path, `${JSON.stringify(receipt, null, 2)}\n`, { forceMode: 0o600 });

/**
 * Provider key and endpoint names Codex forwards from its own environment to
 * serve. Codex starts stdio servers with a scrubbed environment, so a key the
 * user exported never reached serve and search stayed keyword-only. Names
 * only: Codex reads each value from its own environment at launch and skips
 * a name that is unset, so no value is ever written to config.toml. The
 * provider subset of the plugin lane's .codex-plugin/mcp.json env_vars
 * (test/setup-codex-env-vars.test.ts keeps them equal).
 */
export const CODEX_FORWARDED_PROVIDER_ENV: readonly string[] = [
  'ANTHROPIC_API_KEY', 'ANTHROPIC_BASE_URL', 'AZURE_OPENAI_API_KEY', 'DASHSCOPE_API_KEY', 'DEEPGRAM_API_KEY', 'DEEPSEEK_API_KEY',
  'GEMINI_API_KEY', 'GOOGLE_GENERATIVE_AI_API_KEY', 'GOOGLE_GENERATIVE_AI_BASE_URL', 'GROQ_API_KEY', 'JEV_TYPESAFE_API_KEY',
  'LITELLM_API_KEY', 'LITELLM_BASE_URL', 'LLAMA_SERVER_API_KEY', 'LLAMA_SERVER_BASE_URL', 'LLAMA_SERVER_RERANKER_API_KEY',
  'LLAMA_SERVER_RERANKER_BASE_URL', 'LMSTUDIO_API_KEY', 'LMSTUDIO_BASE_URL', 'MINIMAX_API_KEY', 'MISTRAL_API_KEY', 'MOONSHOT_API_KEY',
  'NAN_API_KEY', 'NVIDIA_API_KEY', 'OLLAMA_API_KEY', 'OLLAMA_BASE_URL', 'OPENAI_API_KEY', 'OPENAI_BASE_URL', 'OPENROUTER_API_KEY',
  'OPENROUTER_BASE_URL', 'PARTICLE_API_KEY', 'PERPLEXITY_API_KEY', 'PPLX_API_KEY', 'TOGETHER_API_KEY', 'TYPESAFE_API_KEY',
  'VOYAGE_API_KEY', 'ZHIPUAI_API_KEY',
];

export function desiredCodexMcpEntry(plan: Pick<CodexSetupPlan, 'launcher' | 'brainHome' | 'surface' | 'advertise' | 'gbrainHomeEnv' | 'sourceId' | 'stdioMember'>): Record<string, CodexTomlValue> {
  const env: Record<string, string> = {};
  if (plan.gbrainHomeEnv) env.GBRAIN_HOME = plan.gbrainHomeEnv;
  if (plan.sourceId) env.GBRAIN_SOURCE = plan.sourceId;
  // Codex starts stdio servers in the session's directory, so serve starts through the launcher too (#8426).
  return { command: hookLauncherPath(plan.brainHome), args: stdioServeArgv(plan.launcher, plan.surface, plan.advertise, plan.stdioMember), ...(Object.keys(env).length ? { env } : {}),
    env_vars: [...CODEX_FORWARDED_PROVIDER_ENV] };
}

function desiredGroups(plan: CodexSetupPlan): Partial<Record<CodexSetupEvent, CodexHookGroup>> {
  const env = { GBRAIN_HOME: plan.gbrainHomeEnv, GBRAIN_SOURCE: plan.sourceId ?? undefined };
  return Object.fromEntries(plan.events.map((e) => [e, codexSetupHookGroup(plan.launcher, e, env, 'setup', hookLauncherPath(plan.brainHome))]));
}

const hashes = (groups: Partial<Record<CodexSetupEvent, CodexHookGroup>>): Hashes =>
  Object.fromEntries(Object.entries(groups).map(([e, g]) => [e, ownedEntryFingerprint(g)]));
const values = (h: Hashes | undefined): string[] => Object.values(h ?? {}).filter((v): v is string => typeof v === 'string');
const trustPath = (key: string) => ['hooks', 'state', key];
const trustFingerprint = (key: string, table: unknown) => ownedEntryFingerprint({ key, table });
const consentValues = (c: SetupConsent): string => JSON.stringify([c.wiring_scope.value.hooks, c.capture.value, c.providers.value]);

/** A setup-lane group of THIS install (its launcher and GBRAIN_HOME pin), whatever its fingerprint. */
function isThisInstallsGroup(commands: string[], launcher: string, homeEnv: string | undefined): boolean {
  return commands.some((c) => c.includes(CODEX_SETUP_LANE_TOKEN) && c.includes(launcher)
    && (homeEnv ? c.includes(`GBRAIN_HOME=${homeEnv}`) : !c.includes('GBRAIN_HOME=')));
}

/** Desired trust records for the wanted groups at their current hooks.json indexes. */
function desiredTrust(hooksPath: string, groups: Partial<Record<CodexSetupEvent, CodexHookGroup>>, indexes: Partial<Record<CodexSetupEvent, number>>): Array<{ event: CodexSetupEvent; key: string; table: { trusted_hash: string }; hash: string }> {
  return (Object.keys(groups) as CodexSetupEvent[]).flatMap((event) => {
    const index = indexes[event];
    if (index === undefined) return [];
    const { key, trusted_hash } = codexSetupTrustEntry(hooksPath, event, index, groups[event]!);
    return [{ event, key, table: { trusted_hash }, hash: trustFingerprint(key, { trusted_hash }) }];
  });
}

/** Read-only: what setup would find and own. Throws on an unparseable config or hooks file. */
export function inspectCodexSetup(plan: CodexSetupPlan): CodexInspection {
  const paths = codexSetupPaths(plan.name);
  const { setup: prior, hosted } = readCodexSetupReceipt(paths.receiptPath);
  const entry = readCodexTomlTable(paths.configPath, ['mcp_servers', plan.name]);
  const desired = ownedEntryFingerprint(desiredCodexMcpEntry(plan));
  const entryFp = entry === undefined ? null : ownedEntryFingerprint(entry);
  const mcp: CodexInspection['mcp'] = entry === undefined ? { state: 'absent' }
    : entryFp === desired ? withStdioMember({ state: 'current' }, entry)
      : typeof (entry as Record<string, unknown>)?.url === 'string' ? { state: 'remote', url: (entry as Record<string, string>).url }
        : prior && [prior.entry_hash, prior.pending_entry_hash].includes(entryFp) ? withStdioMember({ state: 'owned' }, entry) : { state: 'unowned' };

  const census = codexHookCensus(paths.hooksPath);
  const groups = desiredGroups(plan);
  const want = hashes(groups);
  const owned = new Set([...values(prior?.hooks.owned), ...values(prior?.hooks.pending), ...values(want)]);
  const edited: Hashes = {};
  for (const event of CODEX_SETUP_EVENTS) {
    const present = census.filter((g) => g.event === event);
    const priorEdit = prior?.hooks.edited[event];
    const recorded = prior?.hooks.owned[event];
    if (priorEdit && present.some((g) => g.hash === priorEdit)) { edited[event] = priorEdit; continue; }
    const candidate = recorded && !present.some((g) => g.hash === recorded)
      ? present.find((g) => !owned.has(g.hash) && isThisInstallsGroup(g.commands, plan.launcher, plan.gbrainHomeEnv)) : undefined;
    if (candidate) edited[event] = candidate.hash;
  }
  let hooksCurrent = true;
  const indexes: Partial<Record<CodexSetupEvent, number>> = {};
  for (const g of census) {
    const target = want[g.event as CodexSetupEvent];
    if (owned.has(g.hash) && g.hash !== target) hooksCurrent = false;
    if (target && g.hash === target) {
      if (indexes[g.event as CodexSetupEvent] !== undefined) hooksCurrent = false;
      indexes[g.event as CodexSetupEvent] = g.index;
    }
  }
  for (const event of plan.events) if (!edited[event] && indexes[event] === undefined) hooksCurrent = false;

  let trustCurrent = hooksCurrent;
  if (trustCurrent) {
    const wanted = desiredTrust(paths.hooksPath, Object.fromEntries(Object.entries(groups).filter(([e]) => !edited[e as CodexSetupEvent])), indexes);
    for (const t of wanted) if (trustFingerprint(t.key, readCodexTomlTable(paths.configPath, trustPath(t.key))) !== t.hash) trustCurrent = false;
    for (const rec of [...Object.values(prior?.trust.owned ?? {}), ...Object.values(prior?.trust.pending ?? {})]) {
      if (!rec || wanted.some((t) => t.key === rec.key && t.hash === rec.hash)) continue;
      if (trustFingerprint(rec.key, readCodexTomlTable(paths.configPath, trustPath(rec.key))) === rec.hash) trustCurrent = false;
    }
  }
  const otherLaneEvents = [...new Set(census.filter((g) => g.lane === 'bootstrap').map((g) => g.event))];
  return { ...paths, prior, hostedReceipt: hosted, mcp, otherLaneEvents, edited, hooksCurrent, trustCurrent };
}

export interface CodexApplyResult { steps: CodexSetupStep[]; receipt: CodexSetupReceipt; changed: boolean; preserved: CodexPreserved[]; notes: string[] }

/**
 * Apply the plan under the Codex config-dir lock, in the write order above.
 * `pluginOwner` skips the MCP table (the gbrain Codex plugin serves the name);
 * `beforeMcp` runs after the receipt is prepared (the brain init step);
 * `abortAfter` is the crash-injection test seam.
 */
/** The current text of each file setup may rewrite, read before it writes; absent files have nothing to back up. */
function readOriginals(paths: string[]): Array<{ path: string; text: string }> {
  return paths.filter((path) => existsSync(path)).map((path) => ({ path, text: readFileSync(path, 'utf8') }));
}

/** Keep `<file>.bak.<stamp>` of each file setup changed (the autopilot convention); one note per backup. */
function keepBackups(originals: Array<{ path: string; text: string }>): string[] {
  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
  return originals.filter(({ path, text }) => !existsSync(path) || readFileSync(path, 'utf8') !== text).map(({ path, text }) => {
    const bakPath = `${path}.bak.${stamp}`;
    writeFileSync(bakPath, text, { mode: 0o600 });
    return `${path} as it was before setup changed it: ${bakPath}`;
  });
}

export async function applyCodexSetup(
  plan: CodexSetupPlan,
  consent: SetupConsent,
  opts: { pluginOwner: string | null; brainCreated: boolean; beforeMcp?: () => Promise<void>; abortAfter?: string },
): Promise<CodexApplyResult> {
  const paths = codexSetupPaths(plan.name);
  mkdirSync(dirname(paths.configPath), { recursive: true, mode: 0o700 });
  const lock = await acquireBootstrapLock(dirname(paths.configPath));
  const originals = readOriginals([paths.configPath, paths.hooksPath]);
  try {
    // The MCP table and every hook command start gbrain through the launcher, so it goes down before anything names it (#8424, #8426).
    ensureHookLauncher(hookLauncherPath(plan.brainHome));
    const found = inspectCodexSetup(plan);
    const prior = found.prior;
    const now = new Date().toISOString();
    const desired = desiredCodexMcpEntry(plan);
    const desiredHash = ownedEntryFingerprint(desired);
    const groups = desiredGroups(plan);
    const writeGroups = Object.fromEntries(Object.entries(groups).filter(([e]) => !found.edited[e as CodexSetupEvent])) as Partial<Record<CodexSetupEvent, CodexHookGroup>>;
    const want = hashes(writeGroups);
    const steps: CodexSetupStep[] = [];
    const preserved: CodexPreserved[] = Object.keys(found.edited).map((event) => ({ kind: 'hook', event, reason: 'edited' }));
    const notes: string[] = [];
    const mcpDone = opts.pluginOwner !== null || found.mcp.state === 'current';
    const consentSame = prior?.consent !== undefined && consentValues(prior.consent) === consentValues(consent);
    if (prior?.status === 'installed' && consentSame && mcpDone && found.hooksCurrent && found.trustCurrent && !opts.brainCreated) {
      steps.push({ step: 'receipt', action: 'keep', detail: `${paths.receiptPath} already records this install` });
      steps.push({ step: 'mcp', action: opts.pluginOwner ? 'skip' : 'keep', detail: opts.pluginOwner ? `the '${opts.pluginOwner}' plugin serves '${plan.name}'` : `[mcp_servers.${plan.name}] in ${paths.configPath} is current` });
      steps.push({ step: 'hooks', action: 'keep', detail: plan.events.length ? `${plan.events.join(', ')} in ${paths.hooksPath} are current` : 'no hooks wanted' });
      steps.push({ step: 'trust', action: 'keep', detail: plan.events.length ? `trust entries in ${paths.configPath} are current` : 'no trust entries wanted' });
      for (const p of preserved) steps.push({ step: 'hooks', action: 'preserve', detail: `${p.event} in ${paths.hooksPath} was edited after setup wrote it; kept as is` });
      return { steps, receipt: prior, changed: false, preserved, notes };
    }

    const receipt: CodexSetupReceipt = {
      harness: 'codex', connection: 'local-stdio', setup_receipt_version: CODEX_SETUP_RECEIPT_VERSION, status: 'prepared',
      name: plan.name, gbrain_home: plan.brainHome, ...(plan.gbrainHomeEnv ? { gbrain_home_env: plan.gbrainHomeEnv } : {}),
      launcher: plan.launcher, source_id: plan.sourceId, surface: plan.surface, ...(plan.advertise ? { advertise: plan.advertise } : {}),
      config_path: paths.configPath, hooks_path: paths.hooksPath,
      entry_hash: prior?.entry_hash ?? null, pending_entry_hash: opts.pluginOwner ? null : desiredHash,
      ...(prior?.mcp_adopted ? { mcp_adopted: true } : {}),
      ...(opts.pluginOwner ? { mcp_plugin: opts.pluginOwner } : {}),
      hooks: { owned: prior?.hooks.owned ?? {}, pending: want, edited: found.edited },
      trust: { owned: prior?.trust.owned ?? {}, pending: prior?.trust.pending ?? {}, edited: prior?.trust.edited ?? {} },
      consent: { ...consent, recorded_at: now },
      brain_created_by_setup: (prior?.brain_created_by_setup ?? false) || opts.brainCreated,
      native_harness_verified: false,
      created_at: prior?.created_at ?? now, updated_at: now,
    };
    const save = () => writeReceipt(paths.receiptPath, receipt);
    save();
    steps.push({ step: 'receipt', action: 'write', detail: `${paths.receiptPath} (prepared: consent and pending fingerprints recorded)` });
    if (opts.abortAfter === 'receipt') throw new SetupAbortInjected('receipt');
    await opts.beforeMcp?.();

    // 2. MCP table.
    if (opts.pluginOwner) {
      steps.push({ step: 'mcp', action: 'skip', detail: `the '${opts.pluginOwner}' plugin serves '${plan.name}'; no hand-wired table` });
    } else if (found.mcp.state === 'current') {
      if (!prior?.entry_hash && !prior?.pending_entry_hash) receipt.mcp_adopted = true;
      steps.push({ step: 'mcp', action: 'keep', detail: `[mcp_servers.${plan.name}] in ${paths.configPath} is current${receipt.mcp_adopted ? ' (adopted: it was already there, so --remove keeps it)' : ''}` });
    } else {
      if (found.mcp.state === 'owned' && removeCodexTomlTable(paths.configPath, ['mcp_servers', plan.name]) === 'unlocatable') {
        throw new Error(`[mcp_servers.${plan.name}] in ${paths.configPath} is setup's but was re-rendered in a shape setup cannot rewrite safely; remove that table by hand, then run setup again.`);
      }
      appendCodexTomlTable(paths.configPath, ['mcp_servers', plan.name], desired, `gbrain setup (${plan.name}): owned by fingerprint; \`gbrain setup codex --remove\` deletes it while unchanged`);
      delete receipt.mcp_adopted;
      steps.push({ step: 'mcp', action: 'write', detail: `[mcp_servers.${plan.name}] in ${paths.configPath}` });
    }
    if (!opts.pluginOwner) receipt.entry_hash = desiredHash;
    receipt.pending_entry_hash = null;
    save();
    if (opts.abortAfter === 'mcp') throw new SetupAbortInjected('mcp');

    // 3. hooks.json groups (inert until trusted).
    const ownedHooks = new Set([...values(prior?.hooks.owned), ...values(prior?.hooks.pending), ...values(want)]);
    const w = writeCodexSetupHooks(paths.hooksPath, { want: writeGroups, owned: ownedHooks, preserve: new Set(Object.keys(found.edited)) });
    notes.push(...w.notes);
    const written = Object.keys(writeGroups);
    steps.push(w.changed
      ? { step: 'hooks', action: 'write', detail: written.length ? `${written.join(', ')} in ${paths.hooksPath}` : `removed setup's groups from ${paths.hooksPath}` }
      : { step: 'hooks', action: 'keep', detail: written.length ? `${written.join(', ')} in ${paths.hooksPath} are current` : 'no hooks wanted' });
    for (const event of Object.keys(found.edited)) steps.push({ step: 'hooks', action: 'preserve', detail: `${event} in ${paths.hooksPath} was edited after setup wrote it; kept as is (and left untrusted by setup)` });
    receipt.hooks.owned = want;
    receipt.hooks.pending = {};
    const wanted = desiredTrust(paths.hooksPath, writeGroups, w.indexes);
    receipt.trust.pending = Object.fromEntries(wanted.map((t) => [t.event, { key: t.key, hash: t.hash }]));
    save();
    if (opts.abortAfter === 'hooks') throw new SetupAbortInjected('hooks');

    // 4. Trust tables: drop stale owned ones (an index or command change), then add the wanted ones.
    const trustEdited: TrustRecords = { ...receipt.trust.edited };
    const ownedTrust = [...Object.entries(prior?.trust.owned ?? {}), ...Object.entries(prior?.trust.pending ?? {})] as Array<[CodexSetupEvent, TrustRecord]>;
    for (const [event, rec] of ownedTrust) {
      if (wanted.some((t) => t.key === rec.key && t.hash === rec.hash)) continue;
      const table = readCodexTomlTable(paths.configPath, trustPath(rec.key));
      if (table === undefined) continue;
      if (trustFingerprint(rec.key, table) !== rec.hash) {
        trustEdited[event] = { key: rec.key, hash: trustFingerprint(rec.key, table) };
        preserved.push({ kind: 'trust', event, reason: 'edited' });
        steps.push({ step: 'trust', action: 'preserve', detail: `[hooks.state."${rec.key}"] changed after setup wrote it; kept` });
        continue;
      }
      const r = removeCodexTomlTable(paths.configPath, trustPath(rec.key));
      if (r === 'unlocatable') {
        preserved.push({ kind: 'trust', event, reason: 'unlocatable' });
        steps.push({ step: 'trust', action: 'preserve', detail: `[hooks.state."${rec.key}"] could not be located as one table; kept` });
      } else steps.push({ step: 'trust', action: 'remove', detail: `stale [hooks.state."${rec.key}"] (setup's ${event} group moved or changed)` });
    }
    const trusted: TrustRecords = {};
    for (const t of wanted) {
      const table = readCodexTomlTable(paths.configPath, trustPath(t.key));
      if (table !== undefined && trustFingerprint(t.key, table) === t.hash) {
        trusted[t.event] = { key: t.key, hash: t.hash };
        steps.push({ step: 'trust', action: 'keep', detail: `${t.event} is trusted in ${paths.configPath}` });
      } else if (table !== undefined) {
        preserved.push({ kind: 'trust', event: t.event, reason: 'conflict' });
        steps.push({ step: 'trust', action: 'preserve', detail: `${paths.configPath} already has a different [hooks.state."${t.key}"]; kept, so codex will ask before running setup's ${t.event} hook` });
      } else {
        appendCodexTomlTable(paths.configPath, trustPath(t.key), t.table, `gbrain setup (${plan.name}): trusts setup's ${t.event} hook; owned by fingerprint`);
        trusted[t.event] = { key: t.key, hash: t.hash };
        steps.push({ step: 'trust', action: 'write', detail: `${t.event} trust entry in ${paths.configPath}` });
      }
    }
    if (wanted.length === 0 && !steps.some((s) => s.step === 'trust')) steps.push({ step: 'trust', action: 'keep', detail: 'no trust entries wanted' });
    receipt.trust = { owned: trusted, pending: {}, edited: trustEdited };
    save();
    if (opts.abortAfter === 'trust') throw new SetupAbortInjected('trust');
    receipt.status = 'installed';
    save();
    notes.push(...keepBackups(originals));
    return { steps, receipt, changed: true, preserved, notes };
  } catch (e) {
    keepBackups(originals);
    throw e;
  } finally {
    lock.release();
  }
}

export interface CodexRemoveResult { steps: CodexSetupStep[]; preserved: CodexPreserved[]; notes: string[]; receiptRemoved: boolean }

/** Remove exactly what the receipt owns by fingerprint (trust, hooks, MCP, receipt); edited entries survive and are reported. */
export async function removeCodexSetup(receipt: CodexSetupReceipt, receiptPath: string, opts: { dryRun: boolean }): Promise<CodexRemoveResult> {
  const lock = await acquireBootstrapLock(dirname(receipt.config_path));
  const originals = readOriginals([receipt.config_path, receipt.hooks_path]);
  try {
    const steps: CodexSetupStep[] = [];
    const preserved: CodexPreserved[] = [];
    const notes: string[] = [];
    const trustEdited: TrustRecords = {};
    for (const [event, rec] of [...Object.entries(receipt.trust.owned), ...Object.entries(receipt.trust.pending)] as Array<[CodexSetupEvent, TrustRecord]>) {
      const table = readCodexTomlTable(receipt.config_path, trustPath(rec.key));
      if (table === undefined) continue;
      if (trustFingerprint(rec.key, table) !== rec.hash) {
        trustEdited[event] = { key: rec.key, hash: trustFingerprint(rec.key, table) };
        preserved.push({ kind: 'trust', event, reason: 'edited' });
        steps.push({ step: 'trust', action: 'preserve', detail: `[hooks.state."${rec.key}"] changed after setup wrote it; kept` });
      } else if (removeCodexTomlTable(receipt.config_path, trustPath(rec.key), { dryRun: opts.dryRun }) === 'unlocatable') {
        preserved.push({ kind: 'trust', event, reason: 'unlocatable' });
        steps.push({ step: 'trust', action: 'preserve', detail: `[hooks.state."${rec.key}"] could not be located as one table; kept` });
      } else steps.push({ step: 'trust', action: 'remove', detail: `${event} trust entry from ${receipt.config_path}` });
    }

    const owned = new Set([...values(receipt.hooks.owned), ...values(receipt.hooks.pending)]);
    const census = codexHookCensus(receipt.hooks_path);
    const removedGroups = census.filter((g) => owned.has(g.hash));
    const w = writeCodexSetupHooks(receipt.hooks_path, { want: {}, owned, preserve: new Set(), dryRun: opts.dryRun });
    notes.push(...w.notes);
    steps.push(removedGroups.length
      ? { step: 'hooks', action: 'remove', detail: `${removedGroups.map((g) => g.event).join(', ')} from ${receipt.hooks_path}` }
      : { step: 'hooks', action: 'skip', detail: `no owned groups in ${receipt.hooks_path}` });
    const edited: Hashes = {};
    for (const event of CODEX_SETUP_EVENTS) {
      const recorded = receipt.hooks.owned[event] ?? receipt.hooks.pending[event];
      const present = census.filter((g) => g.event === event && !owned.has(g.hash));
      const hit = present.find((g) => g.hash === receipt.hooks.edited[event])
        ?? (recorded && !census.some((g) => g.hash === recorded) ? present.find((g) => isThisInstallsGroup(g.commands, receipt.launcher, receipt.gbrain_home_env)) : undefined);
      if (!hit) continue;
      edited[event] = hit.hash;
      preserved.push({ kind: 'hook', event, reason: 'edited' });
      steps.push({ step: 'hooks', action: 'preserve', detail: `${event} in ${receipt.hooks_path} was edited after setup wrote it; kept` });
    }

    const entry = readCodexTomlTable(receipt.config_path, ['mcp_servers', receipt.name]);
    const entryFp = entry === undefined ? null : ownedEntryFingerprint(entry);
    if (receipt.mcp_plugin) {
      steps.push({ step: 'mcp', action: 'skip', detail: `the '${receipt.mcp_plugin}' plugin serves '${receipt.name}'; setup wrote no table` });
    } else if (entry === undefined) {
      steps.push({ step: 'mcp', action: 'skip', detail: `no [mcp_servers.${receipt.name}] in ${receipt.config_path}` });
    } else if (receipt.mcp_adopted && entryFp === receipt.entry_hash) {
      preserved.push({ kind: 'mcp', reason: 'adopted' });
      steps.push({ step: 'mcp', action: 'preserve', detail: `[mcp_servers.${receipt.name}] existed before setup ran; kept` });
    } else if ([receipt.entry_hash, receipt.pending_entry_hash].includes(entryFp)) {
      if (removeCodexTomlTable(receipt.config_path, ['mcp_servers', receipt.name], { dryRun: opts.dryRun }) === 'unlocatable') {
        preserved.push({ kind: 'mcp', reason: 'unlocatable' });
        steps.push({ step: 'mcp', action: 'preserve', detail: `[mcp_servers.${receipt.name}] could not be located as one table; kept` });
      } else steps.push({ step: 'mcp', action: 'remove', detail: `[mcp_servers.${receipt.name}] from ${receipt.config_path}` });
    } else {
      preserved.push({ kind: 'mcp', reason: 'edited' });
      steps.push({ step: 'mcp', action: 'preserve', detail: `[mcp_servers.${receipt.name}] in ${receipt.config_path} changed after setup wrote it; kept` });
    }

    let receiptRemoved = false;
    if (!opts.dryRun) {
      if (preserved.some((p) => p.reason === 'edited')) {
        writeReceipt(receiptPath, { ...receipt, status: 'removed', entry_hash: null, pending_entry_hash: null,
          hooks: { owned: {}, pending: {}, edited }, trust: { owned: {}, pending: {}, edited: trustEdited }, updated_at: new Date().toISOString() });
        steps.push({ step: 'receipt', action: 'write', detail: `${receiptPath} (removed; remembers the edited entries so a later setup leaves them alone)` });
      } else {
        if (existsSync(receiptPath)) unlinkSync(receiptPath);
        receiptRemoved = true;
        steps.push({ step: 'receipt', action: 'remove', detail: receiptPath });
      }
    }
    notes.push(...keepBackups(originals));
    return { steps, preserved, notes, receiptRemoved };
  } catch (e) {
    keepBackups(originals);
    throw e;
  } finally {
    lock.release();
  }
}