Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
130 KB
Raw Blame
/**
 * harness.ts — `gbrain bootstrap harness` (#4043): default brain wiring for
 * agent-framework-driven coding (a downstream framework spawning Claude Code
 * `claude -p` / codex exec / opencode run on a box that already hosts a brain
 * + a running `gbrain serve --http`).
 *
 * What it wires, per harness:
 * - Claude Code: user-scope HTTP MCP registration (`claude mcp add --scope
 *   user -t http … -H "Authorization: Bearer …"`), `mcp__<name>` into
 *   user-scope permissions.allow (headless pre-approval), and the lifecycle
 *   hooks (user scope by default, or per --project dir) — NO agent.json
 *   required anywhere.
 * - Codex: one managed `[mcp_servers.<name>]` TOML block with the inline
 *   bearer token (codex-toml.ts — `codex mcp add` cannot express it).
 * - opencode: one managed `mcp.<name>` remote entry with the inline bearer
 *   header in the user-global JSONC config (opencode-json.ts —
 *   framework-spawned opencode inherits no shell env, so the `{env:…}`
 *   interpolation the connect lane uses would resolve empty here).
 *
 * Contracts folded from the CEO review + outside voice (letters reference the
 * plan file):
 * - [C7] Mint-first rotation: mint → wire → smoke → only then revoke the
 *   PREVIOUS receipt's token BY ID. A wiring failure leaves the old token
 *   fully working; revoke-by-name never happens.
 * - [F1] Write-ahead receipt: harness.json persists at mint time with every
 *   planned target `pending`, flipping per-target as wiring lands — a crash
 *   at any step leaves a receipt --remove can consume.
 * - [C8] Ownership: an existing registration pointing at a DIFFERENT url is
 *   another brain's wiring — refuse without --force; --remove verifies url
 *   match before removing and skips (with a note) otherwise.
 * - [C6] User-scope and --project hook wiring are mutually exclusive; the
 *   writers additionally refuse same-file different-marker double-wiring.
 * - [C5] Session-transcript capture is its own consent item; --no-capture
 *   wires the context events only (SessionStart/UserPromptSubmit/PreCompact).
 * - [F3] Non-loopback --url is refused unless --token supplies the remote
 *   credential (remote brains are `gbrain connect`'s charter).
 * - [F7] Version-skew honesty: a serve older than the CLI verifies scoped
 *   tokens through pre-scopes code (full access) until restarted — say so.
 * - [C9] --remove is engine-free-first: host removals always run; the token
 *   revoke defers with a typed message under a live PGLite serve.
 */

import { existsSync, mkdirSync, readFileSync, rmSync, statSync } from 'node:fs';
import { askHarnessConsent } from './harness-consent.ts';
import { CONFIRMATION_REQUIRED_EXIT_CODE, HARNESS_CLEANUP_PENDING_EXIT_CODE, HARNESS_PENDING_VERIFY_EXIT_CODE } from '../exit-codes.ts';
import { cleanupLines, cleanupOutcomeFields, convergeHarnessCleanup, credentialRevoked, defaultTokenStates, harnessCleanupReport, leaveRevokedEnrollment, type TokenStateLookup } from './harness-cleanup.ts';
import { finishPendingVerify, harnessOutcomeFields, harnessVerifyPending, pendingVerifyStatusLine } from './harness-pending-verify.ts';
import { dirname, join, resolve } from 'node:path';
import { randomUUID } from 'node:crypto';

import { VERSION } from '../../version.ts';
import { loadConfig, loadConfigFileOnly, toEngineConfig, type GBrainConfig } from '../config.ts';
import { PRIVATE_DEFAULT_REMOTE_CONSEQUENCE, resolveWritebackConfigFromFile } from '../facts/writeback-config.ts';
import {
  AMBIENT_WRITEBACK_BLOCK_BEGIN,
  ambientBlockPresent,
  installAmbientWritebackBlockAt,
  probeAmbientBlock,
  renderAmbientInstructionBlock,
  stripAmbientWritebackBlockAt,
} from './instructions-block.ts';
import { harnessTurnRuleHosts, removeHarnessBrainFirst, removeHarnessTurnHooks, turnRuleConsentLine, writeHarnessBrainFirst, writeHarnessTurnHooks } from './harness-brain-first.ts';
import { removeHarnessSkillsIndex, writeHarnessSkillsIndex } from './harness-skills-index.ts';
import { isSkillLoading, skillsOutcomeFailed, type SkillLoading } from '../setup/skills-block.ts';
import { createEngine } from '../engine-factory.ts';
import { isValidSourceId } from '../source-id.ts';
import { ALL_SOURCES, isResolverUserError, localFederatedSourceIds, resolveSourceWithTier } from '../source-resolver.ts';
import { probeBrainIdentity, type ConnectProbeResult } from '../connect-probe.ts';
import {
  buildClaudeMcpAddArgv,
  isLoopbackHostname,
  isValidName,
  normalizeMcpUrl,
  redactToken,
  validateToken,
} from '../mcp-registration.ts';
import { carryLegacyGrant, mintLegacyToken, readActiveTokenPermissions, readActiveTokenPrivatePages, revokeLegacyTokenById, uncarriedPrivatePagesNote, type MintedLegacyToken } from '../token-mint.ts';
import { generateToken } from '../utils.ts';
import { readCredentials, writeCredentials, type HarnessCredentials } from '../harness/credentials.ts';
import { installSharedSkillsConnection, type SharedSkillsConnectionOptions } from '../harness/shared-skills.ts';
import { brainSupersededEnrollments, localEnrollment, SKILLS_REFRESH_COMMAND } from './harness-skills.ts';
import { nativeSharedSkillsDirectory } from '../harness/native-router.ts';
import { sqlQueryForEngine } from '../sql-query.ts';
import { BootstrapError, acquireBootstrapLock } from './lock.ts';
import { probeLivePgliteHolder } from './uninstall.ts';
import type { ExecRunner } from './repo.ts';
import {
  deleteHarnessReceipt,
  guardHarnessReceiptOverwrite,
  harnessReceiptPath,
  readHarnessReceiptState,
  writeHarnessReceipt,
  type HarnessReceipt,
  type HarnessTarget,
} from './format.ts';
import { atomicWriteTextFile } from './atomic-write.ts';
import { removeCodexHooks, writeCodexHooks } from './codex-hooks.ts';
import { ensureHookLauncher, hookLauncherPath } from '../setup/hook-launcher.ts';
import {
  removeCodexHttpServerBlock,
  writeCodexHttpServerBlock,
} from './codex-toml.ts';
import {
  addPermissionsAllowEntry,
  claudeSettingsPath,
  committedHookEvents,
  harnessHookIdentity,
  parseSeatFlags,
  removeClaudeHooksAt,
  removePermissionsAllowEntry,
  writeClaudeHooksAt,
  type ClaudeHookEnv,
} from './hooks.ts';
import { codexPluginProvidesName } from './plugin-lanes.ts';
import { harnessHookCarrierStatus, harnessHooksPresent, previewHarnessRemoval, removeHarnessHooksTarget } from './harness-hooks.ts';
import {
  CLAUDE_HOOK_EVENTS,
  CODEX_TOML_BLOCK_BEGIN,
  CODEX_TOML_BLOCK_END,
  GBRAIN_HARNESS_MARKER_VALUE,
  claudeUserMemoryPath,
  claudeUserSettingsPath,
  codexAgentsOverridePath,
  codexConfigPath,
  codexGlobalAgentsPath,
  mcpPermissionEntry,
  opencodeConfigDir,
  opencodeGlobalConfigPath,
  type ClaudeHookEvent,
  claudeConfigDir,
} from './host-specs.ts';
import {
  opencodeEntryKind,
  parseOpencodeConfig,
  parseOpencodeEntryBearer,
  reconcileOpencodeSiblingGlobal,
  removeOpencodeMcpEntry,
  writeOpencodeMcpEntry,
} from './opencode-json.ts';
import { isServeOlderThanScopes, probeServeHealth } from './serve-health.ts';

// Peeled façade seam (cathedral-6): the serve probe + scopes version floor
// moved to serve-health.ts; re-exported so this module's public surface — and
// every import site — is unchanged.
export {
  SCOPES_MIN_SERVE_VERSION,
  isServeOlderThanScopes,
  probeServeHealth,
  type ServeHealth,
} from './serve-health.ts';

// ── Flags ───────────────────────────────────────────────────────────────────

export type HarnessSelector = 'claude-code' | 'codex' | 'opencode' | 'all';

export interface HarnessFlags {
  harness: HarnessSelector;
  url?: string;
  port?: number;
  source?: string;
  tokenName: string;
  token?: string;
  name: string;
  projects: string[];
  noHooks: boolean;
  noCapture: boolean;
  /** `--no-instructions`: skip (and remove) the brain-first instruction block. */
  noInstructions?: boolean;
  /** `--skill-loading off|spring`: the spring-loaded skills index beside that block. */
  skillLoading?: SkillLoading;
  force: boolean;
  remove: boolean;
  /** `--remove --dry-run`: list what removal would do, write nothing. */
  dryRun?: boolean;
  status: boolean;
  refreshSkills: boolean;
  yes: boolean;
  json: boolean;
  gbrainBin?: string;
  skills?: 'follow' | 'memory-only';
  /** #4618 `--seat <label>` ('' = `--no-seat`); undefined keeps the installed seat. */
  seat?: string;
  /** The raw argv, for the approved command in a consent refusal (the token value is never repeated). */
  raw: string[];
  error?: string;
}

/** Pure flag parser (unit-tested). `--local` is a documented no-op alias. */
export function parseHarnessArgs(rest: string[]): HarnessFlags {
  const out: HarnessFlags = {
    harness: 'all',
    tokenName: 'bootstrap-harness',
    name: 'gbrain',
    projects: [],
    noHooks: false,
    noCapture: false,
    force: false,
    remove: false,
    status: false,
    refreshSkills: false,
    yes: false,
    json: false,
    raw: [...rest],
  };
  // [X14] Fail closed: an unattended setup command must never resolve a
  // malformed invocation by silent precedence. Missing values error.
  const value = (flag: string): string | undefined => {
    const i = rest.indexOf(flag);
    if (i < 0) return undefined;
    const v = rest[i + 1];
    if (v === undefined || v.startsWith('--')) {
      out.error = out.error ?? `${flag} requires a value`;
      return undefined;
    }
    return v;
  };
  const h = value('--harness');
  if (h !== undefined) {
    if (h !== 'claude-code' && h !== 'codex' && h !== 'opencode' && h !== 'all') {
      out.error = `unknown --harness '${h}' — pass claude-code, codex, opencode, or all`;
      return out;
    }
    out.harness = h;
  }
  const skills = value('--skills');
  if (skills !== undefined) {
    if (skills !== 'follow' && skills !== 'memory-only') {
      out.error = '--skills must be follow or memory-only';
      return out;
    }
    out.skills = skills;
  }
  const url = value('--url');
  if (url !== undefined) out.url = url;
  const port = value('--port');
  if (port !== undefined) {
    const n = Number(port);
    if (!Number.isInteger(n) || n <= 0 || n > 65535) {
      out.error = `invalid --port '${port}'`;
      return out;
    }
    out.port = n;
  }
  const source = value('--source');
  if (source !== undefined) {
    // Every other flag is validated here; a typo'd id would otherwise mint a
    // token and wire hooks to a phantom scope (reads return nothing).
    if (!isValidSourceId(source)) {
      out.error = `invalid --source '${source}' (a source id matches [a-z0-9-]{1,32}; '${ALL_SOURCES}' is not a hook scope)`;
      return out;
    }
    out.source = source;
  }
  out.tokenName = value('--token-name') ?? out.tokenName;
  const token = value('--token');
  if (token !== undefined) out.token = token;
  const name = value('--name');
  if (name !== undefined) {
    if (!isValidName(name)) {
      out.error = `invalid --name '${name}' (lowercase identifier)`;
      return out;
    }
    out.name = name;
  }
  for (let i = 0; i < rest.length; i++) {
    if (rest[i] !== '--project') continue;
    // [X14] A --project with a missing or flag-like value must fail loudly —
    // silently dropping it would widen hook wiring to USER scope.
    if (rest[i + 1] === undefined || rest[i + 1].startsWith('--')) {
      out.error = out.error ?? 'the project flag requires a directory value';
      return out;
    }
    out.projects.push(resolve(rest[i + 1]));
  }
  out.noHooks = rest.includes('--no-hooks');
  out.noCapture = rest.includes('--no-capture');
  out.noInstructions = rest.includes('--no-instructions');
  out.force = rest.includes('--force');
  out.remove = rest.includes('--remove');
  out.dryRun = rest.includes('--dry-run');
  out.status = rest.includes('--status');
  out.refreshSkills = rest.includes('--refresh-skills');
  out.yes = rest.includes('--yes');
  out.json = rest.includes('--json');
  const skillLoading = value('--skill-loading');
  if (skillLoading !== undefined) {
    if (isSkillLoading(skillLoading)) out.skillLoading = skillLoading;
    else out.error = out.error ?? `unknown --skill-loading '${skillLoading}'; pass off or spring`;
  }
  const bin = value('--gbrain-bin');
  if (bin !== undefined) out.gbrainBin = bin;
  const seat = parseSeatFlags(rest);
  if (seat.error) out.error = out.error ?? seat.error;
  if (seat.seat !== undefined) out.seat = seat.seat;
  // [X14] Conflicting invocations error instead of resolving by precedence.
  if (out.url !== undefined && out.port !== undefined) {
    out.error = out.error ?? 'pass --url OR --port, not both (the url wins would be a silent guess)';
  }
  if (out.status && out.remove) {
    out.error = out.error ?? 'pass --status OR --remove, not both';
  }
  if (out.refreshSkills && (out.status || out.remove)) out.error = out.error ?? 'pass --refresh-skills alone, not with --status or --remove';
  if (out.dryRun && !out.remove) out.error = out.error ?? '--dry-run previews --remove only: pass `--remove --dry-run`';
  // --user-hooks and --local are accepted, documented no-ops (script clarity).
  // Unknown/typo'd flags never reach this parser through the CLI: cli.ts
  // validates argv against CLI_FLAG_REGISTRY pre-dispatch and rejects them
  // (verified live with a misspelled no-capture flag — it errors before
  // runHarness runs; do NOT spell the typo literally here, the registry
  // generator harvests bare flag tokens from comments and would make it
  // valid). This parser's [X14] errors are the second layer, for the known
  // flags' VALUE shapes.
  return out;
}

// ── Deps (injectable for the serial suite) ──────────────────────────────────

export interface HarnessDeps {
  runner: ExecRunner;
  gbrainHome: string;
  isTTY?: boolean;
  prompt?: (q: string) => Promise<string>;
  fetchFn?: typeof fetch;
  probeIdentity?: (url: string, token: string) => Promise<ConnectProbeResult>;
  /** Resolved user-scope settings path (tests point at a temp HOME). */
  userSettingsPath?: string;
  /** Resolved codex config path (tests point at a temp CODEX_HOME). */
  codexConfig?: string;
  /** Resolved opencode config path (tests point at a temp XDG_CONFIG_HOME). */
  opencodeConfig?: string;
  /** Resolved Claude user memory file (~/.claude/CLAUDE.md) — the
   * ambient-writeback block target. Defaults to the sibling of an injected
   * userSettingsPath so a sandboxed test can never touch the real file. */
  claudeMemoryPath?: string;
  /** Resolved codex user-global AGENTS.md (same sandboxing rule, keyed off
   * an injected codexConfig). */
  codexAgentsPath?: string;
  /** Resolved codex AGENTS.override.md — the [OV-A4] exclusivity probe. */
  codexAgentsOverride?: string;
  /** Resolved opencode global AGENTS.md (the brain-first block target). */
  opencodeAgentsPath?: string;
  /** Engine-free file-plane config loader (ambient-writeback gate); tests
   * inject a fake. */
  loadFileConfig?: () => GBrainConfig | null;
  /** Engine-backed mint; tests inject a fake. */
  mint?: (opts: {
    name: string;
    scopes: string[];
    sourceGrant?: string[];
    allowedOperations?: string[];
    /** #5893: rotate from this token id, carrying its grants (carryLegacyGrant). */
    carry?: { fromId: string; explicitSource: boolean; policyAdded: string[] };
  }) => Promise<MintedLegacyToken>;
  installSharedSkills?: (credentials: HarnessCredentials, options: SharedSkillsConnectionOptions) => Promise<{
    status: string; reason?: string; retained_files?: string[]; next_action?: string; remote_membership_pending?: boolean;
  }>;
  nativeSkillsDir?: (host: HarnessTarget['host']) => string | undefined;
  revokeById?: (id: string) => Promise<boolean>;
  tokenStates?: TokenStateLookup; // #6743: read-only token-row states for the cleanup lane; tests inject a fake.
  /** #6798: read-only shared-skills enrollments the brain has superseded; throws when the brain cannot be opened. */
  supersededEnrollments?: typeof brainSupersededEnrollments;
  /** Resolve the source the hooks + token bind to, through the SAME resolver
   * the serve's resolve-IPC binding uses (resolveSourceWithTier: env →
   * dotfile → local_path → sources.default → sole non-default → seed
   * default), plus that source's local federated read set, so the hook lane
   * reads what search/think read (#4897). `explicit` = --source (validated +
   * asserted to exist). Throws on an unknown id or an unopenable engine — the
   * caller decides fail-open vs fail-closed. Tests inject a fake. */
  resolveHookSource?: (explicit: string | null) => Promise<HookSourceBinding>;
  /** Live-PGLite-serve pre-probe for the revoke lane [C9]. */
  pgliteLiveServe?: () => boolean;
  detectClaude?: () => boolean;
  detectCodex?: () => boolean;
  detectOpencode?: () => boolean;
  gbrainBin?: string | null;
  log?: (line: string) => void;
  logError?: (line: string) => void;
}

