Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* 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';