Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(setup): ask the launcher before the ledger lock when a recorded decision may flip; a lock refusal on an unreadable file reports preserve; correct the paired-removal note

garrytanda4f2a9ce6a9
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2e5b03d96f..fe5ce24a1b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,7 +17,7 @@ identifiers and attribution are available in the pre-removal Git revision
### Itemized changes
- The brain-first and skill-loading ledgers share one lock (`~/.gbrain/agent-instructions.lock`), held across each install step: the ledger read, the file edit, the Claude Code permission edit and the ledger write (#8484). An install that waited reads the recorded choice again under the lock, so an opt-out the other install just recorded stays in force. An install that cannot take it within 10 seconds, or cannot create it, changes nothing and reports why (the skills outcome's reason is `ledger_locked`). A dry run takes no lock.
-- `gbrain setup codex --skill-loading off`, `--no-instructions` and `GBRAIN_SKILL_LOADING=off` also strip a spring index gbrain recorded in the other global instruction file of the same `CODEX_HOME` (`AGENTS.md` or `AGENTS.override.md`), and report it as a second skills line in the plain output (`paired` in `--json`), in `--dry-run` too (#8485). A plain re-run strips nothing, and no other Codex home, OpenClaw workspace or Claude profile is touched.
+- `gbrain setup codex --skill-loading off`, `--no-instructions` and `GBRAIN_SKILL_LOADING=off` also strip a spring index gbrain recorded in the other global instruction file of the same `CODEX_HOME` (`AGENTS.md` or `AGENTS.override.md`), and report it as a second skills line in the plain output (`paired` in `--json`), in `--dry-run` too (#8485). A plain re-run strips it only when brain-first instructions are declined on record for that Codex home, and no other Codex home, OpenClaw workspace or Claude profile is touched.
## [0.60.565.0] - 2026-11-03
diff --git a/src/core/setup/brain-first.ts b/src/core/setup/brain-first.ts
index 46aae72afe..a6e066e715 100644
--- a/src/core/setup/brain-first.ts
+++ b/src/core/setup/brain-first.ts
@@ -353,6 +353,14 @@ export function inspectBrainFirst(path: string, expected?: string): { state: Bra
return { state: current ? 'current' : 'stale', version };
}
+function stateForRefusal(path: string): BrainFirstState {
+ try {
+ return inspectBrainFirst(path).state;
+ } catch {
+ return 'damaged';
+ }
+}
+
export interface BrainFirstOutcome {
harness: string;
path: string;
@@ -398,7 +406,7 @@ export function syncBrainFirst(opts: { target: BrainFirstTarget; access: BrainFi
return syncBrainFirstLocked(outermost && recorded ? { ...opts, decision: resolveBrainFirstDecision(undefined, priorBrainFirst(opts.target.harness, opts.target.path)) } : opts);
}, (why) => ({
harness: opts.target.harness, path: opts.target.path, role: opts.target.role, decision: opts.decision, action: 'preserve',
- state_before: inspectBrainFirst(opts.target.path).state, detail: `${why}; ${opts.target.path} was left as it was`,
+ state_before: stateForRefusal(opts.target.path), detail: `${why}; ${opts.target.path} was left as it was`,
}));
}
@@ -465,7 +473,7 @@ function syncBrainFirstLocked(opts: { target: BrainFirstTarget; access: BrainFir
export function removeBrainFirst(opts: { harness: string; path: string; dryRun: boolean; server?: string }): BrainFirstOutcome {
return underInstructionLedgerLock(opts.dryRun, () => removeBrainFirstLocked(opts), (why) => ({
harness: opts.harness, path: opts.path, role: 'instruction file', decision: { value: 'declined', source: 'flag' }, action: 'preserve',
- state_before: inspectBrainFirst(opts.path).state, detail: `${why}; ${opts.path} was left as it was`,
+ state_before: stateForRefusal(opts.path), detail: `${why}; ${opts.path} was left as it was`,
}));
}
diff --git a/src/core/setup/skills-block.ts b/src/core/setup/skills-block.ts
index 5643af2211..c074a6d4da 100644
--- a/src/core/setup/skills-block.ts
+++ b/src/core/setup/skills-block.ts
@@ -394,7 +394,8 @@ const message = (e: unknown) => (e instanceof Error ? e.message : String(e));
* says otherwise.
*/
export function syncSkillsBlock(opts: { target: BrainFirstTarget; launcher: string; decision: SkillLoadingDecision; writer: string; dryRun: boolean; audience?: SkillAudience; settingsPath?: string }): SkillsBlockOutcome {
- if (opts.decision.value === 'spring') launcherCatalog(opts.launcher);
+ const mayFlip = !opts.dryRun && (opts.decision.source === 'prior' || opts.decision.source === 'default');
+ if (opts.decision.value === 'spring' || mayFlip) launcherCatalog(opts.launcher);
return underInstructionLedgerLock(opts.dryRun, (outermost) => {
const run = { ...opts, decision: outermost ? recordedSkillLoading(opts.target, opts.decision) : opts.decision };
const outcome = syncSkillsBlockLocked(run);
@@ -426,8 +427,8 @@ function recordedSkillLoading(target: BrainFirstTarget, decision: SkillLoadingDe
/**
* #8485: Codex loads its global AGENTS.override.md when it is non-empty, else
* AGENTS.md, so the file setup resolves moves when the override appears or
- * empties. An explicit opt-out (flag, env, --no-instructions) in one of the
- * two also reaches a spring index gbrain recorded in the other one in the
+ * empties. An opt-out (flag, env, or brain-first instructions declined now
+ * or on record) in one of the two also reaches a spring index gbrain recorded in the other one in the
* same CODEX_HOME, so the index cannot come back when the override goes.
* No other file is touched.
*/
diff --git a/test/instruction-ledger-lock.test.ts b/test/instruction-ledger-lock.test.ts
index fc8f53dfce..e735f778fc 100644
--- a/test/instruction-ledger-lock.test.ts
+++ b/test/instruction-ledger-lock.test.ts
@@ -15,7 +15,7 @@ import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, wr
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { withEnv } from './helpers/with-env.ts';
-import { brainFirstLedgerPath, brainFirstTargetAt, priorBrainFirst, resolveBrainFirstDecision, syncBrainFirst } from '../src/core/setup/brain-first.ts';
+import { brainFirstLedgerPath, brainFirstTargetAt, priorBrainFirst, removeBrainFirst, resolveBrainFirstDecision, syncBrainFirst } from '../src/core/setup/brain-first.ts';
import { priorSkillLoading, readSkillLoadingLedger, resolveSkillLoading, skillLoadingLedgerPath, syncSkillsBlock } from '../src/core/setup/skills-block.ts';
import { SKILL_INDEX_VERSION } from '../src/core/skills/spring-index.ts';
@@ -35,6 +35,7 @@ const next = JSON.parse(entry);
ledger.entries = ledger.entries.filter((e) => !(e.harness === next.harness && e.path === next.path));
ledger.entries.push(next);
writeFileSync(ledgerPath, JSON.stringify(ledger, null, 2) + '\n');
+writeFileSync(marker + '.done', 'done');
lock.release();
`;
@@ -155,4 +156,43 @@ describe('#8484: an install that waited acts on what the other one recorded', ()
expect(priorBrainFirst('claude-code', file)?.status).toBe('declined');
});
}, 60_000);
+
+ test('skills: an off decision that turns into spring while this install waited asks the launcher before taking the lock', async () => {
+ const home = sandbox();
+ await withEnv({ GBRAIN_HOME: home, HOME: home, GBRAIN_SKILL_LOADING: undefined }, async () => {
+ const file = join(home, '.codex', 'AGENTS.md');
+ const target = brainFirstTargetAt('codex', file);
+ expect(syncSkillsBlock({ target, launcher: LAUNCHER, decision: { value: 'spring', source: 'flag' }, writer: 'gbrain setup codex --skill-loading spring', dryRun: false }).action).toBe('write');
+ const springEntry = readSkillLoadingLedger()[0];
+ rmSync(skillLoadingLedgerPath());
+ rmSync(file);
+ const probe = join(BIN, 'gbrain-probe');
+ const asked = join(home, 'asked');
+ writeFileSync(probe, `#!/bin/sh\nif [ -f '${join(home, 'held.done')}' ]; then echo under-lock >> '${asked}'; else echo before-lock >> '${asked}'; fi\nexec '${LAUNCHER}' "$@"\n`);
+ chmodSync(probe, 0o755);
+ const { exited } = await otherInstall(home, skillLoadingLedgerPath(), springEntry);
+ const out = syncSkillsBlock({ target, launcher: probe, decision: { value: 'off', source: 'default' }, writer: 'gbrain setup codex', dryRun: false });
+ expect(await exited).toBe(0);
+ expect(out.decision).toEqual({ value: 'spring', source: 'prior' });
+ expect(out.action).toBe('write');
+ expect(readFileSync(asked, 'utf8').trim().split('\n')).toEqual(['before-lock']);
+ });
+ }, 60_000);
+});
+
+describe('#8484: a lock refusal on an unreadable instruction file reports preserve', () => {
+ test('syncBrainFirst and removeBrainFirst return preserve instead of throwing', async () => {
+ const home = sandbox();
+ await withEnv({ GBRAIN_HOME: home, HOME: home, GBRAIN_AGENT_INSTRUCTIONS: undefined }, async () => {
+ mkdirSync(join(home, '.gbrain', 'agent-instructions.lock'));
+ const file = join(home, '.claude', 'CLAUDE.md');
+ mkdirSync(file, { recursive: true });
+ const access = { kind: 'mcp' as const, server: 'gbrain' };
+ const sync = syncBrainFirst({ target: brainFirstTargetAt('claude-code', file), access, decision: { value: 'accepted', source: 'flag' }, writer: 'gbrain setup claude-code', dryRun: false });
+ expect(sync).toMatchObject({ action: 'preserve', state_before: 'damaged' });
+ expect(sync.detail).toContain('could not be locked');
+ const removed = removeBrainFirst({ harness: 'claude-code', path: file, dryRun: false });
+ expect(removed).toMatchObject({ action: 'preserve', state_before: 'damaged' });
+ });
+ });
});