export function resolveHarnessDeps(deps: HarnessDeps): Required<Omit<HarnessDeps, 'gbrainBin'>> & { gbrainBin: string | null } {
  return {
    runner: deps.runner,
    gbrainHome: deps.gbrainHome,
    isTTY: deps.isTTY ?? process.stdout.isTTY === true,
    prompt: deps.prompt ?? (async () => 'n'),
    fetchFn: deps.fetchFn ?? fetch,
    probeIdentity: deps.probeIdentity ?? ((url, token) => probeBrainIdentity(url, token)),
    userSettingsPath: deps.userSettingsPath ?? claudeUserSettingsPath(),
    codexConfig: deps.codexConfig ?? codexConfigPath(),
    opencodeConfig: deps.opencodeConfig ?? opencodeGlobalConfigPath(),
    // Instruction-file targets derive from an INJECTED settings/config path's
    // directory when one is given: in production the derivation equals the
    // host-specs defaults (CLAUDE.md and AGENTS.md live beside settings.json
    // and config.toml), and in tests it keeps every write inside the temp
    // sandbox even when the test predates these fields.
    claudeMemoryPath:
      deps.claudeMemoryPath ??
      (deps.userSettingsPath ? join(dirname(deps.userSettingsPath), 'CLAUDE.md') : claudeUserMemoryPath()),
    codexAgentsPath:
      deps.codexAgentsPath ??
      (deps.codexConfig ? join(dirname(deps.codexConfig), 'AGENTS.md') : codexGlobalAgentsPath()),
    codexAgentsOverride:
      deps.codexAgentsOverride ??
      (deps.codexConfig ? join(dirname(deps.codexConfig), 'AGENTS.override.md') : codexAgentsOverridePath()),
    opencodeAgentsPath: deps.opencodeAgentsPath ?? join(dirname(deps.opencodeConfig ?? opencodeGlobalConfigPath()), 'AGENTS.md'),
    loadFileConfig: deps.loadFileConfig ?? loadConfigFileOnly,
    mint: deps.mint ?? mintHarnessToken,
    installSharedSkills: deps.installSharedSkills ?? installSharedSkillsConnection,
    nativeSkillsDir: deps.nativeSkillsDir ?? ((host) => {
      const config = host === 'claude-code' ? deps.userSettingsPath : host === 'codex' ? deps.codexConfig : deps.opencodeConfig;
      return config ? join(dirname(config), 'skills') : nativeSharedSkillsDirectory(host) ?? undefined;
    }),
    revokeById: deps.revokeById ?? defaultRevokeById,
    tokenStates: deps.tokenStates ?? defaultTokenStates,
    supersededEnrollments: deps.supersededEnrollments ?? brainSupersededEnrollments,
    resolveHookSource: deps.resolveHookSource ?? defaultResolveHookSource,
    pgliteLiveServe: deps.pgliteLiveServe ?? defaultPgliteLiveServe,
    // #4325: config-dir fallback mirrors detectCodex/detectOpencode below —
    // CI runners and alias-only shells don't expose a `claude` binary on the
    // probing process's PATH even when Claude Code is configured.
    detectClaude:
      deps.detectClaude ??
      (() => whichSafe('claude') !== null || existsSync(claudeConfigDir())),
    detectCodex:
      deps.detectCodex ??
      (() => whichSafe('codex') !== null || existsSync(deps.codexConfig ?? codexConfigPath())),
    detectOpencode:
      deps.detectOpencode ??
      (() => whichSafe('opencode') !== null || existsSync(opencodeConfigDir())),
    gbrainBin: deps.gbrainBin !== undefined ? deps.gbrainBin : null,
    log: deps.log ?? ((l) => console.log(l)),
    logError: deps.logError ?? ((l) => console.error(l)),
  };
}

function whichSafe(bin: string): string | null {
  try {
    // #4325: pass PATH explicitly — Bun.which's default lookup snapshots the
    // process-start PATH and ignores runtime process.env.PATH mutations, so
    // env-remapped test lanes (withEnv) could never sandbox detection.
    return process.env.PATH ? Bun.which(bin, { PATH: process.env.PATH }) : Bun.which(bin);
  } catch {
    return null;
  }
}

/** Optional overrides for the three harness-detection probes.
 *
 * Production leaves every field unset, so `resolveDeps` keeps its `Bun.which`
 * defaults. E2E tests MUST pin them: `Bun.which` resolves against the live
 * PATH and reads the real password-database HOME, so it ignores a test's
 * remapped HOME/PATH entirely. Without a pin, an otherwise hermetic test
 * silently asserts something different depending on which agent CLIs the host
 * happens to have installed — `claude` is on a developer laptop's PATH but
 * absent from a GitHub runner, so the claude lane never ran in CI, no
 * `claude mcp add` was exec'd, and no user-scope settings file was written.
 */
export interface HarnessDetectOverrides {
  claude?: () => boolean;
  codex?: () => boolean;
  opencode?: () => boolean;
}

/** Narrow the overrides to the HarnessDeps keys, omitting absent probes so
 * resolveDeps' production defaults stay in charge of anything not pinned. */
export function harnessDetectDeps(o?: HarnessDetectOverrides): Partial<HarnessDeps> {
  return {
    ...(o?.claude ? { detectClaude: o.claude } : {}),
    ...(o?.codex ? { detectCodex: o.codex } : {}),
    ...(o?.opencode ? { detectOpencode: o.opencode } : {}),
  };
}

/** Production mint: open the configured engine just long enough to insert. */
export async function mintHarnessToken(opts: Parameters<NonNullable<HarnessDeps['mint']>>[0]): Promise<MintedLegacyToken> {
  const cfg = loadConfig();
  if (!cfg) {
    throw new Error('no brain configured — run `gbrain init` first (the harness wires an EXISTING brain).');
  }
  const engineConfig = toEngineConfig(cfg);
  const engine = await createEngine(engineConfig);
  await engine.connect(engineConfig);
  try {
    let sourceGrant = opts.sourceGrant;
    if (!sourceGrant) {
      // [C2] Mirror the stdio lane's federation: no explicit --source →
      // reads span the federated=true sources, write floor 'default'.
      try {
        const { localFederatedSourceIds } = await import('../source-resolver.ts');
        sourceGrant = await localFederatedSourceIds(engine, 'default', 'seed_default');
      } catch {
        sourceGrant = undefined; // historical default floor
      }
    }
    const prior = opts.carry && await readActiveTokenPermissions(engine, opts.carry.fromId);
    const uncarried = opts.carry && prior !== undefined && await readActiveTokenPrivatePages(engine, opts.carry.fromId) === 'granted_sources' ? { uncarriedPrivatePages: 'granted_sources' as const } : {};
    if (prior !== undefined && opts.carry && opts.allowedOperations) {
      const carried = carryLegacyGrant(prior, { ...opts.carry, allowedOperations: opts.allowedOperations,
        ...(sourceGrant && sourceGrant.length > 0 ? { sourceGrant } : {}) });
      const minted = await mintLegacyToken(engine, { name: opts.name, scopes: opts.scopes, ...carried });
      return { ...minted, withheldOperations: carried.withheldOperations, ...uncarried };
    }
    return { ...await mintLegacyToken(engine, {
      name: opts.name,
      takesHolders: ['world'],
      scopes: opts.scopes,
      ...(opts.allowedOperations !== undefined ? { allowedOperations: opts.allowedOperations } : {}),
      ...(sourceGrant && sourceGrant.length > 0 ? { sourceGrant } : {}),
    }), ...uncarried };
  } finally {
    await engine.disconnect();
  }
}

/** The source the hooks + token bind to, and the read grant the token carries. */
export interface HookSourceBinding {
  source_id: string;
  /** The federated read set for an ambient tier (what search/think read);
   * `[source_id]` for an explicit --source or a non-federated source. */
  grant: string[];
}

/** Production hook-source lookup: the SAME resolver the serve's resolve-IPC
 * binding runs (`resolveSourceWithTier(engine, null)`), so the hooks claim
 * exactly the source the serve resolves; an explicit --source goes through
 * tier 1 (shape + existence). NOT fail-open: on a PGLite brain under a live
 * serve the engine cannot open, and applyHarness decides what that means
 * (refuse without --source; bind an explicit --source unverified). */
async function defaultResolveHookSource(explicit: string | null): Promise<HookSourceBinding> {
  const cfg = loadConfig();
  if (!cfg) throw new Error('no brain configured (run `gbrain init` first)');
  const engineConfig = toEngineConfig(cfg);
  const engine = await createEngine(engineConfig);
  await engine.connect(engineConfig);
  try {
    const resolved = await resolveSourceWithTier(engine, explicit);
    const grant = (await localFederatedSourceIds(engine, resolved.source_id, resolved.tier)) ?? [resolved.source_id];
    return { source_id: resolved.source_id, grant };
  } finally {
    await engine.disconnect();
  }
}

async function defaultRevokeById(id: string): Promise<boolean> {
  const cfg = loadConfig();
  if (!cfg) throw new Error('no brain configured');
  const engineConfig = toEngineConfig(cfg);
  const engine = await createEngine(engineConfig);
  await engine.connect(engineConfig);
  try {
    return await revokeLegacyTokenById(sqlQueryForEngine(engine), id);
  } finally {
    await engine.disconnect();
  }
}

/** A live PGLite serve holds the single-writer lock — engine opens will fail. */
function defaultPgliteLiveServe(): boolean {
  const cfg = loadConfig();
  if (!cfg?.database_path) return false;
  return probeLivePgliteHolder(cfg.database_path) !== null;
}

// ── Consent copy [C5 / #4029 register] ──────────────────────────────────────

export function buildConsentBlock(p: {
  tokenName: string;
  tokenSupplied: boolean;
  scopes: string[];
  url: string;
  wireClaude: boolean;
  wireCodex: boolean;
  wireOpencode: boolean;
  hooks: boolean;
  capture: boolean;
  codexCapture?: boolean; // Codex SessionEnd capture hook (hooks.json + its config.toml trust entry)
  hookScope: string;
  name: string;
  userSettingsPath: string;
  codexConfig: string;
  opencodeConfig: string;
  /** Instruction files receiving the ambient-writeback managed block (only
   * when memory.auto_writeback is enabled) — consent names every file the
   * apply will write [X7 parity]. */
  instructionsPaths?: string[];
  skills?: 'follow' | 'memory-only';
  /** Hosts that get only the per-turn brain-first rule hook (src/core/setup/turn-hook.ts). */
  turnRuleHosts?: string[];
}): string {
  const lines: string[] = [
    'gbrain bootstrap harness — wire framework-spawned coding sessions to this brain',
    '',
    'Will do, on this machine:',
  ];
  let n = 1;
  lines.push(
    p.tokenSupplied
      ? `  ${n++}. Use the supplied bearer token — written ${p.skills === 'follow' ? 'into' : 'ONLY into'} the host registrations below ` +
          `${p.skills === 'follow' ? 'and a private 0600 enrollment cleanup credential' : '(gbrain keeps no copy)'}. ` +
          `The remove flow does NOT revoke supplied tokens (they are not ours to revoke).`
      : `  ${n++}. Mint an independent bearer token per harness under '${p.tokenName}' (scopes: ${p.scopes.join('+')}; sees takes marked 'world'; ` +
          `reads span this brain's federated sources). Any prior harness token is revoked ` +
          `only after the new one is wired and verified.`,
  );
  if (p.skills) lines.push(p.skills === 'follow'
    ? `  ${n++}. Follow this brain's authorized shared-skills catalog using an owned native router and private installation receipts. No editor authority, automatic execution, extra capture, or identity changes. Restart sessions after updates; native activation remains unverified. Opt out with --skills memory-only.`
    : `  ${n++}. Shared skills: memory-only. Do not enroll or install a router; stop any prior owned enrollment without deleting edited files.`);
  if (p.wireClaude) {
    lines.push(
      `  ${n++}. Claude Code (user scope): register MCP server '${p.name}' -> ${p.url}, and ` +
        `pre-approve its tools for headless runs (permissions.allow entry 'mcp__${p.name}' in ${p.userSettingsPath}).`,
    );
    if (p.hooks) {
      lines.push(
        `  ${n++}. Wire the five lifecycle hooks (SessionStart/UserPromptSubmit/Stop/SessionEnd/PreCompact) in ${p.hookScope}.`,
      );
      lines.push(
        p.capture
          ? `  ${n++}. Session-transcript capture: every Claude Code session's transcript on this machine is ` +
              `secret-scanned and captured into the brain's corpus (Stop/SessionEnd hooks). Opt out of just ` +
              `this with the no-capture flag.`
          : `  ${n++}. Session-transcript capture: OFF (no-capture) — context injection only.`,
      );
    }
  }
  if (p.wireCodex) {
    lines.push(
      `  ${n++}. Codex (user-global): write [mcp_servers.${p.name}] with the bearer token INLINE into ` +
        `${p.codexConfig} (0600) — framework-spawned codex inherits no shell env, so an env-var token would not reach it.`,
    );
    if (p.codexCapture) lines.push(`  ${n++}. Codex session-transcript capture: a SessionEnd hook (hooks.json + its trust entry in ${p.codexConfig}) secret-scans and captures every Codex session's transcript into the brain's corpus. Opt out with the no-capture flag.`);
  }
  if (p.wireOpencode) {
    lines.push(
      `  ${n++}. opencode (user-global): write the mcp.${p.name} remote entry with the bearer token INLINE into ` +
        `${p.opencodeConfig} (0600) — framework-spawned opencode inherits no shell env, so the {env:…} ` +
        `interpolation would resolve empty.`,
    );
  }
  if (p.instructionsPaths && p.instructionsPaths.length > 0) {
    lines.push(
      `  ${n++}. Ambient memory writeback is ENABLED (memory.auto_writeback): install the managed ` +
        `instruction block (marker-delimited, credential-free) into ${p.instructionsPaths.join(' and ')} ` +
        `so every session saves durable user facts to this brain.`,
    );
  }
  // [X7] The reach statement matches what is ACTUALLY being wired — it must
  // never claim a host or a hook lane this invocation does not touch. Joined
  // list, not a ternary tree: a fourth harness must be a compile-time nudge
  // here, not a silent mislabel.
  const hostNames = [
    ...(p.wireClaude ? ['Claude Code'] : []),
    ...(p.wireCodex ? ['Codex'] : []),
    ...(p.wireOpencode ? ['opencode'] : []),
  ];
  const hosts = `EVERY ${hostNames.join(' and ')} session`;
  const turnRule = turnRuleConsentLine(p.turnRuleHosts);
  const hookLine = turnRule + (!(p.wireClaude && p.hooks)
    ? (p.codexCapture ? 'One hook is wired: Codex SessionEnd transcript capture.' : turnRule ? 'No other hooks are wired by this invocation.' : 'No hooks are wired by this invocation.')
    : p.capture
      ? 'Hooks run in every Claude Code session (context injection + transcript capture); auto-commit/push lanes stay inert outside gbrain agent workspaces.'
      : 'Hooks run in every Claude Code session (context injection only — capture is OFF); auto-commit/push lanes stay inert outside gbrain agent workspaces.');
  const offRamps = [
    'GBRAIN_HOOKS=0 (runtime)',
    '`gbrain bootstrap harness --remove`',
    '`gbrain auth revoke --id <id>` (see auth list)',
    ...(p.wireClaude ? [`\`claude mcp remove ${p.name} --scope user\``] : []),
    ...(p.wireCodex ? ['edit the codex config'] : []),
    ...(p.wireOpencode ? ['edit the opencode config'] : []),
  ];
  lines.push(
    '',
    `Reach, plainly: ${hosts} on this machine — any repo, any`,
    'framework-spawned agent — can read AND write this brain through these tools.',
    hookLine,
    `Off-ramps: ${offRamps.join(', ')}.`,
  );
  return lines.join('\n');
}

