Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Claude Code wiring for `gbrain setup claude-code`: the MCP entry in
* Claude Code's own config (`~/.claude.json`, user scope, or that file's
* `projects[<dir>]` block for project scope) and the hook entries in its
* settings file, owned by exact hash through a connection receipt.
*
* The receipt is the connection receipt `gbrain connect --install` already
* writes next to the harness config (`.gbrain-connection-claude-code-<name>.json`,
* `entry_hash` / `pending_entry_hash`, `status: prepared | installed`), with a
* `connection: 'local-stdio'` marker and the hook hashes added. A hosted
* receipt (it carries `client_id`) is never adopted.
*
* Write order, each step idempotent and resumable from the receipt:
* 1. receipt `prepared`: consent decisions plus the pending MCP and hook hashes
* 2. MCP entry, then the receipt records its hash
* 3. hook entries, then the receipt records their hashes
* 4. receipt `installed`
* A crash after any step leaves pending hashes that the next run treats as
* owned, so a resume never duplicates an entry. An entry whose hash the
* receipt did not record is never replaced or removed.
*/
import { createHash } from 'node:crypto';
import { existsSync, readFileSync, unlinkSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { atomicWriteTextFile } from '../bootstrap/atomic-write.ts';
import { ownedEntryFingerprint } from '../bootstrap/adopted-connections.ts';
import { acquireBootstrapLock } from '../bootstrap/lock.ts';
import { buildClaudeHookCommand, classifyHarnessHook, hookEntryHash, removeClaudeHooksAt, writeClaudeHooksAt } from '../bootstrap/hooks.ts';
import {
CLAUDE_HOOK_DEFAULT_TIMEOUT_SECS,
CLAUDE_HOOK_EVENTS,
CLAUDE_SETTINGS_FILE_RELPATH,
GBRAIN_HOOK_MARKER_KEY,
GBRAIN_SETUP_MARKER_VALUE,
claudeUserMcpConfigPath,
claudeUserSettingsPath,
type ClaudeHookEvent,
} from '../bootstrap/host-specs.ts';
import { stdioServeArgv } from '../mcp-registration.ts';
import { withStdioMember } from '../stdio-member-flag.ts';
import { isTurnRuleEntry } from './turn-hook.ts';
import { isSkillResolverEntry } from './skill-resolver-lane.ts';
import { ensureHookLauncher, hookLauncherPath } from './hook-launcher.ts';
import type { McpSurface } from '../../mcp/surface.ts';
export type WiringScope = 'user' | 'project';
export type DecisionSource = 'flag' | 'default' | 'prior' | 'opt_out';
export interface Decision<T> { value: T; source: DecisionSource; note?: string }
/** The three setup decisions, recorded separately (D8). */
export interface SetupConsent {
wiring_scope: Decision<{ scope: WiringScope; hooks: 'read-context' | 'none' }>;
capture: Decision<'accepted' | 'declined'>;
providers: Decision<'accepted' | 'declined'>;
}
type HookHashes = Partial<Record<ClaudeHookEvent, string>>;
export interface ClaudeSetupReceipt {
harness: 'claude-code';
connection: 'local-stdio';
setup_receipt_version: 1;
status: 'prepared' | 'installed' | 'removed';
name: string;
gbrain_home: string;
launcher: string;
scope: WiringScope;
project_dir?: string;
source_id: string | null;
surface: McpSurface;
/** The registration's `--advertise` (absent: tools/list shows the whole surface). */
advertise?: McpSurface;
config_path: string;
entry_hash: string | null;
pending_entry_hash: string | null;
/** The entry existed byte-identical before setup ran; `--remove` keeps it. */
mcp_adopted?: boolean;
/** The gbrain plugin serves the MCP name; setup wrote no MCP entry. */
mcp_plugin?: string;
hooks: { settings_path: string; owned: HookHashes; pending: HookHashes; edited: HookHashes };
consent: SetupConsent & { recorded_at: string };
brain_created_by_setup: boolean;
native_harness_verified: false;
created_at: string;
updated_at: string;
}
export interface ClaudeSetupPlan {
name: string;
scope: WiringScope;
projectDir?: string;
launcher: string;
/** `configDir()` of the install: the receipt's identity. */
brainHome: string;
/** GBRAIN_HOME as set in this environment, rendered into the entry and the hooks. */
gbrainHomeEnv?: string;
sourceId: string | null;
surface: McpSurface;
/** `serve --advertise`; null lists the whole surface. */
advertise: McpSurface | null;
events: ClaudeHookEvent[];
/** GST-363: `serve --stdio-member`: this entry's sessions read as that member. Only a named --stdio-member or the entry setup already wrote sets it. */
stdioMember?: string;
}
export interface SetupStep { step: 'brain' | 'receipt' | 'mcp' | 'hooks'; action: 'write' | 'keep' | 'skip' | 'remove' | 'preserve'; detail: string }
export interface ClaudeInspection {
configPath: string;
settingsPath: string;
receiptPath: string;
prior: ClaudeSetupReceipt | null;
/** A hosted `gbrain connect --install` receipt sits at this name. */
hostedReceipt: { mcp_url?: string } | null;
/** stdioMember: the --stdio-member of an entry setup owns (current or owned), which a rewrite carries forward. */
mcp: { state: 'absent' | 'current' | 'owned' | 'remote' | 'unowned'; url?: string; stdioMember?: string };
/** Events wired by another gbrain lane in this settings file. */
otherLaneEvents: string[];
/** Owned events whose entry the user edited: preserved, never rewritten. */
edited: HookHashes;
/** True when the desired hooks are present and nothing owned is stale. */
hooksCurrent: boolean;
}
export const entryHash = ownedEntryFingerprint;
export function claudeSetupPaths(plan: Pick<ClaudeSetupPlan, 'name' | 'scope' | 'projectDir'>): { configPath: string; settingsPath: string; receiptPath: string } {
const configPath = claudeUserMcpConfigPath();
const suffix = plan.scope === 'project' ? `-project-${createHash('sha256').update(plan.projectDir!).digest('hex').slice(0, 12)}` : '';
return {
configPath,
settingsPath: plan.scope === 'project' ? join(plan.projectDir!, CLAUDE_SETTINGS_FILE_RELPATH) : claudeUserSettingsPath(),
receiptPath: join(dirname(configPath), `.gbrain-connection-claude-code-${plan.name}${suffix}.json`),
};
}
function readJsonObject(path: string): Record<string, unknown> {
if (!existsSync(path)) return {};
const text = readFileSync(path, 'utf8');
if (text.trim() === '') return {};
let parsed: unknown;
try { parsed = JSON.parse(text); } catch (e) {
throw new Error(`${path} is not valid JSON (${(e as Error).message}); setup never rewrites a file it cannot parse. Fix it by hand, then run setup again.`);
}
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error(`${path} is not a JSON object; setup never rewrites a file it cannot parse.`);
return parsed as Record<string, unknown>;
}
export function readSetupReceipt(receiptPath: string): { setup: ClaudeSetupReceipt | null; hosted: { mcp_url?: string } | null } {
if (!existsSync(receiptPath)) return { setup: null, hosted: null };
let raw: Record<string, unknown>;
try { raw = readJsonObject(receiptPath); } catch { throw new Error(`the connection receipt ${receiptPath} is unreadable; move it aside only if you know which install wrote it, then run setup again.`); }
if (raw.client_id) return { setup: null, hosted: { mcp_url: typeof raw.mcp_url === 'string' ? raw.mcp_url : undefined } };
if (raw.connection === 'local-stdio' && raw.setup_receipt_version === 1) return { setup: raw as unknown as ClaudeSetupReceipt, hosted: null };
throw new Error(`the connection receipt ${receiptPath} was not written by gbrain setup; it is left untouched. Choose another --name.`);
}
function writeSetupReceipt(path: string, receipt: ClaudeSetupReceipt): void {
atomicWriteTextFile(path, `${JSON.stringify(receipt, null, 2)}\n`, { forceMode: 0o600 });
}
function mcpServers(config: Record<string, unknown>, plan: Pick<ClaudeSetupPlan, 'scope' | 'projectDir'>, create: boolean): Record<string, unknown> | undefined {
let holder: Record<string, unknown> = config;
if (plan.scope === 'project') {
const projects = config.projects as Record<string, unknown> | undefined;
if (projects !== undefined && (typeof projects !== 'object' || projects === null || Array.isArray(projects))) throw new Error('the Claude Code config "projects" key is not an object; setup leaves it untouched.');
if (!projects && !create) return undefined;
const all = projects ?? (config.projects = {}) as Record<string, unknown>;
const project = all[plan.projectDir!] as Record<string, unknown> | undefined;
if (!project && !create) return undefined;
holder = project ?? (all[plan.projectDir!] = {}) as Record<string, unknown>;
}
const servers = holder.mcpServers;
if (servers !== undefined && (typeof servers !== 'object' || servers === null || Array.isArray(servers))) throw new Error('the Claude Code "mcpServers" key is not an object; setup leaves it untouched.');
if (!servers && !create) return undefined;
return (servers ?? (holder.mcpServers = {})) as Record<string, unknown>;
}
function hookEnv(plan: ClaudeSetupPlan) {
return { ...(plan.sourceId ? { GBRAIN_SOURCE: plan.sourceId } : {}), ...(plan.gbrainHomeEnv ? { GBRAIN_HOME: plan.gbrainHomeEnv } : {}), GBRAIN_SEAT: '' };
}
export function desiredMcpEntry(plan: ClaudeSetupPlan): Record<string, unknown> {
const env: Record<string, string> = {};
if (plan.gbrainHomeEnv) env.GBRAIN_HOME = plan.gbrainHomeEnv;
if (plan.sourceId) env.GBRAIN_SOURCE = plan.sourceId;
// The harness starts stdio servers in the session's directory, so serve starts through the launcher too (#8426).
return { type: 'stdio', command: hookLauncherPath(plan.brainHome), args: stdioServeArgv(plan.launcher, plan.surface, plan.advertise, plan.stdioMember), env };
}
export function desiredHookHashes(plan: ClaudeSetupPlan): HookHashes {
const out: HookHashes = {};
for (const event of plan.events) {
out[event] = hookEntryHash({ type: 'command', command: buildClaudeHookCommand(plan.launcher, event, hookEnv(plan), hookLauncherPath(plan.brainHome)), timeout: CLAUDE_HOOK_DEFAULT_TIMEOUT_SECS[event] })!;
}
return out;
}
const consentValues = (c: SetupConsent): string => JSON.stringify([c.wiring_scope.value.scope, c.wiring_scope.value.hooks, c.capture.value, c.providers.value]);
const values = (h: HookHashes | undefined): string[] => Object.values(h ?? {}).filter((v): v is string => typeof v === 'string');
interface HookCensus { byEvent: Map<string, Array<{ hash: string; marked: boolean }>>; otherLane: Set<string> }
function hookCensus(settingsPath: string): HookCensus {
const settings = readJsonObject(settingsPath);
const byEvent = new Map<string, Array<{ hash: string; marked: boolean }>>();
const otherLane = new Set<string>();
const hooks = settings.hooks;
if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) return { byEvent, otherLane };
for (const [event, groups] of Object.entries(hooks as Record<string, unknown>)) {
if (!Array.isArray(groups)) continue;
for (const group of groups) {
const entries = (group as { hooks?: unknown })?.hooks;
if (!Array.isArray(entries)) continue;
for (const entry of entries) {
const marker = (entry as Record<string, unknown> | null)?.[GBRAIN_HOOK_MARKER_KEY];
if (isTurnRuleEntry(entry) || isSkillResolverEntry(entry)) continue;
if ((typeof marker === 'string' && marker !== GBRAIN_SETUP_MARKER_VALUE) || classifyHarnessHook(entry, event, 'any')) {
if ((CLAUDE_HOOK_EVENTS as readonly string[]).includes(event)) otherLane.add(event);
continue;
}
const hash = hookEntryHash(entry);
if (hash) byEvent.set(event, [...(byEvent.get(event) ?? []), { hash, marked: marker === GBRAIN_SETUP_MARKER_VALUE }]);
}
}
}
return { byEvent, otherLane };
}
/** Read-only: what setup would find and own. Throws on an unparseable config. */
export function inspectClaudeSetup(plan: ClaudeSetupPlan): ClaudeInspection {
const paths = claudeSetupPaths(plan);
const { setup: prior, hosted } = readSetupReceipt(paths.receiptPath);
const servers = mcpServers(readJsonObject(paths.configPath), plan, false);
const entry = servers?.[plan.name];
const desired = entryHash(desiredMcpEntry(plan));
const mcp: ClaudeInspection['mcp'] = entry === undefined ? { state: 'absent' }
: entryHash(entry) === desired ? withStdioMember({ state: 'current' }, entry)
: typeof (entry as Record<string, unknown>)?.url === 'string' ? { state: 'remote', url: (entry as Record<string, string>).url }
: prior && [prior.entry_hash, prior.pending_entry_hash].includes(entryHash(entry)) ? withStdioMember({ state: 'owned' }, entry) : { state: 'unowned' };
const census = hookCensus(paths.settingsPath);
const want = desiredHookHashes(plan);
const owned = new Set([...values(prior?.hooks.owned), ...values(prior?.hooks.pending), ...values(want)]);
const edited: HookHashes = {};
for (const event of CLAUDE_HOOK_EVENTS) {
const present = census.byEvent.get(event) ?? [];
const recorded = prior?.hooks.owned[event];
const priorEdit = prior?.hooks.edited[event];
const stillEdited = priorEdit && present.some((p) => p.hash === priorEdit);
const newlyEdited = recorded && !present.some((p) => p.hash === recorded) && present.find((p) => p.marked && !owned.has(p.hash));
if (stillEdited) edited[event] = priorEdit;
else if (newlyEdited) edited[event] = newlyEdited.hash;
}
let hooksCurrent = true;
for (const [event, present] of census.byEvent) {
const target = want[event as ClaudeHookEvent];
if (present.some((p) => owned.has(p.hash) && p.hash !== target)) hooksCurrent = false;
if (target && present.filter((p) => p.hash === target).length > 1) hooksCurrent = false;
}
for (const event of plan.events) {
if (!edited[event] && !(census.byEvent.get(event) ?? []).some((p) => p.hash === want[event])) hooksCurrent = false;
}
return { ...paths, prior, hostedReceipt: hosted, mcp, otherLaneEvents: [...census.otherLane], edited, hooksCurrent };
}
export interface ApplyResult { steps: SetupStep[]; receipt: ClaudeSetupReceipt; changed: boolean; edited: HookHashes }
/**
* Apply the plan under the config-dir lock. `pluginOwner` skips the MCP
* entry (the plugin serves the name). `beforeMcp` runs after the receipt is
* prepared and before the MCP write (the brain init step); `abortAfter` is
* the crash-injection test seam.
*/
export async function applyClaudeSetup(
plan: ClaudeSetupPlan,
consent: SetupConsent,
opts: { pluginOwner: string | null; brainCreated: boolean; beforeMcp?: () => Promise<void>; abortAfter?: string; refreshOf?: ClaudeSetupReceipt },
): Promise<ApplyResult> {
const paths = claudeSetupPaths(plan);
const lock = await acquireBootstrapLock(dirname(paths.configPath));
try {
// The MCP entry and every hook command start gbrain through the launcher, so it goes down before anything names it (#8424, #8426).
ensureHookLauncher(hookLauncherPath(plan.brainHome));
const found = inspectClaudeSetup(plan);
// post-upgrade's refresh: it rewrites only the install it planned from, and the MCP entry only while it is still setup's, both read again under the lock (#8426).
if (opts.refreshOf && JSON.stringify(found.prior) !== JSON.stringify(opts.refreshOf)) throw new Error(`the '${plan.name}' setup receipt changed before setup's entries were rewritten`);
if (opts.refreshOf && opts.pluginOwner === null && found.mcp.state !== 'current' && found.mcp.state !== 'owned') throw new Error(`the '${plan.name}' MCP entry changed before setup's entries were rewritten`);
const now = new Date().toISOString();
const desired = desiredMcpEntry(plan);
const desiredHash = entryHash(desired);
const want = desiredHookHashes(plan);
const writeEvents = plan.events.filter((e) => !found.edited[e]);
const prior = found.prior;
const consentSame = prior?.consent !== undefined && consentValues(prior.consent) === consentValues(consent);
const mcpDone = opts.pluginOwner !== null || found.mcp.state === 'current';
const steps: SetupStep[] = [];
if (prior?.status === 'installed' && consentSame && mcpDone && found.hooksCurrent && !opts.brainCreated) {
steps.push({ step: 'receipt', action: 'keep', detail: `${paths.receiptPath} already records this install` });
steps.push({ step: 'mcp', action: opts.pluginOwner ? 'skip' : 'keep', detail: opts.pluginOwner ? `the '${opts.pluginOwner}' plugin serves '${plan.name}'` : `'${plan.name}' in ${paths.configPath} is current` });
steps.push({ step: 'hooks', action: 'keep', detail: plan.events.length ? `${plan.events.join(', ')} in ${paths.settingsPath} are current` : 'no hooks wanted' });
return { steps, receipt: prior, changed: false, edited: found.edited };
}
const receipt: ClaudeSetupReceipt = {
harness: 'claude-code', connection: 'local-stdio', setup_receipt_version: 1, status: 'prepared',
name: plan.name, gbrain_home: plan.brainHome, launcher: plan.launcher, scope: plan.scope,
...(plan.projectDir ? { project_dir: plan.projectDir } : {}),
source_id: plan.sourceId, surface: plan.surface, ...(plan.advertise ? { advertise: plan.advertise } : {}), config_path: paths.configPath,
entry_hash: prior?.entry_hash ?? null, pending_entry_hash: opts.pluginOwner ? null : desiredHash,
...(prior?.mcp_adopted ? { mcp_adopted: true } : {}),
...(opts.pluginOwner ? { mcp_plugin: opts.pluginOwner } : {}),
hooks: { settings_path: paths.settingsPath, owned: prior?.hooks.owned ?? {}, pending: Object.fromEntries(writeEvents.map((e) => [e, want[e]])), edited: found.edited },
consent: { ...consent, recorded_at: now },
brain_created_by_setup: (prior?.brain_created_by_setup ?? false) || opts.brainCreated,
native_harness_verified: false,
created_at: prior?.created_at ?? now, updated_at: now,
};
const save = () => writeSetupReceipt(paths.receiptPath, receipt);
save();
steps.push({ step: 'receipt', action: 'write', detail: `${paths.receiptPath} (prepared: consent and pending hashes recorded)` });
if (opts.abortAfter === 'receipt') throw new SetupAbortInjected('receipt');
await opts.beforeMcp?.();
if (opts.pluginOwner) {
steps.push({ step: 'mcp', action: 'skip', detail: `the '${opts.pluginOwner}' plugin serves '${plan.name}'; no hand-wired entry` });
} else if (found.mcp.state === 'current') {
if (!prior?.entry_hash && !prior?.pending_entry_hash) receipt.mcp_adopted = true;
receipt.entry_hash = desiredHash;
steps.push({ step: 'mcp', action: 'keep', detail: `'${plan.name}' in ${paths.configPath} is current${receipt.mcp_adopted ? ' (adopted: it was already there, so --remove keeps it)' : ''}` });
} else {
const config = readJsonObject(paths.configPath);
mcpServers(config, plan, true)![plan.name] = desired;
atomicWriteTextFile(paths.configPath, `${JSON.stringify(config, null, 2)}\n`, { freshMode: 0o600 });
receipt.entry_hash = desiredHash;
delete receipt.mcp_adopted;
steps.push({ step: 'mcp', action: 'write', detail: `'${plan.name}' in ${paths.configPath}` });
}
receipt.pending_entry_hash = null;
save();
if (opts.abortAfter === 'mcp') throw new SetupAbortInjected('mcp');
if (found.hooksCurrent) {
steps.push({ step: 'hooks', action: 'keep', detail: plan.events.length ? `${plan.events.join(', ')} in ${paths.settingsPath} are current` : 'no hooks wanted' });
} else {
const ownedHashes = new Set([...values(prior?.hooks.owned), ...values(prior?.hooks.pending), ...values(receipt.hooks.pending)]);
writeClaudeHooksAt(paths.settingsPath, {
gbrainBin: plan.launcher, hookLauncher: hookLauncherPath(plan.brainHome), env: hookEnv(plan), events: writeEvents, marker: GBRAIN_SETUP_MARKER_VALUE,
ownedEntryHashes: ownedHashes, freshMode: 0o600,
});
steps.push({ step: 'hooks', action: 'write', detail: writeEvents.length ? `${writeEvents.join(', ')} in ${paths.settingsPath}` : `removed setup's hooks from ${paths.settingsPath}` });
}
for (const [event, hash] of Object.entries(found.edited)) {
steps.push({ step: 'hooks', action: 'preserve', detail: `${event} in ${paths.settingsPath} was edited after setup wrote it (hash ${hash.slice(0, 12)}); kept as is` });
}
receipt.hooks.owned = Object.fromEntries(writeEvents.map((e) => [e, want[e]]));
receipt.hooks.pending = {};
save();
if (opts.abortAfter === 'hooks') throw new SetupAbortInjected('hooks');
receipt.status = 'installed';
save();
return { steps, receipt, changed: true, edited: found.edited };
} finally {
lock.release();
}
}
export interface RemoveResult { steps: SetupStep[]; preserved: Array<{ kind: 'mcp' | 'hook'; event?: string; reason: string }>; receiptRemoved: boolean }
/** Remove exactly what the receipt owns by hash; edited entries survive and are reported. */
export async function removeClaudeSetup(receipt: ClaudeSetupReceipt, receiptPath: string, opts: { dryRun: boolean }): Promise<RemoveResult> {
const plan = { name: receipt.name, scope: receipt.scope, projectDir: receipt.project_dir };
const lock = await acquireBootstrapLock(dirname(receipt.config_path));
try {
const steps: SetupStep[] = [];
const preserved: RemoveResult['preserved'] = [];
const config = readJsonObject(receipt.config_path);
const servers = mcpServers(config, plan, false);
const entry = servers?.[receipt.name];
if (receipt.mcp_plugin) {
steps.push({ step: 'mcp', action: 'skip', detail: `the '${receipt.mcp_plugin}' plugin serves '${receipt.name}'; setup wrote no entry` });
} else if (entry === undefined) {
steps.push({ step: 'mcp', action: 'skip', detail: `no '${receipt.name}' entry in ${receipt.config_path}` });
} else if (receipt.mcp_adopted && entryHash(entry) === receipt.entry_hash) {
steps.push({ step: 'mcp', action: 'preserve', detail: `'${receipt.name}' existed before setup ran; kept` });
preserved.push({ kind: 'mcp', reason: 'adopted' });
} else if ([receipt.entry_hash, receipt.pending_entry_hash].includes(entryHash(entry))) {
if (!opts.dryRun) {
delete servers![receipt.name];
atomicWriteTextFile(receipt.config_path, `${JSON.stringify(config, null, 2)}\n`, { freshMode: 0o600 });
}
steps.push({ step: 'mcp', action: 'remove', detail: `'${receipt.name}' from ${receipt.config_path}` });
} else {
steps.push({ step: 'mcp', action: 'preserve', detail: `'${receipt.name}' in ${receipt.config_path} changed after setup wrote it; kept` });
preserved.push({ kind: 'mcp', reason: 'edited' });
}
const owned = new Set([...values(receipt.hooks.owned), ...values(receipt.hooks.pending)]);
let before: HookCensus['byEvent'] = new Map();
try { before = hookCensus(receipt.hooks.settings_path).byEvent; } catch { /* removeClaudeHooksAt reports an unparseable file */ }
const r = removeClaudeHooksAt(receipt.hooks.settings_path, GBRAIN_SETUP_MARKER_VALUE, { ownedEntryHashes: owned, dryRun: opts.dryRun });
steps.push({ step: 'hooks', action: r.removed > 0 ? 'remove' : 'skip', detail: r.removed > 0 ? `${r.removed} hook entr${r.removed === 1 ? 'y' : 'ies'} from ${r.settingsPath}` : (r.notes[0] ?? 'no owned hook entries present') });
const edited: HookHashes = {};
for (const p of r.preserved) {
const event = p.event as ClaudeHookEvent;
const recorded = receipt.hooks.owned[event] ?? receipt.hooks.pending[event];
const ours = receipt.hooks.edited[event] === p.hash
|| (recorded !== undefined && !(before.get(event) ?? []).some((e) => e.hash === recorded) && edited[event] === undefined);
if (!ours) continue;
edited[p.event as ClaudeHookEvent] = p.hash;
preserved.push({ kind: 'hook', event: p.event, reason: 'edited' });
steps.push({ step: 'hooks', action: 'preserve', detail: `${p.event} in ${r.settingsPath} was edited after setup wrote it; kept` });
}
let receiptRemoved = false;
if (!opts.dryRun) {
if (preserved.some((p) => p.reason === 'edited')) {
writeSetupReceipt(receiptPath, { ...receipt, status: 'removed', entry_hash: null, pending_entry_hash: null,
hooks: { ...receipt.hooks, owned: {}, pending: {}, edited }, updated_at: new Date().toISOString() });
steps.push({ step: 'receipt', action: 'write', detail: `${receiptPath} (removed; remembers the edited entries so a later setup leaves them alone)` });
} else {
if (existsSync(receiptPath)) unlinkSync(receiptPath);
receiptRemoved = true;
steps.push({ step: 'receipt', action: 'remove', detail: receiptPath });
}
}
return { steps, preserved, receiptRemoved };
} finally {
lock.release();
}
}
export class SetupAbortInjected extends Error {
constructor(readonly phase: string) {
super(`setup aborted after ${phase} (GBRAIN_SETUP_ABORT_AFTER test seam)`);
this.name = 'SetupAbortInjected';
}
}