// ── Apply ───────────────────────────────────────────────────────────────────

interface ClaudeMcpGetInfo {
  found: boolean;
  url?: string;
}

/** Parse `claude mcp get <name>` output for the registered URL (redact-safe). */
export function parseClaudeMcpGetUrl(out: string): ClaudeMcpGetInfo {
  const m = out.match(/^\s*URL:\s*(\S+)\s*$/m);
  if (!m) return { found: /Scope:|Type:/.test(out) };
  return { found: true, url: m[1] };
}

/**
 * [X3] Unwire prior-receipt targets that the new plan does not re-plan.
 * Matching is by (host, kind, path/name identity); unmatched targets are
 * removed from the hosts now. A cleanup failure re-appends the target to the
 * NEW receipt as failed so --remove (or a re-run) retries it.
 */
async function cleanupStalePriorTargets(
  prior: HarnessReceipt,
  receipt: HarnessReceipt,
  d: ReturnType<typeof resolveHarnessDeps>,
  save: () => void,
): Promise<void> {
  const planned = receipt.targets;
  const matches = (pt: HarnessTarget): boolean =>
    planned.some((nt) => {
      if (nt.host !== pt.host || nt.kind !== pt.kind) return false;
      if (pt.kind === 'hooks') return nt.path === pt.path && nt.marker === pt.marker;
      if (pt.kind === 'permission') return nt.path === pt.path && nt.entry === pt.entry;
      if (pt.kind === 'instructions') return nt.path === pt.path;
      return (nt.name ?? 'gbrain') === (pt.name ?? 'gbrain');
    });
  for (const pt of prior.targets) {
    if (matches(pt)) continue;
    try {
      if (pt.kind === 'instructions') {
        // Ambient-writeback block no longer planned (host dropped or
        // writeback turned off) — strip it. Same [X11] nested-lock
        // discipline as the codex branch below (the caller holds the
        // claude/config dir lock).
        if (pt.path && existsSync(pt.path)) {
          const blockDir = dirname(pt.path);
          const heldDir = resolve(dirname(d.userSettingsPath));
          const lk = resolve(blockDir) === heldDir ? null : await acquireBootstrapLock(blockDir);
          let r: { removed: boolean };
          try {
            r = stripAmbientWritebackBlockAt(pt.path);
          } finally {
            lk?.release();
          }
          if (r.removed) d.log(`stale ambient-writeback block removed from ${pt.path} (no longer planned).`);
        }
      } else if (pt.host === 'claude-code' && pt.kind === 'hooks') {
        const r = removeClaudeHooksAt(pt.path ?? d.userSettingsPath, pt.marker ?? GBRAIN_HARNESS_MARKER_VALUE, {
          identity: harnessHookIdentity(prior, pt, { launcher: d.gbrainBin }),
        });
        if (r.notes.some((n) => n.startsWith('WARNING'))) throw new Error(r.notes.join('; '));
        if (r.removed > 0) d.log(`stale harness hooks unwired from ${r.settingsPath} (no longer planned).`);
      } else if (pt.host === 'claude-code' && pt.kind === 'permission') {
        if (pt.mechanism === 'pre-existing') continue; // never ours to remove [X8]
        const r = removePermissionsAllowEntry(pt.path!, pt.entry!);
        if (r.notes.some((n) => n.startsWith('WARNING'))) throw new Error(r.notes.join('; '));
        if ((r.removed ?? 0) > 0) d.log(`stale permissions.allow entry '${pt.entry}' removed (no longer planned).`);
      } else if (pt.host === 'claude-code' && pt.kind === 'mcp') {
        const get = await d.runner(['claude', 'mcp', 'get', pt.name ?? 'gbrain']);
        const info = parseClaudeMcpGetUrl(`${get.stdout}\n${get.stderr}`);
        if (get.code === 0 && info.found && info.url === prior.url) {
          const rm = await d.runner(['claude', 'mcp', 'remove', pt.name ?? 'gbrain', '--scope', pt.scope]);
          if (rm.code !== 0 && !/not found|No MCP server/i.test(rm.stdout + rm.stderr)) {
            // A failed remove must NOT be forgotten as success — re-append so
            // --remove / the next converge retries it (ship-review P2).
            throw new Error(rm.stderr.trim() || `claude mcp remove exited ${rm.code}`);
          }
          d.log(`stale MCP registration '${pt.name}' removed (no longer planned).`);
        } else if (get.code === 0 && info.found && !info.url) {
          // Refuse-rather-than-guess: an unparseable URL means we cannot prove
          // ownership — never remove a registration we can't verify is ours.
          d.log(
            `stale MCP registration '${pt.name}' left in place — could not verify its URL against the receipt; ` +
              `remove it manually if it is this brain's: claude mcp remove ${pt.name ?? 'gbrain'} --scope ${pt.scope}`,
          );
        }
      } else if (pt.host === 'codex' && pt.kind === 'mcp') {
        // [X11] The caller holds only the claude config-dir lock; the codex
        // config is a DIFFERENT shared file, and its read-modify-write must
        // serialize on ITS directory's bootstrap lock too — a concurrent
        // codex-dir-locked writer interleaving here would have one rename
        // discard the other. Ordering matches apply/remove (claude/config
        // dir first, then codex dir), so no lock-order inversion; the lock
        // is non-reentrant, so the same-dir case skips the nested acquire.
        const codexPath = pt.path ?? d.codexConfig;
        const codexDir = dirname(codexPath);
        mkdirSync(codexDir, { recursive: true });
        const heldDir = resolve(dirname(d.userSettingsPath));
        const lk = resolve(codexDir) === heldDir ? null : await acquireBootstrapLock(codexDir);
        let r: ReturnType<typeof removeCodexHttpServerBlock>;
        try {
          r = removeCodexHttpServerBlock(codexPath, pt.name ?? 'gbrain');
        } finally {
          lk?.release();
        }
        if (r.removed) d.log(`stale codex managed block removed from ${codexPath} (no longer planned).`);
      } else if (pt.host === 'opencode' && pt.kind === 'mcp') {
        // Fingerprint-keyed against the PRIOR receipt's url — a foreign or
        // rotated-away entry refuses inside the module (never guess). Same
        // [X11] nested-lock discipline as the codex branch above (claude/
        // config dir held by the caller, then the opencode dir here).
        const ocPath = pt.path ?? d.opencodeConfig;
        const ocDir = dirname(ocPath);
        mkdirSync(ocDir, { recursive: true });
        const heldDir = resolve(dirname(d.userSettingsPath));
        const lk = resolve(ocDir) === heldDir ? null : await acquireBootstrapLock(ocDir);
        let r: ReturnType<typeof removeOpencodeMcpEntry>;
        try {
          r = removeOpencodeMcpEntry(ocPath, pt.name ?? 'gbrain', { url: prior.url });
        } finally {
          lk?.release();
        }
        if (r.removed) d.log(`stale opencode entry removed from ${ocPath} (no longer planned).`);
      }
    } catch (e) {
      const msg = e instanceof Error ? e.message : String(e);
      receipt.targets.push({ ...pt, state: 'failed', error: `stale-cleanup: ${msg}` });
      save();
      d.logError(`could not unwire stale ${pt.host}/${pt.kind}: ${msg} (kept on the receipt for retry).`);
    }
  }
}

/** #6661 (D25): a live serve holds this PGLite brain (no mint) and a stopped one fails the health probe: pre-mint with the harness grant, then --token. */
async function liveServeRefusal(opts: { tokenName: string; follow: boolean; source?: string }): Promise<BootstrapError> {
  const scopes = opts.follow ? ['read', 'write', 'skills_member_self'] : ['read', 'write'];
  const operations = await harnessOperationSnapshot(opts.follow);
  const steps = ['stop the serve that holds this brain', `gbrain auth create ${opts.tokenName} --scopes ${scopes.join(',')}`,
    `gbrain auth rescope --token ${opts.tokenName} --operations ${operations.join(',')}${opts.source ? ` --sources ${opts.source}` : ''}`,
    'start `gbrain serve --http` again', 're-run this `gbrain bootstrap harness` command with --token <the token step 2 printed>'];
  return new BootstrapError('LIVE_SERVE', 'a live `gbrain serve` holds this PGLite brain, so the harness cannot mint a token, and with the serve ' +
    `stopped its health check fails. Pre-mint the token with the harness grant (scopes ${scopes.join(',')} and its operation list), then use ` +
    `--token:\n${steps.map((step, i) => `  ${i + 1}. ${step}`).join('\n')}\n(Postgres brains mint fine while the serve runs.)`, { details: { steps, scopes, operations } });
}

/** The engine could not open because a live serve holds the PGLite brain (vs any other failure). */
function isLiveServeFailure(msg: string, d: Pick<Required<HarnessDeps>, 'pgliteLiveServe'>): boolean {
  return /already open through `gbrain serve`|LiveServeLockError/i.test(msg) || d.pgliteLiveServe();
}

/** #5893: the token a host's rotation carries grants from, with the operations a skills-policy change adds. */
async function rotationCarry(prior: HarnessReceipt | null | undefined, host: HarnessTarget['host'], explicitSource: boolean, allowedOperations: string[]) {
  const fromId = prior?.harness_tokens?.[host]?.minted ? prior.harness_tokens[host]!.id : prior?.token.minted ? prior.token.id : undefined;
  if (!prior || !fromId) return undefined;
  const priorSnapshot = await harnessOperationSnapshot(prior.skills_policy === 'follow');
  return { fromId, explicitSource, policyAdded: allowedOperations.filter(op => !priorSnapshot.includes(op)) };
}

function withheldOperationsNote(name: string, count: number): string {
  return `token ${name}: carried the previous grants; ${count} newer operation(s) withheld — preview with \`gbrain auth rescope-token ${name} --refresh-operations\`.`;
}

async function harnessOperationSnapshot(follow: boolean): Promise<string[]> {
  const { operations } = await import('../operations.ts');
  return operations.filter(op => !op.localOnly && (op.scope === 'read' || op.scope === 'write') &&
    (op.requiredScopes ?? []).every(scope => follow && scope === 'skills_member_self')).map(op => op.name).sort();
}

async function leaveHarnessSkills(
  entry: NonNullable<HarnessReceipt['shared_skills']>[number],
  d: ReturnType<typeof resolveHarnessDeps>,
): Promise<boolean> {
  try {
    if (entry.status === 'left' || entry.status === 'left_with_retained_files') return true;
    if (!existsSync(join(entry.root, 'shared-skills', 'receipt.json'))) {
      entry.status = 'left';
      rmSync(join(entry.root, 'credentials.json'), { force: true });
      return true;
    }
    if (await credentialRevoked(entry, d)) return leaveRevokedEnrollment(entry, d);
    const credentials = readCredentials(join(entry.root, 'credentials.json'));
    if (credentials.mcp_url !== entry.url) throw new Error('credential endpoint mismatch');
    const result = await d.installSharedSkills(credentials, { harness: entry.host, root: entry.root, name: entry.name, remove: true });
    entry.status = result.status;
    entry.reason = result.reason;
    entry.retained_files = result.retained_files;
    if (result.remote_membership_pending) {
      entry.status = 'pending';
      entry.reason = 'remote_membership_pending';
      d.logError(`shared skills (${entry.host}): local cleanup completed; remote enrollment cleanup remains pending. Retaining the cleanup credential for retry.`);
      return false;
    }
    if (result.status !== 'left' && result.status !== 'left_with_retained_files') {
      d.logError(`shared skills (${entry.host}): removal pending; keep the cleanup credential and retry.`);
      return false;
    }
    if (result.retained_files?.length) d.log(`shared skills (${entry.host}): edited files retained: ${result.retained_files.join(', ')}`);
    rmSync(join(entry.root, 'credentials.json'), { force: true });
    return true;
  } catch {
    entry.status = 'pending';
    entry.reason = 'cleanup_unavailable';
    d.logError(`shared skills (${entry.host}): enrollment cleanup pending; restore its private credential and retry before revoking access.`);
    return false;
  }
}

/** Pre-consent notes about the ambient-writeback posture. Registrar mode never
 * installs blocks for the remote brain; #5671: an explicit private default is
 * write-only memory for the HTTP sessions this harness wires (remote reads are
 * world-only), so say so before the operator consents. */
function logAmbientPostureNotes(
  d: { log: (line: string) => void; logError: (line: string) => void },
  wb: { enabled: boolean; visibility_posture: 'world' | 'private' },
  registrarMode: boolean,
): void {
  if (wb.enabled && registrarMode) {
    d.log(
      'registrar mode: ambient-writeback instruction blocks are NOT installed for a remote brain — ' +
        'its own MCP instructions carry the contract when the remote operator enables memory.auto_writeback.',
    );
  }
  if (!registrarMode && wb.visibility_posture === 'private') {
    d.logError(
      'WARNING: facts.default_visibility is private, but this harness reads the brain over HTTP MCP — ' +
        `${PRIVATE_DEFAULT_REMOTE_CONSEQUENCE} (then run gbrain bootstrap harness again; it asks the user first).`,
    );
  }
}

export async function applyHarness(flags: HarnessFlags, rawDeps: HarnessDeps): Promise<number> {
  const d = resolveHarnessDeps(rawDeps);
  // stdout-for-data discipline: under --json, stdout carries ONLY the final
  // JSON document; every prose/progress line flows to stderr (matching the
  // statusHarness --json contract, so machine callers never scrape).
  const emitJson = d.log;
  if (flags.json) (d as { log: (line: string) => void }).log = d.logError;

  // 1. Validate inputs + detect harnesses.
  for (const dir of flags.projects) {
    if (!existsSync(dir) || !statSync(dir).isDirectory()) {
      d.logError(`--project directory does not exist: ${dir}`);
      return 2;
    }
  }
  if (flags.token !== undefined) {
    const v = validateToken(flags.token);
    if (!v.ok) {
      d.logError(`--token: ${v.error}`);
      return 2;
    }
  }
  // [X1] Detection heuristics gate only the `all` DEFAULT. An explicit
  // `--harness codex` FORCES wiring: the TOML writer needs no codex CLI and
  // creates the config 0600 — that no-CLI box (embedded/ACP codex) is the
  // exact use case #4043 filed. Claude Code stays CLI-gated even when
  // explicit (we exec `claude mcp add`; it owns ~/.claude.json).
  const wireClaude = (flags.harness === 'all' || flags.harness === 'claude-code') && d.detectClaude();
  const wireCodex = flags.harness === 'codex' || (flags.harness === 'all' && d.detectCodex());
  // opencode mirrors codex: an explicit --harness opencode FORCES wiring (the
  // JSONC writer needs no opencode CLI and creates the config file itself).
  const wireOpencode = flags.harness === 'opencode' || (flags.harness === 'all' && d.detectOpencode());
  if (flags.harness === 'claude-code' && !wireClaude) {
    d.logError('claude CLI not found on PATH — the user-scope MCP registration needs it (it owns ~/.claude.json).');
    return 2;
  }
  if (!wireClaude && !wireCodex && !wireOpencode) {
    d.logError(
      'no harness detected on this box (claude CLI not on PATH; no codex install; no opencode install) — ' +
        'pass --harness claude-code|codex|opencode explicitly if detection is wrong.',
    );
    return 2;
  }

  // 2. Serve health + loopback guard [F3].
  const norm = normalizeMcpUrl(flags.url ?? `http://127.0.0.1:${flags.port ?? 3131}/mcp`);
  if (!norm.ok) {
    d.logError(norm.error);
    return 2;
  }
  const url = norm.url;
  if (norm.warning) d.logError(norm.warning); // [X13] never discard the http-bearer warning
  const hostname = new URL(url).hostname;
  if (flags.url !== undefined && !isLoopbackHostname(hostname) && flags.token === undefined) {
    d.logError(
      `--url points at a non-loopback host (${hostname}) but the token would be minted in the LOCAL brain — ` +
        'those are different databases. For a remote brain use `gbrain connect --install`; ' +
        'to use harness mode as a pure registrar for a LAN serve, pass --token <bearer> from that brain.',
    );
    return 2;
  }
  // [X13] Registrar mode: a non-loopback --url + --token registers a REMOTE
  // serve, but hooks always talk to the LOCAL brain (gbrain bin + local
  // config) — wiring them here would split-brain the box. MCP only.
  const registrarMode = flags.url !== undefined && !isLoopbackHostname(hostname);
  if (registrarMode && !flags.noHooks && (wireClaude || wireCodex)) {
    d.log('registrar mode (non-loopback url): hooks are NOT wired — they would talk to the LOCAL brain, not the registered remote serve. MCP registration only.');
  }
  const health = await probeServeHealth(url, d.fetchFn);
  const verifyPending = harnessVerifyPending(health, flags, registrarMode, url, d); // #6661: logs the verdict
  if (!health.ok && !verifyPending) return 1;

  // 2b. Ambient-writeback gate (WP3): resolved from the FILE plane only —
  // this lane is engine-free by design (the DB plane stays authoritative for
  // extraction; doctor's drift check catches plane divergence). Default OFF.
  // REGISTRAR MODE never installs instruction blocks (adversarial review,
  // this wave): the local file mirror speaks for the LOCAL brain, but the
  // block would order agents to save into the REMOTE brain — whose operator
  // may never have opted in. That brain's own serve advertises the ambient
  // section over MCP `instructions` when ITS config enables it.
  const wb = resolveWritebackConfigFromFile(d.loadFileConfig());
  const wbInstall = wb.enabled && !registrarMode;
  logAmbientPostureNotes(d, wb, registrarMode);
  const ambientBody =
    !wbInstall
      ? null
      : renderAmbientInstructionBlock({
          mode: wb.mode as 'salient' | 'all',
          transientTtl: wb.transient_ttl,
          visibility: wb.visibility_posture,
          serveUrl: url,
        });
  const instructionsPaths = wbInstall
    ? [...(wireClaude ? [d.claudeMemoryPath] : []), ...(wireCodex ? [d.codexAgentsPath] : [])]
    : [];

  // 3. Consent (connect --install shape; never the interview/A8 ledger).
  const wireHooks = wireClaude && !flags.noHooks && !registrarMode; // Codex capture below: same consent, never registrar
  const wireCodexCapture = wireCodex && !flags.noHooks && !flags.noCapture && !registrarMode;
  const priorState = readHarnessReceiptState(d.gbrainHome);
  const prior = priorState.state === 'ok' ? priorState.receipt : null;
  const skillsPolicy = flags.skills ?? prior?.skills_policy ?? (priorState.state === 'absent' ? 'follow' : 'memory-only');
  const hookScope = flags.projects.length > 0 ? `${flags.projects.length} project dir(s)` : 'user scope';
  const consent = buildConsentBlock({
    tokenName: flags.tokenName,
    tokenSupplied: flags.token !== undefined,
    scopes: skillsPolicy === 'follow' ? ['read', 'write', 'skills_member_self'] : ['read', 'write'],
    skills: skillsPolicy,
    url,
    wireClaude,
    wireCodex,
    wireOpencode,
    hooks: wireHooks,
    capture: !flags.noCapture,
    codexCapture: wireCodexCapture,
    hookScope,
    name: flags.name,
    userSettingsPath: d.userSettingsPath,
    codexConfig: d.codexConfig,
    opencodeConfig: d.opencodeConfig,
    ...(instructionsPaths.length > 0 ? { instructionsPaths } : {}),
    turnRuleHosts: harnessTurnRuleHosts({ off: flags.noHooks || registrarMode || flags.noInstructions, wireClaude, claudeHooksWired: wireHooks, wireCodex }),
  });
  d.log(consent);
  const harnesses = [wireClaude ? 'Claude Code' : null, wireCodex ? 'Codex' : null, wireOpencode ? 'opencode' : null].filter(Boolean).join(', ');
  if (!(await askHarnessConsent({ flags, url, harnesses, skillsPolicy, wireHooks, hookScope }, d))) return CONFIRMATION_REQUIRED_EXIT_CODE;

  // Prior receipt: carries the previous minted token for post-wire rotation
  // [C7], and the prior hook-scope for the user-XOR-project exclusivity check
  // [C6].
  if (prior) {
    const priorProjectHooks = prior.targets.some(
      (t) => t.kind === 'hooks' && t.scope !== 'user' && t.state !== 'failed',
    );
    const priorUserHooks = prior.targets.some(
      (t) => t.kind === 'hooks' && t.scope === 'user' && t.state !== 'failed',
    );
    if (flags.projects.length > 0 && priorUserHooks) {
      d.logError(
        'this box already carries USER-scope harness hooks; --project would double-fire every event ' +
          '(Claude Code merges the scopes). Run `gbrain bootstrap harness --remove` first, then re-apply with --project.',
      );
      return 2;
    }
    if (flags.projects.length === 0 && !flags.noHooks && priorProjectHooks) {
      d.logError(
        'this box already carries PROJECT-scope harness hooks; user-scope wiring would double-fire every event. ' +
          'Run `gbrain bootstrap harness --remove` first, or re-apply with the same --project list.',
      );
      return 2;
    }
  }
  // Cross-HOME exclusivity (the receipt check above only sees THIS home's
  // install): when wiring --project, another install's USER-scope harness
  // hooks would double-fire in that project — the user settings file is
  // knowable, so scan it. (The reverse — user-scope wiring vs some other
  // home's --project dirs — is not enumerable; the receipt check plus the
  // same-file writer refusal are the guards there.)
  // Marked or not (the host may drop the marker): an unreadable file falls
  // through to the writers' own fail-closed paths.
  if (flags.projects.length > 0 && !flags.noHooks && harnessHooksPresent(d.userSettingsPath)) {
    d.logError(
      `user-scope harness hooks already exist in ${d.userSettingsPath} (edited entries included; possibly from another GBRAIN_HOME's ` +
        'install); --project wiring would double-fire every event. Remove that install first ' +
        '(`gbrain bootstrap harness --remove` under its home).',
    );
    return 2;
  }

  // 4. Plan targets + WRITE-AHEAD receipt [F1/X6] — BEFORE the mint, so a
  // crash (or a newer-format receipt refusal) can never leave a live token
  // no receipt records.
  // #4897: without --source the hooks must claim the source the serve's
  // resolve-IPC listener is bound to — resolved through the SAME chain the
  // serve runs (env → dotfile → local_path → sources.default → sole
  // non-default → seed default), or every turn_context is `source_mismatch`.
  // The token floors on that source's federated read set (what search/think
  // read): the federated-default mint cannot read a sole non-federated
  // source (page_count 0). A resolution that lands on the seeded 'default'
  // (or a `__all__` env) is the federated floor, not a scalar grant (same
  // guard as dream.ts).
  let bound: HookSourceBinding;
  // Live PGLite serve + --token, no --source: the hooks carry NO source pin
  // (a claim-free request resolves through the serve's own binding).
  let unpinnedHooks = false;
  try {
    if (registrarMode) {
      bound = { source_id: flags.source ?? 'default', grant: flags.source ? [flags.source] : [] };
      unpinnedHooks = !flags.source;
    } else bound = await d.resolveHookSource(flags.source ?? null);
  } catch (e) {
    const msg = e instanceof Error ? e.message : String(e);
    if (isResolverUserError(e)) {
      // A typo'd --source / stale GBRAIN_SOURCE or dotfile: minting a token
      // to a phantom scope would "succeed" and then read nothing.
      throw new BootstrapError('SOURCE_UNRESOLVED', msg);
    }
    if (flags.source) {
      // The engine could not open (a live PGLite serve + --token is the
      // documented path here); the explicit id is the operator's word.
      d.logError(`WARNING: could not verify --source '${flags.source}' against the brain (${msg}); binding to it unverified.`);
      bound = { source_id: flags.source, grant: [flags.source] };
    } else if (isLiveServeFailure(msg, d)) {
      // A live PGLite serve holds the brain. Without a token the mint below
      // would refuse anyway — refuse HERE with the same two escape hatches, so
      // the operator never sees a source-resolution error for a lock problem.
      if (flags.token === undefined) throw await liveServeRefusal({ tokenName: flags.tokenName, follow: skillsPolicy === 'follow' });
      // --token lane (the documented PGLite path): nothing is minted, so the
      // grant is the operator's own token. Leave the hooks UNPINNED — a hook
      // request that names no source resolves through the live serve's own
      // binding, which is exactly the source the serve resolves (#4897). Say
      // so, and name the override.
      d.logError(
        'WARNING: a live `gbrain serve` holds this PGLite brain, so the harness could not read which source it ' +
          "serves; wiring the hooks unpinned (they resolve through the live serve). If `gbrain sources list` " +
          "shows a default other than 'default', re-run with --source <id>.",
      );
      bound = { source_id: 'default', grant: ['default'] };
      unpinnedHooks = true;
    } else {
      // Silently binding 'default' here is the #4897 bug reopened: the serve
      // may resolve a different source and every hook turn would mismatch.
      throw new BootstrapError(
        'SOURCE_UNRESOLVED',
        `could not resolve the source the serve binds its hooks to (${msg}) — pass --source <id> ` +
          '(`gbrain sources list` shows the registered ids) and re-run.',
      );
    }
  }
  const implicitSource =
    flags.source || bound.source_id === 'default' || bound.source_id === ALL_SOURCES ? null : bound.source_id;
  const hookSource: string | null = unpinnedHooks ? null : (flags.source ?? implicitSource ?? 'default');
  if (implicitSource) {
    d.log(`binding hooks + token to source '${implicitSource}' (the serve's resolved default; pass --source to override).`);
  }
  const guard = guardHarnessReceiptOverwrite(d.gbrainHome);
  if (guard.brokenBackupPath) {
    d.logError(`WARNING: the harness receipt was unreadable; backed it up to ${guard.brokenBackupPath}.`);
  }
  const targets: HarnessTarget[] = [];
  if (wireClaude) {
    targets.push({ host: 'claude-code', kind: 'mcp', state: 'pending', scope: 'user', name: flags.name, mechanism: 'claude-cli' });
    // A re-run finds its own earlier entry already allowed: ownership carries
    // from the prior receipt (a legacy confirmed target without a mechanism
    // is ours) so it is never relabeled pre-existing.
    const priorPerm = prior?.targets.find((t) => t.kind === 'permission' && t.path === d.userSettingsPath && t.entry === mcpPermissionEntry(flags.name));
    targets.push({
      host: 'claude-code',
      kind: 'permission',
      state: 'pending',
      scope: 'user',
      path: d.userSettingsPath,
      entry: mcpPermissionEntry(flags.name),
      ...(priorPerm?.state === 'confirmed' && priorPerm.mechanism !== 'pre-existing' ? { mechanism: 'added' } : {}),
    });
    if (wireHooks) {
      if (flags.projects.length > 0) {
        for (const dir of flags.projects) {
          targets.push({
            host: 'claude-code',
            kind: 'hooks',
            state: 'pending',
            scope: dir,
            path: claudeSettingsPath(dir),
            marker: GBRAIN_HARNESS_MARKER_VALUE,
          });
        }
      } else {
        targets.push({
          host: 'claude-code',
          kind: 'hooks',
          state: 'pending',
          scope: 'user',
          path: d.userSettingsPath,
          marker: GBRAIN_HARNESS_MARKER_VALUE,
        });
      }
    }
    if (wbInstall) {
      targets.push({
        host: 'claude-code',
        kind: 'instructions',
        state: 'pending',
        scope: 'user',
        path: d.claudeMemoryPath,
        mechanism: 'managed-block',
      });
    }
  }
  if (wireCodex) {
    targets.push({
      host: 'codex',
      kind: 'mcp',
      state: 'pending',
      scope: 'user',
      path: d.codexConfig,
      name: flags.name,
      mechanism: 'toml-block',
    });
    if (wbInstall) {
      targets.push({
        host: 'codex',
        kind: 'instructions',
        state: 'pending',
        scope: 'user',
        path: d.codexAgentsPath,
        mechanism: 'managed-block',
      });
    }
  }
  if (wireOpencode) {
    targets.push({
      host: 'opencode',
      kind: 'mcp',
      state: 'pending',
      scope: 'user',
      path: d.opencodeConfig,
      name: flags.name,
      mechanism: 'jsonc-entry',
    });
  }
  // [X4] EVERY unrevoked prior minted id is carried — on the --token lane
  // too. A failed rotation must never forget the token before last.
  const carriedPreviousIds = [...new Set([
    ...(prior?.token.previous_ids ?? []),
    ...(prior?.token.minted && prior.token.id ? [prior.token.id] : []),
    ...Object.values(prior?.harness_tokens ?? {}).flatMap(t => t.minted && t.id ? [t.id] : []),
  ])];
  const receipt: HarnessReceipt = {
    harness_receipt_version: 1,
    created_at: new Date().toISOString(),
    created_by: `gbrain@${VERSION}`,
    url,
    ...(health.engine ? { engine: health.engine } : {}),
    ...(health.version ? { serve_version: health.version } : {}),
    source_id: hookSource ?? 'default',
    ...(unpinnedHooks ? { source_pinned: false as const } : {}),
    token: {
      name: flags.tokenName,
      minted: flags.token === undefined,
      ...(carriedPreviousIds.length > 0 ? { previous_ids: carriedPreviousIds } : {}),
    },
    skills_policy: skillsPolicy,
    harness_tokens: {},
    shared_skills: [...(prior?.shared_skills ?? [])],
    targets,
  };
  writeHarnessReceipt(d.gbrainHome, receipt);
  const save = () => writeHarnessReceipt(d.gbrainHome, receipt);

  // ([X3] convergence cleanup of dropped prior targets is DEFERRED to after
  // the smoke passes — see step 9. Unwiring the old working state before the
  // mint even succeeds would leave the box disconnected when a PGLite lock or
  // mint failure aborts the run: mint-first applies to removals too.)

  // 5. Token — mint-first [C7]; the receipt already exists [X6].
  let token: string;
  const tokens = new Map<HarnessTarget['host'], string>();
  const hosts = targets.filter(t => t.kind === 'mcp').map(t => t.host);
  if (flags.token !== undefined) {
    token = flags.token;
    for (const host of hosts) {
      tokens.set(host, token);
      receipt.harness_tokens![host] = { minted: false, name: flags.tokenName };
    }
  } else {
    const allowedOperations = await harnessOperationSnapshot(skillsPolicy === 'follow');
    for (const host of hosts) {
      let minted: MintedLegacyToken;
      const carry = await rotationCarry(prior, host, !!flags.source, allowedOperations);
      try {
        minted = await d.mint({
          name: hosts.length === 1 ? flags.tokenName : `${flags.tokenName}-${host}`,
          scopes: skillsPolicy === 'follow' ? ['read', 'write', 'skills_member_self'] : ['read', 'write'],
          allowedOperations,
          ...(carry ? { carry } : {}),
          // [X2] --source is the write floor — a scalar grant, the stdio
          // env-tier mirror. An implicit non-default source carries its
          // federated read set (#4897 — the same set search/think read, not a
          // scalar that would hide every federated sibling). Neither → the
          // default mint federates.
          ...(flags.source || implicitSource ? { sourceGrant: bound.grant } : {}),
        });
      } catch (e) {
        const msg = e instanceof Error ? e.message : String(e);
        if (isLiveServeFailure(msg, d)) throw await liveServeRefusal({ tokenName: flags.tokenName, follow: skillsPolicy === 'follow', ...(flags.source ? { source: flags.source } : {}) });
        throw e;
      }
      tokens.set(host, minted.token);
      if (minted.withheldOperations?.length) d.log(withheldOperationsNote(minted.name, minted.withheldOperations.length));
      if (minted.uncarriedPrivatePages) d.log(uncarriedPrivatePagesNote(minted.name, minted.uncarriedPrivatePages));
      receipt.harness_tokens![host] = { id: minted.id, name: minted.name, minted: true };
      if (host === hosts[0]) {
        receipt.token.id = minted.id;
        receipt.token.name = minted.name;
      }
      save();
    }
    token = tokens.get(hosts[0])!;
  }

  const confirm = (t: HarnessTarget) => {
    t.state = 'confirmed';
    save();
  };
  const failTarget = (t: HarnessTarget, err: string) => {
    t.state = 'failed';
    t.error = err;
    save();
    d.logError(`FAILED (${t.host}/${t.kind}${t.scope !== 'user' ? ` ${t.scope}` : ''}): ${err}`);
  };

  // 6. Claude Code wiring — under a config-dir lock [X11]: serializes gbrain
  // writers (even with different GBRAIN_HOMEs) against the same user-scope
  // files. The race with Claude Code ITSELF is irreducible by any lock we
  // hold; the docs say so.
  const hookEvents: ClaudeHookEvent[] = flags.noCapture
    ? ([...CLAUDE_HOOK_EVENTS].filter((e) => e !== 'Stop' && e !== 'SessionEnd') as ClaudeHookEvent[])
    : [...CLAUDE_HOOK_EVENTS];
  // [X5] Captured for rollback: the previous working claude registration and
  // the codex .bak from THIS run — a failed apply restores a working state
  // (the old token is still valid; mint-first means nothing was revoked yet).
  let oldClaudeReg: { url: string; token: string } | null = null;
  let permissionAddedThisRun = false;
  let claudeReplaced = false;
  let codexRollback: { path: string; backupPath: string | null; replacedPrior: boolean } | null = null;
  let opencodeRollback: {
    path: string;
    backupPath: string | null;
    replacedPrior: boolean;
    /** Exact text this run's writer landed — the rollback compares the LIVE
     * file against it before restoring (the lock is released before the
     * smoke, so a newer registration may have landed since). */
    writtenText: string;
  } | null = null;
  let cfgLock: Awaited<ReturnType<typeof acquireBootstrapLock>> | null = null;
  if (wireClaude) {
    const cfgDir = dirname(d.userSettingsPath);
    mkdirSync(cfgDir, { recursive: true }); // the lock needs the dir; writers mkdir later anyway
    cfgLock = await acquireBootstrapLock(cfgDir);
  }
  try {
  for (const t of targets) {
    if (t.host !== 'claude-code') continue;
    const token = tokens.get(t.host)!;
    try {
      if (t.kind === 'mcp') {
        // [C8] Ownership: an existing registration at a DIFFERENT url is
        // another brain's wiring.
        const get = await d.runner(['claude', 'mcp', 'get', flags.name]);
        if (get.code === 0) {
          const out = `${get.stdout}\n${get.stderr}`;
          const info = parseClaudeMcpGetUrl(out);
          if (info.found && info.url && info.url !== url && !flags.force) {
            failTarget(
              t,
              `an existing '${flags.name}' registration points at ${info.url}, not ${url} — ` +
                'another brain owns it; pass --force to replace, or --name <other>.',
            );
            continue;
          }
          if (info.found) {
            const oldBearer = parseClaudeMcpGetBearer(out);
            // A rollback with a garbage bearer would silently BREAK the
            // registration it exists to preserve — if the CLI ever redacts
            // header values ('***', '<redacted>'), treat the old bearer as
            // unrecoverable and take the honest-degrade branch instead.
            if (info.url && oldBearer && validateToken(oldBearer).ok && !/^[*<]/.test(oldBearer)) {
              oldClaudeReg = { url: info.url, token: oldBearer };
            }
            await d.runner(['claude', 'mcp', 'remove', flags.name, '--scope', 'user']);
            claudeReplaced = true;
          }
        }
        const add = await d.runner([
          'claude',
          ...buildClaudeMcpAddArgv({ name: flags.name, url, headerToken: token, scope: 'user' }),
        ]);
        if (add.code !== 0) {
          failTarget(t, redactToken(add.stderr.trim() || `exit ${add.code}`, token));
          // [X5] The old registration was already removed — restore it so
          // existing clients stay connected (its token is still valid).
          if (oldClaudeReg) {
            const restore = await d.runner([
              'claude',
              ...buildClaudeMcpAddArgv({ name: flags.name, url: oldClaudeReg.url, headerToken: oldClaudeReg.token, scope: 'user' }),
            ]);
            d.log(
              restore.code === 0
                ? 'previous MCP registration restored — existing clients stay connected.'
                : 'could not restore the previous MCP registration — re-run to converge.',
            );
          }
          continue;
        }
        confirm(t);
        d.log(`MCP registered with Claude Code (user scope) -> ${url}`);
      } else if (t.kind === 'permission') {
        // The pre-approval string only makes sense for OUR registration —
        // when the mcp target failed (ownership refusal, add failure), wiring
        // `mcp__<name>` would pre-approve whatever server owns that name,
        // possibly another brain's (red-team CRITICAL).
        const mcpTarget = targets.find((x) => x.host === 'claude-code' && x.kind === 'mcp');
        if (mcpTarget && mcpTarget.state !== 'confirmed') {
          failTarget(t, 'skipped: the MCP registration itself did not land — pre-approving the name would bless a foreign server');
          continue;
        }
        const r = addPermissionsAllowEntry(t.path!, t.entry!);
        for (const note of r.notes) d.logError(note);
        permissionAddedThisRun = r.added === true;
        if (r.added === false && t.mechanism === 'added') {
          confirm(t);
          d.log(`headless pre-approval: '${t.entry}' already in permissions.allow from the previous harness install.`);
        } else if (r.added === false) {
          // [X8] Already allowed before us — record it as pre-existing so
          // removal never deletes what we didn't add.
          t.mechanism = 'pre-existing';
          confirm(t);
          d.log(`headless pre-approval: '${t.entry}' was already allowed (pre-existing — remove will leave it).`);
        } else {
          t.mechanism = 'added';
          confirm(t);
          d.log(`headless pre-approval: '${t.entry}' in permissions.allow (${t.path})`);
        }
      } else if (t.kind === 'instructions') {
        // Under the cfgLock already held for this loop — CLAUDE.md lives in
        // the same config dir the lock serializes. The null-guard replaces a
        // pair of `!` assertions whose invariant (targets planned ⟺ body
        // rendered) lived 350 lines away: if a future edit decouples them,
        // this fails the TARGET, not the whole install loop.
        if (!t.path || ambientBody === null) {
          failTarget(t, 'internal: instructions target planned without a rendered block body');
          continue;
        }
        // Same precedent as the permission pre-approval above: the block
        // orders agents to save through THIS host's gbrain registration —
        // if that registration didn't land (foreign-url refusal, write
        // failure), installing the block would direct ambient saves at
        // whatever server already owns the name, a consent the operator
        // never gave (codex re-review, this wave).
        const hostMcp = targets.find((x) => x.host === t.host && x.kind === 'mcp');
        if (hostMcp && hostMcp.state !== 'confirmed') {
          failTarget(t, `skipped: the ${t.host} MCP registration itself did not land — an instruction block without it would direct saves at a foreign server`);
          continue;
        }
        installAmbientWritebackBlockAt(t.path, ambientBody);
        confirm(t);
        d.log(`ambient-writeback instruction block installed in ${t.path} (mode: ${wb.mode}).`);
      } else {
        const settingsPath = t.scope === 'user' ? d.userSettingsPath : t.path!;
        const env: ClaudeHookEnv = {
          ...(hookSource !== null ? { GBRAIN_SOURCE: hookSource } : {}),
          GBRAIN_HOOK_LANE: 'harness',
          GBRAIN_SEAT: flags.seat,
        };
        const bin = flags.gbrainBin ?? d.gbrainBin;
        if (!bin) {
          failTarget(t, 'cannot resolve an absolute gbrain binary path — pass --gbrain-bin <abs path>');
          continue;
        }
        const r = writeClaudeHooksAt(settingsPath, {
          gbrainBin: bin,
          hookLauncher: ensureHookLauncher(hookLauncherPath(d.gbrainHome)),
          env,
          events: hookEvents,
          marker: GBRAIN_HARNESS_MARKER_VALUE,
          backupStrategy: 'timestamped',
          refuseOnForeignGbrainMarker: true,
          identity: harnessHookIdentity(prior, prior?.targets.find((p) => p.kind === 'hooks' && p.path === t.path),
            { launcher: bin, source: hookSource, seat: flags.seat }),
          ...(t.scope === 'user'
            ? { freshMode: 0o600 }
            : // [D12] a --project dir whose COMMITTED settings carry workspace
              // events must not get inert harness duplicates for them (the
              // runtime lane guard would make those entries yield forever).
              { carriedEvents: committedHookEvents(dirname(dirname(t.path!))) }),
        });
        for (const note of r.notes) d.logError(note);
        t.launcher = bin;
        t.seat = r.seat;
        confirm(t);
        d.log(
          `hooks wired (${r.installed.length} event(s)${flags.noCapture ? ', capture off' : ''}) in ${r.settingsPath}`,
        );
      }
    } catch (e) {
      failTarget(t, e instanceof Error ? e.message : String(e));
    }
  }
  } finally {
    cfgLock?.release();
  }

  // 7. Codex wiring — the managed TOML block is the single write mechanism.
  // Same [X11] discipline as the claude lane: config.toml is user-global, so
  // gbrain writers with different GBRAIN_HOMEs serialize on ITS directory.
  for (const t of targets) {
    if (t.host !== 'codex') continue;
    const token = tokens.get(t.host)!;
    if (t.kind === 'instructions') {
      try {
        // [OV-A4] Exclusivity pre-check: when AGENTS.override.md exists,
        // codex loads IT and IGNORES AGENTS.md — a block written there is a
        // dead integration and must never be reported as installed.
        if (existsSync(d.codexAgentsOverride)) {
          failTarget(
            t,
            `codex ignores ${t.path} while ${d.codexAgentsOverride} exists (AGENTS.override.md loads ` +
              `exclusively, per developers.openai.com/codex/guides/agents-md) — fold the ambient-writeback ` +
              `block into that file yourself, or remove it and re-run \`gbrain bootstrap harness\`.`,
          );
        } else if (!t.path || ambientBody === null) {
          // Same decoupling guard as the claude lane: fail the TARGET.
          failTarget(t, 'internal: instructions target planned without a rendered block body');
        } else if ((() => {
          // Same registration guard as the claude lane (codex re-review):
          // the codex MCP target is applied EARLIER in this loop (planned
          // first), so its state is final here — a foreign-toml refusal or
          // failed write must not leave a block directing ambient saves at
          // a server this run never registered.
          const codexMcp = targets.find((x) => x.host === 'codex' && x.kind === 'mcp');
          return codexMcp !== undefined && codexMcp.state !== 'confirmed';
        })()) {
          failTarget(t, 'skipped: the codex MCP registration itself did not land — an instruction block without it would direct saves at a foreign server');
        } else {
          // Same [X11] lock discipline as the managed TOML block: AGENTS.md
          // is a user-global shared file.
          const agentsDir = dirname(t.path);
          mkdirSync(agentsDir, { recursive: true });
          const agentsLock = await acquireBootstrapLock(agentsDir);
          try {
            installAmbientWritebackBlockAt(t.path, ambientBody);
          } finally {
            agentsLock.release();
          }
          confirm(t);
          d.log(`ambient-writeback instruction block installed in ${t.path} (mode: ${wb.mode}).`);
        }
      } catch (e) {
        failTarget(t, e instanceof Error ? e.message : String(e));
      }
      continue;
    }
    try {
      // Plugin-lane collision WARN (not a refusal — the harness lane serves
      // framework-spawned sessions over HTTP and may legitimately coexist
      // with the plugin's stdio serve): two servers named `<name>` in
      // different layers means duplicate tool registration, and which wins
      // is host-defined.
      const pluginOwner = codexPluginProvidesName(t.path!, flags.name);
      if (pluginOwner) {
        d.logError(
          `WARNING: the '${pluginOwner}' codex plugin also provides an MCP server named '${flags.name}' — ` +
            'after this wire, two servers with the same name exist in different layers (plugin + managed block); ' +
            'duplicate tool registration behavior is host-defined. Keep one: `codex plugin remove gbrain`, ' +
            'or re-run with `--remove` to drop the managed block.',
        );
      }
      const codexDir = dirname(t.path!);
      mkdirSync(codexDir, { recursive: true });
      const codexLock = await acquireBootstrapLock(codexDir);
      let r: ReturnType<typeof writeCodexHttpServerBlock>;
      try {
        r = writeCodexHttpServerBlock(t.path!, { name: flags.name, url, bearerToken: token });
      } finally {
        codexLock.release();
      }
      for (const note of r.notes) d.logError(note);
      codexRollback = { path: t.path!, backupPath: r.backupPath, replacedPrior: r.replacedPrior };
      confirm(t);
      d.log(
        `Codex wired: [mcp_servers.${flags.name}] with inline bearer token in ${t.path} (0600). ` +
          'Per-turn context on codex is MCP tools + the pull protocol. ' +
          '[X9] If codex cannot see the server, some builds gate HTTP MCP behind ' +
          'experimental_use_rmcp_client = true in the same config — add it above the managed block.',
      );
      // Codex SessionEnd capture (v1: session-end only): user-global
      // hooks.json + its config.toml trust entry via the ONE writer
      // (codex-hooks.ts) — idempotent, so a workspace-lane bootstrap and this
      // harness lane converge on the same entry. No GBRAIN_SOURCE in the
      // command (machine-global file; session-end resolves from the payload).
      if (wireCodexCapture) {
        const hooksBin = flags.gbrainBin ?? d.gbrainBin;
        if (!hooksBin) {
          d.logError('codex hooks skipped: cannot resolve an absolute gbrain binary path — pass --gbrain-bin <abs path>.');
        } else {
          // Paths derive from THIS TARGET's config.toml (CODEX_HOME-resolved
          // upstream, test-injectable) — never the ambient global default.
          const hr = writeCodexHooks({ gbrainBin: hooksBin, hookLauncher: ensureHookLauncher(hookLauncherPath(d.gbrainHome)), configPath: t.path!, hooksPath: join(dirname(t.path!), 'hooks.json') });
          if (hr.ok) d.log(`Codex SessionEnd hook wired: ${hr.hooksPath} + trust entry in ${hr.configPath}.`);
          else for (const note of hr.notes) d.logError(note);
        }
      }
    } catch (e) {
      failTarget(t, e instanceof Error ? e.message : String(e));
    }
  }

  // 7b. opencode wiring — the managed JSONC entry is the single write
  // mechanism (opencode-json.ts; fingerprint-owned, comment-preserving).
  // Same [X11] lock discipline; same forced-wire posture as codex.
  for (const t of targets) {
    if (t.host !== 'opencode') continue;
    const token = tokens.get(t.host)!;
    try {
      const ocDir = dirname(t.path!);
      mkdirSync(ocDir, { recursive: true });
      const ocLock = await acquireBootstrapLock(ocDir);
      let r: ReturnType<typeof writeOpencodeMcpEntry>;
      try {
        // Ownership [C8]: an entry at OUR new url (idempotent re-run) or at
        // the PRIOR receipt's url (rotation across a port change) is ours;
        // anything else under the name refuses inside the writer. The prior
        // url is offered as the expectation only when the current one does
        // not classify the entry as ours.
        let expectUrl = url;
        if (prior && prior.url !== url && existsSync(t.path!)) {
          try {
            const parsedExisting = parseOpencodeConfig(readFileSync(t.path!, 'utf8'), t.path!);
            if (
              opencodeEntryKind(parsedExisting, flags.name, { url }) === 'foreign' &&
              opencodeEntryKind(parsedExisting, flags.name, { url: prior.url }) === 'ours-same-source'
            ) {
              expectUrl = prior.url;
            }
          } catch {
            /* the writer's own read path raises the real error below */
          }
        }
        // Two-filename merge blind spot: opencode merges BOTH user-global
        // filenames, so a same-name gbrain entry in the SIBLING file would
        // survive this write as a shadow registration. Reconcile under the
        // same config-dir lock (ours → removed with a note; foreign →
        // refuse loudly naming both files).
        const sib = reconcileOpencodeSiblingGlobal(t.path!, flags.name, { url: expectUrl });
        for (const note of sib.notes) d.log(note);
        r = writeOpencodeMcpEntry(
          t.path!,
          { kind: 'remote', name: flags.name, url, tokenMode: 'inline', bearerToken: token },
          { expect: { url: expectUrl }, allowReplaceOtherSource: true },
        );
      } finally {
        ocLock.release();
      }
      for (const note of r.notes) d.logError(note);
      opencodeRollback = { path: t.path!, backupPath: r.backupPath, replacedPrior: r.replacedPrior, writtenText: r.writtenText };
      confirm(t);
      d.log(
        `opencode wired: mcp.${flags.name} remote entry with inline bearer header in ${t.path} (0600). ` +
          'opencode ships a plugin/event system, but gbrain does not wire it yet — per-turn context on ' +
          'opencode is MCP tools + the pull protocol (AGENTS.md loads natively). Restart opencode: it ' +
          'reads config at session start.',
      );
    } catch (e) {
      // Redaction parity with the claude lane: the writer's refusal messages
      // can embed a paste-by-hand snippet, and the receipt + stderr must
      // never carry the live bearer under any error shape.
      failTarget(t, redactToken(e instanceof Error ? e.message : String(e), token));
    }
  }

  // 8. Smoke [C3-enriched message; X10 verbs-surface honesty]. An
  // unknown-tool tool_error means initialize + auth ALREADY succeeded — a
  // serve running a narrowed --surface (e.g. verbs) is verified, not broken.
  //
  // CANARY first (ship-review P0, three reviewers convergent): the smoke
  // sends the real bearer to whatever answers on the port, and an impostor
  // squatting 127.0.0.1 could accept it, fake an identity, and trigger
  // previous-token revocation. A real gbrain serve validates bearers against
  // the brain DB, so it MUST reject a random same-format token with an auth
  // failure — an impostor cannot tell the canary from the real token (same
  // format, both unknown to it), so it either rejects both (smoke fails,
  // nothing revoked, rollback fires) or accepts the canary and is caught
  // here. Either way the fresh mint is revoked below, never left live.
  const canary = await d.probeIdentity(url, generateToken('gbrain_'));
  let smoke: ConnectProbeResult;
  if (canary.ok || canary.reason === 'tool_error') {
    smoke = {
      ok: false,
      reason: 'auth',
      message:
        'the endpoint accepted an INVALID credential — whatever answers on this port is not a gbrain serve ' +
        'backed by this brain (loopback impostor guard). Wiring rolled back; nothing revoked.',
    };
  } else {
    smoke = await d.probeIdentity(url, token);
    for (const other of new Set(tokens.values())) {
      if (other === token || (!smoke.ok && smoke.reason !== 'tool_error')) continue;
      const result = await d.probeIdentity(url, other);
      if (!result.ok && result.reason !== 'tool_error') smoke = { ...result, message: redactToken(result.message, other) };
    }
  }
  const smokeOk = smoke.ok || (!smoke.ok && smoke.reason === 'tool_error');
  if (smoke.ok) {
    d.log(`smoke test: ${smoke.identity}`);
  } else if (smoke.reason === 'tool_error') {
    d.log(
      'smoke test: token authenticated (initialize + tool dispatch reached); get_brain_identity ' +
        'unavailable — the serve likely runs a narrowed --surface (e.g. verbs). Counted as verified.',
    );
  } else if (!verifyPending || !['unreachable', 'timeout'].includes(smoke.reason)) { // #6661: nothing answered, nothing to roll back
    d.logError(
      redactToken(
        `smoke test FAILED (${smoke.reason}): ${smoke.message}` +
          (smoke.reason === 'auth' && flags.token === undefined
            ? ' — a fresh-minted token failing auth against a live loopback serve means the serve is NOT ' +
              'backed by this brain; check the serve process’s GBRAIN_HOME / DATABASE_URL.'
            : ''),
        token,
      ),
    );
    // [X5] Roll the host registrations back to the last working state — the
    // old token is still valid (mint-first), so old clients keep working for
    // real, not rhetorically.
    if (codexRollback) {
      try {
        const rbLock = await acquireBootstrapLock(dirname(codexRollback.path)); // [X11] parity
        try {
          if (codexRollback.backupPath && existsSync(codexRollback.backupPath)) {
            // Atomic restore: a crash mid-copy must never leave a torn config
            // (the backup carries the previous bearer — 0600 stays forced).
            atomicWriteTextFile(codexRollback.path, readFileSync(codexRollback.backupPath, 'utf8'), { forceMode: 0o600 });
          } else if (!codexRollback.replacedPrior) {
            removeCodexHttpServerBlock(codexRollback.path, flags.name);
          }
        } finally {
          rbLock.release();
        }
        const ct = targets.find((t) => t.host === 'codex' && t.kind === 'mcp');
        if (ct) failTarget(ct, 'rolled back to the previous codex config after the failed smoke');
      } catch (e) {
        d.logError(`codex rollback failed: ${e instanceof Error ? e.message : String(e)} — re-run to converge.`);
      }
    }
    if (opencodeRollback) {
      try {
        let failNote = 'rolled back to the previous opencode config after the failed smoke';
        const rbLock = await acquireBootstrapLock(dirname(opencodeRollback.path)); // [X11] parity
        try {
          // Restore-guard: the config-dir lock was released before the smoke,
          // so a NEWER registration (another run's) may have replaced ours —
          // restoring this run's snapshot over it would clobber that newer
          // wiring. Only restore when the live file still carries the EXACT
          // text this run wrote; either way the fresh mint is revoked below.
          const current = existsSync(opencodeRollback.path)
            ? readFileSync(opencodeRollback.path, 'utf8')
            : '';
          if (current !== opencodeRollback.writtenText) {
            failNote =
              'smoke failed; opencode rollback SKIPPED — the config changed after this run wrote it ' +
              '(a newer registration exists); this run\'s fresh mint is still revoked';
            d.log(failNote + '.');
          } else if (opencodeRollback.backupPath && existsSync(opencodeRollback.backupPath)) {
            // Atomic restore (codex-lane parity): never a torn config mid-crash.
            atomicWriteTextFile(opencodeRollback.path, readFileSync(opencodeRollback.backupPath, 'utf8'), { forceMode: 0o600 });
            // Consumed — the unique backup carries the previous bearer and
            // has no consumer once restored.
            try { rmSync(opencodeRollback.backupPath, { force: true }); } catch { /* best-effort */ }
          } else if (!opencodeRollback.replacedPrior) {
            removeOpencodeMcpEntry(opencodeRollback.path, flags.name, { url });
          }
        } finally {
          rbLock.release();
        }
        const ot = targets.find((t) => t.host === 'opencode' && t.kind === 'mcp');
        if (ot) failTarget(ot, failNote);
      } catch (e) {
        d.logError(`opencode rollback failed: ${e instanceof Error ? e.message : String(e)} — re-run to converge.`);
      }
    }
    const mt = targets.find((t) => t.host === 'claude-code' && t.kind === 'mcp');
    if (claudeReplaced && oldClaudeReg) {
      await d.runner(['claude', 'mcp', 'remove', flags.name, '--scope', 'user']);
      const restore = await d.runner([
        'claude',
        ...buildClaudeMcpAddArgv({ name: flags.name, url: oldClaudeReg.url, headerToken: oldClaudeReg.token, scope: 'user' }),
      ]);
      if (mt) failTarget(mt, 'rolled back to the previous registration after the failed smoke');
      d.log(
        restore.code === 0
          ? 'previous Claude Code registration restored — existing clients stay connected.'
          : 'could not restore the previous Claude Code registration — re-run to converge.',
      );
    } else if (mt?.state === 'confirmed' && !claudeReplaced) {
      // Fresh add (nothing existed before this run): roll back to the pre-run
      // state so a failed smoke never leaves a green-looking registration
      // wired to an unverified token — mirrors the codex fresh-add branch.
      await d.runner(['claude', 'mcp', 'remove', flags.name, '--scope', 'user']);
      failTarget(mt, 'fresh registration removed after the failed smoke');
    } else if (mt?.state === 'confirmed' && claudeReplaced) {
      // Replaced a prior registration whose bearer we could not recover — the
      // old state is unrestorable, so keep the new wiring but record the
      // failed smoke honestly instead of leaving the target green.
      failTarget(
        mt,
        'smoke failed and the previous registration could not be recovered — the new registration is left in place; re-run to converge',
      );
    }
    // A freshly-added pre-approval must not outlive its rolled-back
    // registration (red-team CRITICAL): remove the entry we added this run.
    // Pre-existing entries [X8] are never touched.
    const pt = targets.find((t) => t.host === 'claude-code' && t.kind === 'permission');
    if (pt?.state === 'confirmed' && permissionAddedThisRun) {
      try {
        removePermissionsAllowEntry(pt.path!, pt.entry!);
        failTarget(pt, 'pre-approval removed after the failed smoke (its registration was rolled back)');
      } catch (e) {
        d.logError(`could not remove the pre-approval after rollback: ${e instanceof Error ? e.message : String(e)}`);
      }
    }
    // Ambient instruction blocks installed THIS run must not outlive their
    // rolled-back registrations either (codex re-review): a confirmed block
    // would keep ordering every new session to save through an endpoint that
    // failed verification — or through a foreign registration a forced
    // replacement just restored. Strip removes only OUR marker block; the
    // file itself always stays.
    for (const it of targets) {
      if (it.kind !== 'instructions' || it.state !== 'confirmed' || !it.path) continue;
      try {
        stripAmbientWritebackBlockAt(it.path);
        failTarget(it, 'instruction block removed after the failed smoke (its registration was rolled back)');
      } catch (e) {
        d.logError(`could not remove the ambient-writeback block from ${it.path} after the failed smoke: ${e instanceof Error ? e.message : String(e)}`);
        failTarget(it, 'smoke failed and the instruction block could not be removed — run `gbrain bootstrap harness --remove` to converge');
      }
    }
    // The fresh mint was sent to an endpoint that failed verification — a
    // possible impostor now holds a live credential. Retire it immediately
    // (we minted it, so the engine is reachable); the receipt keeps the id,
    // and a later revoke of an already-revoked id is a no-op.
    for (const id of new Set(Object.values(receipt.harness_tokens ?? {}).flatMap(t => t.minted && t.id ? [t.id] : []))) {
      try {
        await d.revokeById(id);
        d.log(`fresh-minted token revoked (id ${id}) — nothing live leaked to the unverified endpoint.`);
      } catch (e) {
        d.logError(
          `could not revoke the fresh-minted token (${e instanceof Error ? e.message : String(e)}) — ` +
            `revoke it manually: gbrain auth revoke with the id flag (${id}).`,
        );
      }
    }
  }

  // The unique opencode backup carries the PREVIOUS bearer; once the new
  // wiring is verified it has no consumer — unlink it so re-runs never
  // accumulate token-bearing snapshots (failed runs consume it via the
  // restore above; skipped restores leave it 0600 for manual recovery).
  if (smokeOk && opencodeRollback?.backupPath) {
    try {
      rmSync(opencodeRollback.backupPath, { force: true });
    } catch {
      /* best-effort — it is 0600 either way */
    }
  }

  // 9. [X3] Convergence cleanup — AFTER the smoke, so prior working wiring is
  // never unwired on a run that failed to establish its replacement. Cleanup
  // failures append as failed targets (blocking the rotation gate below) so
  // --remove or a re-run retries them. Runs under the config-dir lock: it
  // mutates the same user-scope files the apply loop serializes on [X11].
  if (prior && smokeOk) {
    const cfgDir = dirname(d.userSettingsPath);
    mkdirSync(cfgDir, { recursive: true });
    const cleanupLock = await acquireBootstrapLock(cfgDir);
    try {
      await cleanupStalePriorTargets(prior, receipt, d, save);
    } finally {
      cleanupLock.release();
    }
  }

  // 9b. Converge-on-off [OV-A2/OV2-2]: writeback disabled means a
  // previously-installed ambient block is a stale contract — strip it from
  // the receipt-recorded paths AND the candidate paths (an out-of-band or
  // crashed-receipt install still converges). The FILE always stays in
  // place, even when left empty of our content. Removing a stale
  // instruction block never disconnects anything, so this is not gated on
  // the smoke (unlike step 9's wiring cleanup).
  if (!wb.enabled) {
    const candidatePaths = new Set<string>([d.claudeMemoryPath, d.codexAgentsPath]);
    for (const pt of prior?.targets ?? []) {
      if (pt.kind === 'instructions' && pt.path) candidatePaths.add(pt.path);
    }
    for (const path of candidatePaths) {
      try {
        if (!existsSync(path) || !ambientBlockPresent(readFileSync(path, 'utf8'))) continue;
        const blockDir = dirname(path);
        const blockLock = await acquireBootstrapLock(blockDir);
        let r: { removed: boolean };
        try {
          r = stripAmbientWritebackBlockAt(path);
        } finally {
          blockLock.release();
        }
        if (r.removed) {
          d.log(`ambient-writeback instruction block removed from ${path} (memory.auto_writeback is off — converged).`);
        }
      } catch (e) {
        const msg = e instanceof Error ? e.message : String(e);
        d.logError(
          `could not remove the ambient-writeback block from ${path}: ${msg}`,
        );
        // Track the orphan (adversarial review, this wave): a damaged block
        // that failed to strip would otherwise vanish from the rewritten
        // receipt while STILL instructing every new session — record a
        // failed `instructions` target so --status shows it, --remove and
        // the next converge retry it, and doctor's off-branch probe warns.
        receipt.targets.push({
          host: path === d.codexAgentsPath ? 'codex' : 'claude-code',
          kind: 'instructions',
          state: 'failed',
          scope: 'user',
          path,
          mechanism: 'managed-block',
          error: `converge-off: ${msg}`,
        });
        save();
      }
    }
    // WP8 audience gate (engine-free lane, so the DECLARED file-plane
    // audience is the signal — `config set brain.audience` dual-writes it):
    // a shared-declared brain never gets the enable nudge; undeclared reads
    // as the single-operator harness default (the consent ask itself only
    // ever fires on engine-classified personal brains).
    const declaredAudience = (d.loadFileConfig()?.brain?.audience ?? '').trim().toLowerCase();
    if (declaredAudience !== 'shared') {
      d.log('ambient writeback off — enable with `gbrain config set memory.auto_writeback salient` and re-run.');
    }
  }

  // 10. Rotation completion [C7/X4]: only after all targets confirmed + the
  // token verified. EVERY carried prior id is revoked; failures stay on the
  // receipt for the next converge.
  const allConfirmed = targets.every((t) => t.state === 'confirmed');
  let skillsReady = true;
  const currentSkills = new Set<NonNullable<HarnessReceipt['shared_skills']>[number]>();
  if (smokeOk && skillsPolicy === 'follow') {
    for (const host of hosts) {
      const mcp = targets.find(t => t.host === host && t.kind === 'mcp');
      if (mcp?.state !== 'confirmed') { skillsReady = false; continue; }
      const hostToken = tokens.get(host)!;
      const owned = receipt.harness_tokens![host]!;
      let entry = flags.token === undefined ? undefined : receipt.shared_skills!.find(candidate => {
        if (candidate.host !== host || candidate.url !== url || candidate.name !== flags.name || candidate.status.startsWith('left')) return false;
        try { return readCredentials(join(candidate.root, 'credentials.json')).access_token === hostToken; } catch { return false; }
      });
      entry ??= {
        host, root: join(d.gbrainHome, 'bootstrap', 'shared-skills', host, randomUUID()),
        name: flags.name, url, ...(owned.id ? { token_id: owned.id } : {}), status: 'pending',
      };
      if (!receipt.shared_skills!.includes(entry)) receipt.shared_skills!.push(entry);
      currentSkills.add(entry);
      save();
      if (flags.token !== undefined && hosts.length > 1) {
        entry.reason = 'independent_credentials_required';
        skillsReady = false;
        d.logError('shared skills pending: a supplied token cannot enroll multiple harness identities. Connect each harness with its own explicit grant.');
        save();
        continue;
      }
      if (registrarMode && new URL(url).protocol !== 'https:') {
        entry.reason = 'secure_endpoint_required';
        skillsReady = false;
        d.logError(`shared skills (${host}): pending; use HTTPS for the remote credential handoff. Existing memory registration is unchanged.`);
        save();
        continue;
      }
      const credentials: HarnessCredentials = {
        version: 1, mcp_url: url, issuer_url: url.replace(/\/mcp$/, ''), client_id: owned.id ?? `supplied-${host}`,
        access_token: hostToken, shared_skills: { follow: true, ...(flags.source ? { source_ids: [flags.source] } : {}) },
      };
      try {
        writeCredentials(join(entry.root, 'credentials.json'), credentials);
        const result = await d.installSharedSkills(credentials, {
          harness: host, root: entry.root, name: flags.name, nativeSkillsDir: d.nativeSkillsDir(host),
        });
        entry.status = result.status;
        entry.reason = result.reason ? redactToken(result.reason, hostToken) : undefined;
        skillsReady = skillsReady && ['restart_required', 'advisory_refresh'].includes(result.status);
        d.log(redactToken(`shared skills (${host}): ${result.status}; native activation unverified. ${result.next_action ?? 'Keep using memory; verify the follow grant and server support if enrollment is pending.'}`, hostToken));
      } catch {
        entry.status = 'pending';
        entry.reason = 'shared_skills_unavailable';
        skillsReady = false;
        d.logError(`shared skills (${host}): pending; memory remains independent. Verify the explicit follow grant and private installation storage, then retry.`);
      }
      save();
    }
  }
  // #6743: per-id leave-then-revoke; a revoked credential's enrollment is inert (logic in harness-cleanup.ts).
  const cleanup = await convergeHarnessCleanup({ receipt, prior, current: currentSkills, wired: allConfirmed && smokeOk, skillsReady,
    memoryOnly: skillsPolicy === 'memory-only', leave: leaveHarnessSkills, save }, d);

  // 10b. Brain-first instructions beside each confirmed MCP entry; 10c. the same rule next to every turn where this lane wires no UserPromptSubmit hook.
  const mcpHosts = hosts.filter((h) => targets.some((t) => t.host === h && t.kind === 'mcp' && t.state === 'confirmed'));
  writeHarnessBrainFirst({ hosts: mcpHosts, server: flags.name, optOut: flags.noInstructions === true, paths: d, log: d.log });
  const turnHooks = writeHarnessTurnHooks({ hosts: mcpHosts, claudeHooksWired: wireHooks, noHooks: flags.noHooks || registrarMode, gbrainBin: d.gbrainBin, userSettingsPath: d.userSettingsPath, codexConfig: d.codexConfig, log: d.log, logError: d.logError });
  const skillsIndex = writeHarnessSkillsIndex({ hosts: mcpHosts, launcher: flags.gbrainBin ?? d.gbrainBin ?? 'gbrain', optOut: flags.noInstructions === true,
    skillLoading: flags.skillLoading, paths: d, settingsPath: d.userSettingsPath, log: d.log });
  const skillsIndexFailed = skillsIndex.some(skillsOutcomeFailed);
  if (skillsIndexFailed) d.logError('the skills index was not written as asked (see the skills line above); fix that and re-run.');

  // 11. Degradation + skew honesty.
  if (health.engine === 'postgres') {
    d.log(
      '\nNote: this brain runs on Postgres — per-turn hook injection needs a running `gbrain serve` for this ' +
        'brain (hooks heartbeat no_pglite_path/no_serve until one is up; the engine-uniform IPC listener keys its ' +
        'socket off the connection URL under ~/.gbrain/run). MCP tools are the active seam: sessions ' +
        'search/read/write the brain on demand; the pre-wired hooks light up whenever a serve runs.',
    );
  }
  if (health.version && flags.token === undefined && isServeOlderThanScopes(health.version)) {
    d.log(
      `\nNote: serve v${health.version} predates token scoping — this token verifies as FULL-ACCESS until you ` +
        'restart `gbrain serve` on this binary version.',
    );
  }

  const pendingFix = verifyPending && allConfirmed && !smokeOk ? finishPendingVerify(receipt, save, flags.raw, url, unpinnedHooks || flags.source ? null : hookSource, d) : null;
  if (flags.json) {
    emitJson(
      JSON.stringify(
        {
          schema_version: 1, ...harnessOutcomeFields(pendingFix, allConfirmed && smokeOk && !skillsIndexFailed),
          ...cleanupOutcomeFields(cleanup, !pendingFix && allConfirmed && smokeOk, flags.raw),
          url,
          engine: health.engine ?? null,
          serve_version: health.version ?? null,
          token_name: receipt.token.name,
          token_redacted: true,
          targets: receipt.targets,
          skills_policy: receipt.skills_policy,
          shared_skills: receipt.shared_skills,
          degraded_per_turn: health.engine === 'postgres',
          smoke_ok: smokeOk,
          skills_index: skillsIndex,
          receipt_path: harnessReceiptPath(d.gbrainHome),
          turn_hooks: turnHooks.results,
        },
        null,
        2,
      ),
    );
  }
  const code = pendingFix ? HARNESS_PENDING_VERIFY_EXIT_CODE : allConfirmed && smokeOk && turnHooks.ok ? (cleanup.length ? HARNESS_CLEANUP_PENDING_EXIT_CODE : 0) : 1;
  return code === 0 && skillsIndexFailed ? 1 : code;
}

// ── Remove [C9/F2/C8] ───────────────────────────────────────────────────────

export async function removeHarness(flags: HarnessFlags, rawDeps: HarnessDeps): Promise<number> {
  const d = resolveHarnessDeps(rawDeps);
  const state = readHarnessReceiptState(d.gbrainHome);
  if (state.state === 'absent') {
    d.log('nothing harness-installed on this machine (no harness receipt).');
    return 0;
  }
  if (state.state === 'newer') {
    d.logError('the harness receipt was written by a newer gbrain — upgrade gbrain before removing.');
    return 1;
  }
  if (state.state === 'invalid') {
    d.logError(
      `the harness receipt at ${harnessReceiptPath(d.gbrainHome)} is unreadable — fix or delete it, then ` +
        'remove any stragglers by hand (claude mcp remove / the codex config block / hook entries).',
    );
    return 1;
  }
  const receipt = state.receipt;
  if (flags.dryRun) return previewHarnessRemoval(receipt, { ...d, gbrainBin: flags.gbrainBin ?? d.gbrainBin });
  const save = () => writeHarnessReceipt(d.gbrainHome, receipt);
  let anyFailed = false;
  let skillsDone = true;
  for (const entry of receipt.shared_skills ?? []) {
    if (!(await leaveHarnessSkills(entry, d))) skillsDone = false;
    save();
  }

  // Phase 1 — host removals (engine-free). Under the SAME config-dir lock the
  // apply loop takes [X11]: a remove racing an apply from another GBRAIN_HOME
  // must not lose the apply's just-written entry via read-modify-write
  // interleave. (Lock order everywhere is config-dir → codex-dir.)
  const rmCfgDir = dirname(d.userSettingsPath);
  mkdirSync(rmCfgDir, { recursive: true });
  const rmCfgLock = await acquireBootstrapLock(rmCfgDir);
  const remaining: HarnessTarget[] = [];
  try {
  for (const t of receipt.targets) {
    try {
      if (t.kind === 'instructions') {
        // Ambient-writeback managed block: strip it wherever the receipt
        // recorded it (any host). Damaged markers throw → the target stays
        // failed on the receipt for a hand-fix + retry.
        if (!t.path || !existsSync(t.path)) {
          d.log(`no ambient-writeback block file at ${t.path ?? '(no path recorded)'} — counted as removed.`);
        } else {
          const blockDir = dirname(t.path);
          const blockLock = resolve(blockDir) === resolve(rmCfgDir) ? null : await acquireBootstrapLock(blockDir);
          let r: { removed: boolean };
          try {
            r = stripAmbientWritebackBlockAt(t.path);
          } finally {
            blockLock?.release();
          }
          d.log(
            r.removed
              ? `ambient-writeback instruction block removed from ${t.path}.`
              : `no ambient-writeback block in ${t.path} — counted as removed.`,
          );
        }
      } else if (t.host === 'claude-code' && t.kind === 'mcp') {
        // [C8] Only remove what points at OUR url.
        const get = await d.runner(['claude', 'mcp', 'get', t.name ?? 'gbrain']);
        if (get.code !== 0 || !parseClaudeMcpGetUrl(`${get.stdout}\n${get.stderr}`).found) {
          d.log(`MCP '${t.name}' already gone — counted as removed.`); // [F2]
          continue;
        }
        const info = parseClaudeMcpGetUrl(`${get.stdout}\n${get.stderr}`);
        if (info.url && info.url !== receipt.url) {
          d.log(
            `MCP '${t.name}' now points at ${info.url} (not ours) — owned by another install; skipping, ` +
              'cleared from the receipt.',
          );
          continue;
        }
        if (!info.url) {
          // Refuse-rather-than-guess [C8]: no URL parsed means ownership is
          // unprovable (a claude CLI output-format change would otherwise turn
          // every remove into deleting other brains' registrations).
          d.log(
            `MCP '${t.name}' exists but its URL could not be verified against the receipt — left in place; ` +
              `remove it manually if it is this brain's: claude mcp remove ${t.name ?? 'gbrain'} --scope ${t.scope}`,
          );
          continue;
        }
        const rm = await d.runner(['claude', 'mcp', 'remove', t.name ?? 'gbrain', '--scope', t.scope]);
        if (rm.code !== 0 && !/not found|No MCP server/i.test(rm.stdout + rm.stderr)) {
          throw new Error(rm.stderr.trim() || `exit ${rm.code}`);
        }
        d.log(`MCP '${t.name}' removed from Claude Code (${t.scope} scope).`);
      } else if (t.host === 'claude-code' && t.kind === 'permission') {
        if (t.mechanism === 'pre-existing') {
          // [X8] The entry was allowed before us — never delete what we
          // didn't add. Left in place, cleared from the receipt.
          d.log(`permissions.allow entry '${t.entry}' predates the harness install — left in place.`);
          continue;
        }
        const r = removePermissionsAllowEntry(t.path!, t.entry!);
        if (r.notes.some((n) => n.startsWith('WARNING'))) throw new Error(r.notes.join('; '));
        d.log(
          r.removed && r.removed > 0
            ? `permissions.allow entry '${t.entry}' removed.`
            : `permissions.allow entry '${t.entry}' already gone — counted as removed.`,
        );
      } else if (t.host === 'claude-code' && t.kind === 'hooks') {
        removeHarnessHooksTarget(t, receipt, { ...d, gbrainBin: flags.gbrainBin ?? d.gbrainBin });
      } else if (t.host === 'codex') {
        const codexPath = t.path ?? d.codexConfig;
        const codexDir = dirname(codexPath);
        mkdirSync(codexDir, { recursive: true });
        // [X11] parity — but the phase-1 config-dir lock may already cover
        // this dir (same-parent layouts): the lock is non-reentrant.
        const codexLock = resolve(codexDir) === resolve(rmCfgDir) ? null : await acquireBootstrapLock(codexDir);
        let r: ReturnType<typeof removeCodexHttpServerBlock>;
        try {
          r = removeCodexHttpServerBlock(codexPath, t.name ?? 'gbrain');
        } finally {
          codexLock?.release();
        }
        d.log(
          r.removed
            ? `Codex managed block removed from ${codexPath}.`
            : `no managed block in ${codexPath} — counted as removed.`,
        );
        const hr = removeCodexHooks({ configPath: codexPath, hooksPath: join(dirname(codexPath), 'hooks.json') });
        if (hr.removed) d.log(`Codex SessionEnd hook + trust entry removed (${hr.hooksPath}).`);
        for (const note of hr.notes) d.logError(note);
      } else if (t.host === 'opencode') {
        const ocPath = t.path ?? d.opencodeConfig;
        // [C8] Ownership before removal: an entry now at a DIFFERENT url is
        // another install's — skip with a note, cleared from the receipt
        // (mirror of the claude not-ours branch; the module's foreign check
        // would THROW, which reads as a failure rather than a skip).
        let kind: ReturnType<typeof opencodeEntryKind> = 'absent';
        if (existsSync(ocPath)) {
          try {
            kind = opencodeEntryKind(
              parseOpencodeConfig(readFileSync(ocPath, 'utf8'), ocPath),
              t.name ?? 'gbrain',
              { url: receipt.url },
            );
          } catch (e) {
            throw new Error(`opencode config unreadable: ${e instanceof Error ? e.message : String(e)}`);
          }
        }
        if (kind === 'absent') {
          d.log(`opencode entry '${t.name}' already gone — counted as removed.`); // [F2]
        } else if (kind !== 'ours-same-source') {
          d.log(
            `opencode entry '${t.name}' does not match this receipt's url (${receipt.url}) — owned by another ` +
              'install; skipping, cleared from the receipt.',
          );
        } else {
          const ocDir = dirname(ocPath);
          mkdirSync(ocDir, { recursive: true });
          const ocLock = resolve(ocDir) === resolve(rmCfgDir) ? null : await acquireBootstrapLock(ocDir);
          let r: ReturnType<typeof removeOpencodeMcpEntry>;
          try {
            r = removeOpencodeMcpEntry(ocPath, t.name ?? 'gbrain', { url: receipt.url });
          } finally {
            ocLock?.release();
          }
          d.log(
            r.removed
              ? `opencode managed entry removed from ${ocPath}.`
              : `no managed entry in ${ocPath} — counted as removed.`,
          );
        }
      }
    } catch (e) {
      anyFailed = true;
      t.state = 'failed';
      t.error = e instanceof Error ? e.message : String(e);
      remaining.push(t);
      d.logError(`could not remove ${t.host}/${t.kind}: ${t.error}`);
    }
  }
  } finally {
    rmCfgLock.release();
  }
  receipt.targets = remaining;
  save();

  // Phase 2 — revoke EVERY minted id we own [C7/X4]: the current token (when
  // minted) plus any carried previous_ids from unconverged rotations.
  // Deferred under a live PGLite serve [C9].
  const skillsPendingIds = new Set((receipt.shared_skills ?? []).filter(e => !e.status.startsWith('left')).map(e => e.token_id));
  const idsToRevoke = [...new Set([
    ...(receipt.token.minted && receipt.token.id ? [receipt.token.id] : []),
    ...(receipt.token.previous_ids ?? []),
    ...Object.values(receipt.harness_tokens ?? {}).flatMap(t => t.minted && t.id ? [t.id] : []),
  ])];
  let tokenDone = idsToRevoke.length === 0;
  if (!tokenDone) {
    if (d.pgliteLiveServe()) {
      d.logError(
        'a live `gbrain serve` holds this PGLite brain — token(s) NOT revoked. Host wiring is removed; ' +
          `stop the serve and re-run \`gbrain bootstrap harness --remove\`, or run ` +
          `\`gbrain auth revoke\` with the id flag per id (${idsToRevoke.join(', ')}).`,
      );
    } else {
      const unrevoked: string[] = [];
      for (const id of idsToRevoke) {
        if (skillsPendingIds.has(id)) { unrevoked.push(id); continue; }
        try {
          await d.revokeById(id);
          for (const t of Object.values(receipt.harness_tokens ?? {})) if (t.id === id) delete t.id;
          d.log(`harness token revoked (id ${id}).`);
        } catch (e) {
          unrevoked.push(id);
          d.logError(
            `token revoke failed (${e instanceof Error ? e.message : String(e)}) — ` +
              `run \`gbrain auth revoke\` with the id flag (${id}) manually.`,
          );
        }
      }
      if (unrevoked.length === 0) {
        tokenDone = true;
      } else {
        const stillCurrent = receipt.token.id !== undefined && unrevoked.includes(receipt.token.id);
        receipt.token.previous_ids = unrevoked.filter((id) => id !== receipt.token.id);
        if (receipt.token.previous_ids.length === 0) delete receipt.token.previous_ids;
        if (!stillCurrent) delete receipt.token.id;
      }
    }
  }
  if (!receipt.token.minted && (receipt.token.previous_ids?.length ?? 0) === 0) {
    d.log('current token was supplied via --token — not revoked (not ours to revoke).');
  }

  removeHarnessBrainFirst(flags.name, d.log);
  removeHarnessTurnHooks({ userSettingsPath: d.userSettingsPath, codexConfig: d.codexConfig, log: d.log });
  const skillsIndexDone = !removeHarnessSkillsIndex(flags.name, d.log).some(skillsOutcomeFailed);

  if (remaining.length === 0 && tokenDone && skillsDone && skillsIndexDone) {
    deleteHarnessReceipt(d.gbrainHome);
    d.log('harness wiring fully removed; receipt consumed.');
    return 0;
  }
  save();
  d.logError('some removals are pending — the receipt keeps exactly the unfinished parts (re-run to retry).');
  return 1;
}

// ── Status (read-only; no lockstep with apply — probes the live truth) ─────

/** Parse the bearer token back out of `claude mcp get` output (live-verified
 * shape: `Authorization: Bearer <tok>` under a Headers: section). NEVER echo
 * the raw output anywhere — redactToken everything user-visible. */
export function parseClaudeMcpGetBearer(out: string): string | null {
  const m = out.match(/Authorization:\s*Bearer\s+(\S+)/);
  return m ? m[1] : null;
}

/** Parse the bearer token out of OUR managed codex block. When
 * `expectedUrl` is given, the block's `url` must match it ([C8] parity with
 * the claude-lane recovery): a hand-edited block pointing at another brain's
 * serve carries a credential that must never be transmitted to receipt.url.
 * Reads the current `http_headers = { Authorization = "Bearer <t>" }` shape
 * (#4574 — codex-cli >=0.149 rejects inline `bearer_token`), with a legacy
 * `bearer_token = "<t>"` fallback so machines wired by older gbrain still
 * have their token recovered for status/rotation. */
export function parseCodexBlockBearer(configText: string, expectedUrl?: string): string | null {
  const norm = configText.replace(/\r\n/g, '\n');
  // The shared writer constants — inline copies here would silently stop
  // matching if host-specs.ts ever rewords the markers.
  const begin = norm.indexOf(CODEX_TOML_BLOCK_BEGIN);
  const end = norm.indexOf(CODEX_TOML_BLOCK_END);
  if (begin < 0 || end < 0 || end < begin) return null;
  const block = norm.slice(begin, end);
  if (expectedUrl !== undefined) {
    const u = block.match(/^url\s*=\s*"((?:[^"\\]|\\.)*)"\s*$/m);
    if (!u || u[1].replace(/\\(.)/g, '$1') !== expectedUrl) return null;
  }
  const h = block.match(/^http_headers\s*=\s*\{\s*Authorization\s*=\s*"((?:[^"\\]|\\.)*)"\s*\}\s*$/m);
  if (h) {
    const value = h[1].replace(/\\(.)/g, '$1');
    // A non-Bearer Authorization header is a hand-edit — not ours to recover.
    return value.startsWith('Bearer ') ? value.slice('Bearer '.length) : null;
  }
  const m = block.match(/^bearer_token\s*=\s*"((?:[^"\\]|\\.)*)"\s*$/m);
  if (!m) return null;
  return m[1].replace(/\\(.)/g, '$1');
}

/** `bootstrap harness --status [--json]` — one screen of live health. */
export async function statusHarness(flags: HarnessFlags, rawDeps: HarnessDeps): Promise<number> {
  const d = resolveHarnessDeps(rawDeps);
  const state = readHarnessReceiptState(d.gbrainHome);
  if (state.state === 'absent') {
    if (flags.json) {
      d.log(JSON.stringify({ schema_version: 1, installed: false }, null, 2));
      return 2; // cron contract: absence is distinguishable under --json
    }
    d.log('no harness install on this machine (no harness receipt).');
    return 0;
  }
  if (state.state !== 'ok') {
    d.logError(`harness receipt unreadable (${state.state}) — see ${harnessReceiptPath(d.gbrainHome)}`);
    return 1;
  }
  const receipt = state.receipt;

  const health = await probeServeHealth(receipt.url, d.fetchFn);
  const serveLine = health.ok
    ? `serve: OK at ${receipt.url} (engine ${health.engine ?? '?'}, v${health.version ?? '?'})`
    : `serve: UNREACHABLE at ${receipt.url} (${health.detail ?? 'no response'})`;

  // Token liveness — the receipt stores no plaintext by design [F1]; recover
  // from the host registration or degrade honestly.
  let token: string | null = null;
  let tokenSource = '';
  // #4586: the [C8] ownership probe doubles as the LIVE verdict for the
  // claude-code mcp target. Positive evidence only — a URL that is not ours,
  // or a non-HTTP transport at OUR (user) scope — flips the displayed state
  // to 'failed'; not-found / unparseable stays the receipt's honest degrade.
  // Status is read-only: the receipt itself is never rewritten here.
  let claudeLiveError: string | null = null;
  const claudeMcp = receipt.targets.find((t) => t.host === 'claude-code' && t.kind === 'mcp');
  if (claudeMcp) {
    try {
      const get = await d.runner(['claude', 'mcp', 'get', claudeMcp.name ?? 'gbrain']);
      if (get.code === 0) {
        const out = `${get.stdout}\n${get.stderr}`;
        // [C8] Ownership before recovery (red-team CRITICAL): if another
        // install has taken the name over, the parsed bearer is a FOREIGN
        // credential — recovering it here would transmit it to receipt.url,
        // a host it was never issued for. Only a URL match makes it ours.
        const info = parseClaudeMcpGetUrl(out);
        if (info.found && info.url === receipt.url) {
          token = parseClaudeMcpGetBearer(out);
          if (token) tokenSource = 'claude registration';
        } else if (info.found && info.url) {
          claudeLiveError =
            `registration now points at ${info.url}, not ${receipt.url} — owned by another install; ` +
            're-run `gbrain bootstrap harness --force` to reclaim, or --remove';
        } else if (info.found) {
          // No URL line: a stdio (or other non-HTTP) launch. Only a same-scope
          // entry is a replacement; a project-scope one merely shadows ours
          // from that cwd, which re-running the harness cannot undo.
          const type = out.match(/^\s*Type:\s*(\S+)/m)?.[1];
          if (type && type.toLowerCase() !== 'http' && /^\s*Scope:\s*User\b/im.test(out)) {
            claudeLiveError =
              `registration at user scope is now a ${type} serve (a \`claude mcp add\` or ` +
              '`bootstrap hooks --scope user` replaced the HTTP wiring) — re-run `gbrain bootstrap harness` to reclaim';
          }
        }
      }
    } catch {
      /* degrade */
    }
  }
  const liveTargets = receipt.targets.map((t) =>
    t === claudeMcp && claudeLiveError ? { ...t, state: 'failed' as const, error: claudeLiveError } : t,
  );
  if (!token) {
    const codexMcp = receipt.targets.find((t) => t.host === 'codex' && t.kind === 'mcp');
    if (codexMcp?.path && existsSync(codexMcp.path)) {
      try {
        token = parseCodexBlockBearer(readFileSync(codexMcp.path, 'utf8'), receipt.url);
        if (token) tokenSource = 'codex config block';
      } catch {
        /* degrade */
      }
    }
  }
  if (!token) {
    const ocMcp = receipt.targets.find((t) => t.host === 'opencode' && t.kind === 'mcp');
    if (ocMcp?.path) {
      // [C8] url-matched inside the helper: a foreign/rotated entry's bearer
      // is never recovered (it was not issued for receipt.url).
      token = parseOpencodeEntryBearer(ocMcp.path, ocMcp.name ?? 'gbrain', receipt.url);
      if (token) tokenSource = 'opencode config entry';
    }
  }

  let tokenLine: string;
  let tokenVerified: boolean | 'unavailable' = 'unavailable';
  if (!health.ok) {
    tokenLine = 'token: not verified (serve unreachable)';
  } else if (token) {
    const smoke = await d.probeIdentity(receipt.url, token);
    // [X10] An unknown-tool tool_error means auth + dispatch succeeded — a
    // narrowed --surface (e.g. verbs) is verified, not broken.
    tokenVerified = smoke.ok || smoke.reason === 'tool_error';
    tokenLine = smoke.ok
      ? `token: OK ('${receipt.token.name}' via ${tokenSource} — ${smoke.identity})`
      : smoke.reason === 'tool_error'
        ? `token: OK ('${receipt.token.name}' via ${tokenSource} — authenticated; get_brain_identity ` +
          'unavailable, the serve likely runs a narrowed --surface)'
        : `token: FAILED (${smoke.reason}) — ${redactToken(smoke.message, token)}. ` +
          'Someone may have revoked it; re-run `gbrain bootstrap harness` to rotate.';
  } else {
    tokenLine = `token: verify unavailable (no registration to recover the bearer from) — honest degrade, not a failure.`;
  }
  const harnessTokenStatus: Array<{ host: HarnessTarget['host']; verified: boolean }> = [];
  if (health.ok && Object.keys(receipt.harness_tokens ?? {}).length > 1) {
    for (const target of receipt.targets.filter(t => t.kind === 'mcp')) {
      let bearer: string | null = null;
      try {
        if (target.host === 'claude-code') {
          const result = await d.runner(['claude', 'mcp', 'get', target.name ?? 'gbrain']);
          const text = `${result.stdout}\n${result.stderr}`;
          if (result.code === 0 && parseClaudeMcpGetUrl(text).url === receipt.url) bearer = parseClaudeMcpGetBearer(text);
        } else if (target.host === 'codex' && target.path && codexBlockOwnsName(target.path, target.name ?? 'gbrain')) {
          bearer = parseCodexBlockBearer(readFileSync(target.path, 'utf8'), receipt.url);
        } else if (target.host === 'opencode' && target.path) {
          bearer = parseOpencodeEntryBearer(target.path, target.name ?? 'gbrain', receipt.url);
        }
        const result = bearer ? await d.probeIdentity(receipt.url, bearer) : null;
        harnessTokenStatus.push({ host: target.host, verified: !!result && (result.ok || result.reason === 'tool_error') });
      } catch { harnessTokenStatus.push({ host: target.host, verified: false }); }
    }
    if (harnessTokenStatus.some(status => !status.verified)) {
      if (tokenVerified !== false) tokenLine = 'token: FAILED — at least one independent harness credential is missing or could not authenticate; re-run to converge.';
      tokenVerified = false;
    }
  }

  const skew =
    health.ok && health.version && isServeOlderThanScopes(health.version)
      ? `serve v${health.version} predates token scoping — the token verifies as FULL-ACCESS until the serve restarts on this version.`
      : null;

  const degraded = (health.engine ?? receipt.engine) === 'postgres';

  // Ambient-writeback block probes (kind === 'instructions'): live sentinel
  // presence, plus the [OV-A4] codex exclusivity file — an install shadowed
  // by AGENTS.override.md must never read as healthy.
  const instructionsProbes = receipt.targets
    .filter((t) => t.kind === 'instructions')
    .map((t) => {
      let probe: 'installed' | 'missing' | 'override-blocked' | 'unreadable' = 'missing';
      try {
        if (t.host === 'codex' && existsSync(d.codexAgentsOverride)) {
          probe = 'override-blocked';
        } else if (
          t.path &&
          existsSync(t.path) &&
          // The ONE probe vocabulary (instructions-block.ts) so status,
          // converge, and doctor classify a damaged-marker file identically.
          probeAmbientBlock(readFileSync(t.path, 'utf8')).state === 'present'
        ) {
          probe = 'installed';
        }
      } catch {
        probe = 'unreadable';
      }
      return { host: t.host, path: t.path ?? null, probe };
    });
  const instructionsOk = instructionsProbes.every((p) => p.probe === 'installed');
  const hookCarriers = harnessHookCarrierStatus(receipt, d);
  // Cron contract: 0 means ALL-VERIFIED (or honest degrades only) — a
  // crashed apply's pending/failed targets are NOT success just because
  // /health answers (ship-review P2); an unconverged rotation or shared-skills
  // cleanup exits bootstrap_cleanup_pending (#6743). The
  // token-unrecoverable honest degrade stays 0 per the documented contract.
  const allTargetsConfirmed = liveTargets.every((t) => t.state === 'confirmed');
  // Half-removed state (red-team CRITICAL): --remove under a live PGLite
  // serve strips every host target but defers the revoke, leaving a
  // zero-target receipt whose minted token is STILL ACTIVE. Vacuous
  // every() would read that as green forever.
  const removalPending = receipt.targets.length === 0 && ((receipt.token.minted && receipt.token.id !== undefined) ||
    Object.values(receipt.harness_tokens ?? {}).some(t => t.minted && t.id) ||
    (receipt.shared_skills ?? []).some(entry => !entry.status.startsWith('left')));
  const statusOk = health.ok && tokenVerified !== false && allTargetsConfirmed && !removalPending && instructionsOk && !receipt.verify_pending;
  const cleanup = await harnessCleanupReport(receipt, d.tokenStates);

  if (flags.json) {
    d.log(
      JSON.stringify(
        {
          schema_version: 1,
          installed: true,
          url: receipt.url,
          serve_ok: health.ok,
          engine: health.engine ?? receipt.engine ?? null,
          serve_version: health.version ?? null,
          version_skew: skew !== null,
          token_name: receipt.token.name,
          token_verified: tokenVerified,
          harness_tokens: harnessTokenStatus,
          skills_policy: receipt.skills_policy ?? 'memory-only',
          shared_skills: receipt.shared_skills ?? [],
          degraded_per_turn: degraded,
          targets: liveTargets,
          ...(instructionsProbes.length > 0 ? { instructions_blocks: instructionsProbes } : {}),
          ...(hookCarriers.length > 0 ? { hook_carriers: hookCarriers } : {}),
          pending_previous_tokens: receipt.token.previous_ids ?? [],
          ...(receipt.verify_pending ? { status: 'partial', verify_pending: receipt.verify_pending } : {}),
          ...cleanupOutcomeFields(cleanup, statusOk, null),
          receipt_path: harnessReceiptPath(d.gbrainHome),
        },
        null,
        2,
      ),
    );
  } else {
    d.log(serveLine);
    d.log(tokenLine);
    const superseded = receipt.shared_skills?.length ? await d.supersededEnrollments(receipt).catch(() => null) : [];
    for (const entry of receipt.shared_skills ?? []) {
      const local = localEnrollment(entry.root);
      const stale = superseded?.find(s => s.host === entry.host && s.installation_id === local?.installation_id);
      const epochHint = superseded === null
        ? ` (if the brain reports a newer enrollment epoch: ${SKILLS_REFRESH_COMMAND})`
        : stale ? `; enrollment superseded (server epoch ${stale.server_epoch}${stale.active ? '' : ', inactive'}): ${SKILLS_REFRESH_COMMAND}` : '';
      d.log(`  shared skills (${entry.host}): ${entry.status}${entry.reason ? ` — ${entry.reason}` : ''}${local ? `; enrollment epoch ${local.enrollment_epoch}` : ''}; receipt evidence only, native activation unverified${epochHint}.`);
      if (entry.retained_files?.length) d.log(`    edited files retained: ${entry.retained_files.join(', ')}`);
    }
    for (const t of liveTargets) {
      d.log(`  ${t.host}/${t.kind} (${t.scope}): ${t.state}${t.error ? ` — ${t.error}` : ''}`);
    }
    for (const p of instructionsProbes) {
      d.log(
        `  ambient-writeback block (${p.host}): ${p.probe}${p.path ? ` — ${p.path}` : ''}` +
          (p.probe === 'override-blocked'
            ? ` (codex ignores AGENTS.md while ${d.codexAgentsOverride} exists — fold the block in there or remove the override and re-run)`
            : ''),
      );
    }
    for (const c of hookCarriers) {
      d.log(`  hook entries in ${c.path}: ${c.state === 'ok' ? `${c.ours} gbrain (${c.unmarked} without the _gbrain marker)` : c.state}` +
        `${c.duplicates.length ? `; duplicated: ${c.duplicates.join(', ')}` : ''}${c.unowned.length ? `; not this install's (left in place): ${c.unowned.join(', ')}` : ''}`);
    }
    for (const line of cleanupLines(cleanup)) d.log(line);
    if (receipt.verify_pending) d.log(pendingVerifyStatusLine(receipt.verify_pending));
    if (degraded) {
      d.log('per-turn injection: needs a running gbrain serve on Postgres (MCP tools are the active seam).');
    }
    if (skew) d.log(`note: ${skew}`);
  }
  if (removalPending) {
    d.logError(
      `removal pending: host wiring is gone but token revocation or shared-skills cleanup is unfinished — ` +
        'stop the serve and re-run `gbrain bootstrap harness --remove`, or revoke it with `gbrain auth revoke` and the id flag.',
    );
  }
  return statusOk ? (cleanup.length ? HARNESS_CLEANUP_PENDING_EXIT_CODE : 0) : 1;
}

// ── Home preflight ──────────────────────────────────────────────────────────

/** Ensure the gbrain home exists before locking in it (the bootstrap lock's
 * missing-dir message says "workspace directory", which would mislead here). */
export function ensureHarnessHome(home: string): void {
  mkdirSync(join(home, 'bootstrap'), { recursive: true });
}

/** True when the codex config carries OUR managed block for `name` — the
 * stdio lane (runHooks) must not fight the harness lane for the same server
 * name (one owner per name; `codex mcp remove` drops comments). */
export function codexBlockOwnsName(configPath: string, name: string): boolean {
  if (!existsSync(configPath)) return false;
  try {
    const text = readFileSync(configPath, 'utf8').replace(/\r\n/g, '\n');
    const begin = text.indexOf(CODEX_TOML_BLOCK_BEGIN);
    const end = text.indexOf(CODEX_TOML_BLOCK_END);
    if (begin < 0 || end < 0 || end < begin) return false;
    // Ownership means the table header sits INSIDE our managed block — a
    // foreign `[mcp_servers.<name>]` elsewhere in the file must not make the
    // stdio lane defer to us.
    return text.slice(begin, end).includes(`[mcp_servers.${name}]`);
  } catch {
    return false;
  }
}

export {
  claudeAnyRegistrationExists,
  claudePluginProvidesName,
  codexAnyRegistrationExists,
  codexPluginProvidesName,
} from './plugin-lanes.ts';