Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
30.3 KB
Raw Blame
/**
 * The one-time `behavior_changes` safety notice (fix wave lane B3, W-A3).
 *
 * Protects: an existing brain (recorded upgrade from an older release, an
 * older recorded baseline, or a brain created before the grace window with no
 * upgrade history) gets the disclosure once per notice × brain × channel, and
 * once per authenticated client over HTTP; a fresh install never does, even
 * after the grace window; markers survive a restart; a home that cannot be
 * written still delivers (once per process); concurrent processes deliver it
 * once; the chain section appears only when a chain is set, and the HTTP view
 * never names entries or providers; failed tool responses carry it; doctor
 * reads it without recording anything. The #6188 fence rows (inline
 * normalization, automatic repair) reach an upgraded brain with their opt-out
 * commands, the first-run sweep disclosure and undo guidance, and never a
 * fresh install.
 * Fails when: eligibility, marker identity, the HTTP per-client store, the
 * remote redaction or dispatch delivery regress.
 * Seams: per-test GBRAIN_HOME; `__resetBehaviorNoticeForTests` stands in for a
 * new process; PGLite always, Postgres when DATABASE_URL is set.
 */
import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import {
  BEHAVIOR_CHANGES,
  BEHAVIOR_NOTICE_ID,
  BEHAVIOR_NOTICE_SINCE,
  HTTP_SHOWN_CAP,
  HTTP_SHOWN_KEY,
  __resetBehaviorNoticeForTests,
  behaviorBrainKey,
  behaviorChangesNotice,
  compareReleases,
  recordHttpShown,
  takeHttpBehaviorNotice,
  takeLocalBehaviorNotice,
} from '../src/core/behavior-change-notice.ts';
import { cliRenderContext, renderNotice } from '../src/core/agent-output.ts';
import { VERSION } from '../src/version.ts';
import { checkBehaviorChanges } from '../src/commands/doctor/checks/behavior-changes.ts';
import { dispatchToolCall } from '../src/mcp/dispatch.ts';

// Expectations derive from the BEHAVIOR_CHANGES table, so adding a release's
// rows does not require re-pinning every count; each release's own content is
// still asserted by text below.
const NEWEST = BEHAVIOR_NOTICE_SINCE;
const NEXT_PATCH = NEWEST.replace(/^(\d+\.\d+\.)(\d+)(.*)$/, (_m, a: string, b: string, c: string) => `${a}${Number(b) + 1}${c}`);
const NEWEST_TEXT = (BEHAVIOR_CHANGES.find(c => c.since === NEWEST && typeof c.text === 'string')!.text as string).slice(0, 48);
function noticeHeader(after: string, withChain = false): string {
  const rows = BEHAVIOR_CHANGES.filter(c => compareReleases(c.since, after) > 0 && (withChain || typeof c.text === 'string'));
  const releases = [...new Set(rows.map(c => c.since))];
  const list = releases.length > 4
    ? `v${[...releases].sort(compareReleases)[0]} through v${[...releases].sort(compareReleases).at(-1)} (${releases.length} releases)`
    : releases.length > 1 ? `${releases.slice(0, -1).map(v => `v${v}`).join(', ')} and v${releases.at(-1)}` : `v${releases[0]}`;
  return `gbrain ${list} changed ${rows.length} behavior${rows.length === 1 ? '' : 's'}`;
}
import { NoticeLedger, __resetProcessNoticeLedgerForTests } from '../src/core/notice-ledger.ts';
import { _resetDbPlaneMergeMemoForTests } from '../src/core/config-db-merge.ts';
import type { GBrainConfig } from '../src/core/config.ts';
import { withEnv } from './helpers/with-env.ts';
import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';

const DAY = 24 * 60 * 60 * 1000;
const NO_CHAIN = { GBRAIN_CHAT_FALLBACK_CHAIN: undefined, GBRAIN_CHAT_FALLBACK_ON_REFUSAL: undefined };
const freshHome = () => mkdtempSync(join(tmpdir(), 'gbrain-behavior-home-'));
const noticeDir = (home: string) => join(home, '.gbrain', 'notices', 'behavior-changes');
let seq = 0;
const config = (): GBrainConfig => ({ engine: 'pglite', database_path: join(tmpdir(), `behavior-brain-${process.pid}-${++seq}`) } as GBrainConfig);

async function setCreated(engine: BrainEngine, agoMs: number): Promise<void> {
  await engine.executeRaw(`UPDATE sources SET created_at = $1::timestamptz`, [new Date(Date.now() - agoMs).toISOString()]);
}

function noticeBlocks(res: { content: Array<{ text: string }> }): string[] {
  return res.content.map(c => c.text).filter(t => t.startsWith('[gbrain notice behavior_changes kind=safety]'));
}

for (const backend of testBackends()) {
  describe(`${backend}: behavior_changes notice`, () => {
    let engine: BrainEngine;
    let close: () => Promise<void>;
    beforeAll(async () => {
      if (backend === 'postgres') {
        const pg = await isolatedPersistencePostgres(requirePostgresTestDatabase());
        engine = pg.engine;
        close = pg.close;
      } else {
        const pglite = new PGLiteEngine();
        await pglite.connect({});
        await pglite.initSchema();
        engine = pglite;
        close = () => pglite.disconnect();
      }
    }, 120_000);
    afterAll(async () => { await close(); });
    beforeEach(async () => {
      __resetBehaviorNoticeForTests();
      __resetProcessNoticeLedgerForTests();
      _resetDbPlaneMergeMemoForTests();
      await engine.unsetConfig(HTTP_SHOWN_KEY);
      await engine.unsetConfig('chat_fallback_chain');
      await setCreated(engine, 0);
    });

    test('a fresh install sees nothing, and stays fresh after the grace window', async () => {
      const home = freshHome();
      await withEnv({ GBRAIN_HOME: home, ...NO_CHAIN }, async () => {
        expect(await takeLocalBehaviorNotice(engine, 'cli', { cfg: null, brainKey: 'fresh' })).toBeNull();
        expect(readFileSync(join(noticeDir(home), 'fresh.baseline'), 'utf8').trim()).toBe(VERSION);
        await setCreated(engine, 2 * DAY);
        __resetBehaviorNoticeForTests();
        expect(await takeLocalBehaviorNotice(engine, 'stdio', { cfg: null, brainKey: 'fresh' })).toBeNull();
      });
    });

    test('an existing brain with no upgrade history sees it once per channel, and a restart does not repeat it', async () => {
      await setCreated(engine, 2 * DAY);
      await withEnv({ GBRAIN_HOME: freshHome(), ...NO_CHAIN }, async () => {
        const first = await takeLocalBehaviorNotice(engine, 'cli', { cfg: null, brainKey: 'old' });
        expect(first?.code).toBe('behavior_changes');
        expect(first?.kind).toBe('safety');
        expect(await takeLocalBehaviorNotice(engine, 'cli', { cfg: null, brainKey: 'old' })).toBeNull();
        __resetBehaviorNoticeForTests();
        expect(await takeLocalBehaviorNotice(engine, 'cli', { cfg: null, brainKey: 'old' })).toBeNull();
        expect((await takeLocalBehaviorNotice(engine, 'stdio', { cfg: null, brainKey: 'old' }))?.code).toBe('behavior_changes');
        expect(await takeLocalBehaviorNotice(engine, 'stdio', { cfg: null, brainKey: 'old' })).toBeNull();
      });
    });

    test('a skipped-release install still sees it: upgrade history from an older release, or an older recorded baseline', async () => {
      const home = freshHome();
      mkdirSync(join(home, '.gbrain'), { recursive: true });
      writeFileSync(join(home, '.gbrain', 'upgrade-state.json'), JSON.stringify({ last_upgrade: { from: '0.50.0.0', to: '99.0.0.0' } }));
      await withEnv({ GBRAIN_HOME: home, ...NO_CHAIN }, async () => {
        expect((await takeLocalBehaviorNotice(engine, 'cli', { cfg: null, brainKey: 'upgraded' }))?.code).toBe('behavior_changes');
      });
      const baselineHome = freshHome();
      mkdirSync(noticeDir(baselineHome), { recursive: true });
      writeFileSync(join(noticeDir(baselineHome), 'older.baseline'), '0.59.0.0\n');
      writeFileSync(join(noticeDir(baselineHome), 'current.baseline'), `${BEHAVIOR_NOTICE_SINCE}\n`);
      await withEnv({ GBRAIN_HOME: baselineHome, ...NO_CHAIN }, async () => {
        expect((await takeLocalBehaviorNotice(engine, 'cli', { cfg: null, brainKey: 'older' }))?.code).toBe('behavior_changes');
        expect(await takeLocalBehaviorNotice(engine, 'cli', { cfg: null, brainKey: 'current' })).toBeNull();
      });
    });

    test('each brain gets its own disclosure', async () => {
      await setCreated(engine, 2 * DAY);
      await withEnv({ GBRAIN_HOME: freshHome(), ...NO_CHAIN }, async () => {
        const a = behaviorBrainKey(config());
        const b = behaviorBrainKey(config());
        expect(a).not.toBe(b);
        expect(await takeLocalBehaviorNotice(engine, 'cli', { cfg: null, brainKey: a })).not.toBeNull();
        expect(await takeLocalBehaviorNotice(engine, 'cli', { cfg: null, brainKey: b })).not.toBeNull();
      });
    });

    test('the chain section appears only when a chain is set, with entries, providers and refusal behavior', async () => {
      await setCreated(engine, 2 * DAY);
      await withEnv({ GBRAIN_HOME: freshHome(), ...NO_CHAIN }, async () => {
        const plain = (await takeLocalBehaviorNotice(engine, 'cli', { cfg: null, brainKey: 'no-chain' }))!;
        expect(plain.why).not.toContain('chat_fallback_chain is live');
        expect(plain.why).toContain('cycle.lint_fix false');
        expect(plain.why).toContain('about 6.75x');
        expect(plain.why).toContain('mention linker');
        expect(plain.why).toContain('`setsid`');
        expect(plain.why).toContain('autopilot.auto_drain.enabled false');
        expect(plain.why).toContain('at most 90 days');
        expect(plain.why).toContain('local_process_ingress');
        expect(plain.why).toContain('exits 0 after a SIGTERM drain (was 143) and 17');
        expect(plain.why).toContain('gbrain sweep --once --budget-ms 600000');
        expect(plain.why).toContain('think.quote_verify false');
        expect(plain.why).toContain('decide.slots.conflict.review_withdraw false');
        expect(plain.why).toContain('no longer send text to an embedding provider');
        expect(plain.why).toContain('not a request for consent');
        expect(plain.fix?.argv).toEqual(['gbrain', 'doctor', '--only', 'behavior_changes', '--json']);
      });
      await withEnv({ GBRAIN_HOME: freshHome(), GBRAIN_CHAT_FALLBACK_CHAIN: 'openai:gpt-5.6-luna', GBRAIN_CHAT_FALLBACK_ON_REFUSAL: undefined, OPENAI_API_KEY: 'fake-openai' }, async () => {
        const chained = (await takeLocalBehaviorNotice(engine, 'cli', { cfg: null, brainKey: 'chain' }))!;
        expect(chained.why).toContain('chat_fallback_chain is live');
        expect(chained.why).toContain('openai:gpt-5.6-luna');
        expect(chained.why).toContain('so openai receive');
        expect(chained.why).toContain('on refusals as well as errors');
        expect(chained.fix?.argv).toEqual(['unset', 'GBRAIN_CHAT_FALLBACK_CHAIN']);
        expect(chained.fix?.actor).toBe('user');
      });
      await withEnv({ GBRAIN_HOME: freshHome(), GBRAIN_CHAT_FALLBACK_CHAIN: 'openai:gpt-5.6-luna', GBRAIN_CHAT_FALLBACK_ON_REFUSAL: 'false', OPENAI_API_KEY: 'fake-openai' }, async () => {
        expect((await takeLocalBehaviorNotice(engine, 'cli', { cfg: null, brainKey: 'chain-no-refusal' }))!.why).toContain('falls back on errors only');
      });
    });

    test('a home that cannot be written still gets the notice, once per process', async () => {
      await setCreated(engine, 2 * DAY);
      const blocker = join(freshHome(), 'not-a-dir');
      writeFileSync(blocker, 'x');
      await withEnv({ GBRAIN_HOME: join(blocker, 'home'), ...NO_CHAIN }, async () => {
        expect(await takeLocalBehaviorNotice(engine, 'stdio', { cfg: null, brainKey: 'ro' })).not.toBeNull();
        expect(await takeLocalBehaviorNotice(engine, 'stdio', { cfg: null, brainKey: 'ro' })).toBeNull();
        __resetBehaviorNoticeForTests();
        expect(await takeLocalBehaviorNotice(engine, 'stdio', { cfg: null, brainKey: 'ro' })).not.toBeNull();
      });
    });

    test('HTTP: once per authenticated client, kept in the brain across restarts, never naming entries or providers', async () => {
      await setCreated(engine, 2 * DAY);
      await withEnv({ GBRAIN_HOME: freshHome(), GBRAIN_CHAT_FALLBACK_CHAIN: 'openai:gpt-5.6-luna', OPENAI_API_KEY: 'fake-openai' }, async () => {
        const a = await takeHttpBehaviorNotice(engine, 'client-a', { cfg: null, brainKey: 'http' });
        expect(a?.code).toBe('behavior_changes');
        expect(a!.why).toContain('A chat fallback chain is configured on this brain host');
        expect(a!.why).not.toContain('gpt-5.6-luna');
        expect(a!.why).not.toContain('openai');
        expect(a!.fix?.actor).toBe('host_admin');
        expect(await takeHttpBehaviorNotice(engine, 'client-a', { cfg: null, brainKey: 'http' })).toBeNull();
        expect(await takeHttpBehaviorNotice(engine, 'client-b', { cfg: null, brainKey: 'http' })).not.toBeNull();
        __resetBehaviorNoticeForTests();
        expect(await takeHttpBehaviorNotice(engine, 'client-a', { cfg: null, brainKey: 'http' })).toBeNull();
        expect(await takeHttpBehaviorNotice(engine, undefined, { cfg: null, brainKey: 'http' })).toBeNull();
        const stored = JSON.parse((await engine.getConfig(HTTP_SHOWN_KEY))!);
        expect(stored.id).toBe(BEHAVIOR_NOTICE_ID);
        expect(Object.keys(stored.clients).sort()).toEqual(['client-a', 'client-b']);
      });
    });

    test('HTTP: a store that cannot be written still delivers', async () => {
      await setCreated(engine, 2 * DAY);
      const readOnly = new Proxy(engine, {
        get(target, prop, receiver) {
          if (prop === 'setConfig') return async () => { throw new Error('read-only brain'); };
          const v = Reflect.get(target, prop, receiver);
          return typeof v === 'function' ? v.bind(target) : v;
        },
      });
      await withEnv({ GBRAIN_HOME: freshHome(), ...NO_CHAIN }, async () => {
        expect(await takeHttpBehaviorNotice(readOnly, 'client-ro', { cfg: null, brainKey: 'http-ro' })).not.toBeNull();
      });
    });

    test('doctor shows the disclosure and records nothing', async () => {
      await setCreated(engine, 2 * DAY);
      const home = freshHome();
      await withEnv({ GBRAIN_HOME: home, ...NO_CHAIN }, async () => {
        const c = await checkBehaviorChanges(engine, { cfg: null, brainKey: 'doctor' });
        expect(c.status).toBe('ok');
        expect(c.message).toContain('one-time disclosure');
        expect(c.details).toMatchObject({ shown: { cli: false, stdio: false } });
        expect(existsSync(noticeDir(home))).toBe(false);
        expect(await takeLocalBehaviorNotice(engine, 'cli', { cfg: null, brainKey: 'doctor' })).not.toBeNull();
        const again = await checkBehaviorChanges(engine, { cfg: null, brainKey: 'doctor' });
        expect(again.details).toMatchObject({ shown: { cli: true, stdio: false } });
        expect(again.message).toContain(noticeHeader('0'));
      });
    });

    test('stdio dispatch: the first tool result carries it, later ones do not, and a failed first call carries it too', async () => {
      await setCreated(engine, 2 * DAY);
      await withEnv({ GBRAIN_HOME: freshHome(), ...NO_CHAIN }, async () => {
        const cfg = config();
        const opts = { remote: true, transport: 'stdio' as const, sourceId: 'default', config: cfg };
        const first = await dispatchToolCall(engine as never, 'list_pages', {}, opts);
        expect(noticeBlocks(first)).toHaveLength(1);
        const second = await dispatchToolCall(engine as never, 'list_pages', {}, opts);
        expect(noticeBlocks(second)).toHaveLength(0);

        __resetProcessNoticeLedgerForTests();
        const failCfg = config();
        const failed = await dispatchToolCall(engine as never, 'get_page', { slug: 'missing/acme-example' }, { ...opts, config: failCfg });
        expect(failed.isError).toBe(true);
        const envelope = JSON.parse(failed.content[0]!.text) as { notices?: Array<{ code: string }> };
        expect(envelope.notices?.map(n => n.code)).toContain('behavior_changes');
        const after = await dispatchToolCall(engine as never, 'list_pages', {}, { ...opts, config: failCfg });
        expect(noticeBlocks(after)).toHaveLength(0);
      });
    }, 60_000);

    test('HTTP dispatch: each client gets it on its first tool result', async () => {
      await setCreated(engine, 2 * DAY);
      await withEnv({ GBRAIN_HOME: freshHome(), ...NO_CHAIN }, async () => {
        const cfg = config();
        const ledger = new NoticeLedger();
        const httpOpts = (clientId: string) => ({ remote: true, transport: 'http' as const, sourceId: 'default', config: cfg, noticeLedger: ledger,
          auth: { token: 't', clientId, clientName: clientId, scopes: ['read'], expiresAt: Date.now() / 1000 + 3600 } as never });
        expect(noticeBlocks(await dispatchToolCall(engine as never, 'list_pages', {}, httpOpts('http-a')))).toHaveLength(1);
        expect(noticeBlocks(await dispatchToolCall(engine as never, 'list_pages', {}, httpOpts('http-a')))).toHaveLength(0);
        expect(noticeBlocks(await dispatchToolCall(engine as never, 'list_pages', {}, httpOpts('http-b')))).toHaveLength(1);
      });
    }, 60_000);
  });
}

describe('HTTP per-client store', () => {
  test('keeps the newest HTTP_SHOWN_CAP clients', () => {
    let raw: string | null = JSON.stringify({ id: '[email protected]', clients: { stale: '2020-01-01T00:00:00.000Z' } });
    for (let i = 0; i < HTTP_SHOWN_CAP + 25; i++) raw = recordHttpShown(raw, `client-${i}`, new Date(Date.UTC(2026, 0, 1, 0, 0, i)).toISOString());
    const stored = JSON.parse(raw!) as { id: string; clients: Record<string, string> };
    expect(stored.id).toBe(BEHAVIOR_NOTICE_ID);
    expect(Object.keys(stored.clients)).toHaveLength(HTTP_SHOWN_CAP);
    expect(stored.clients.stale).toBeUndefined();
    expect(stored.clients['client-0']).toBeUndefined();
    expect(stored.clients[`client-${HTTP_SHOWN_CAP + 24}`]).toBeDefined();
  });
});

describe('per-release content', () => {
  test('a client from an older build\'s row keeps the release it was shown', () => {
    const raw = recordHttpShown(JSON.stringify({ id: '[email protected]', clients: { old: '2026-10-05T00:00:00.000Z' } }), 'new', '2026-10-06T00:00:00.000Z');
    const stored = JSON.parse(raw) as { id: string; clients: Record<string, { since: string; at: string }> };
    expect(stored.id).toBe(BEHAVIOR_NOTICE_ID);
    expect(stored.clients.old).toEqual({ since: '0.60.68.0', at: '2026-10-05T00:00:00.000Z' });
    expect(stored.clients.new).toEqual({ since: BEHAVIOR_NOTICE_SINCE, at: '2026-10-06T00:00:00.000Z' });
  });

  test('the notice id is the newest change\'s release, and only newer changes are listed', () => {
    expect(BEHAVIOR_NOTICE_SINCE).toBe(BEHAVIOR_CHANGES.map(c => c.since).sort(compareReleases).at(-1)!);
    expect(BEHAVIOR_NOTICE_ID).toBe(`behavior_changes@${BEHAVIOR_NOTICE_SINCE}`);
    expect(behaviorChangesNotice(null, { after: BEHAVIOR_NOTICE_SINCE })).toBeNull();
    const chain = { plane: 'env' as const, entries: ['openai:gpt-5.6-luna'], providers: ['openai'], onRefusal: true, filePath: '' };
    const later = behaviorChangesNotice(chain, { after: '0.60.68.0' })!;
    expect(later.why).not.toContain('chat_fallback_chain is live');
    expect(later.fix?.argv).toEqual(['gbrain', 'doctor', '--only', 'behavior_changes', '--json']);
    const all = behaviorChangesNotice(chain)!;
    expect(all.why).toContain(noticeHeader('0', true));
    expect(all.fix?.argv).toEqual(['unset', 'GBRAIN_CHAT_FALLBACK_CHAIN']);
  });

  // Value: protects=the verbs-listing notice only promises the request_tools reveal where it exists; fails_when=the text says a described tool joins the session's list with no transport, and HTTP has no reveal; why_new=#7983 item 7; seam=none; no_claim=the reveal itself (mcp server tests)
  test('the verbs-listing notice scopes the request_tools reveal to stdio', () => {
    const text = BEHAVIOR_CHANGES.find(c => c.id === 'registration_lists_verbs_gbra199')!.text as string;
    expect(text).toContain("on stdio a tool it describes joins the session's list");
  });

  // #7646: table order is not release order (rows land out of order across merges), so the notice sorts releases itself.
  test('the disclosure lists releases oldest first, whatever the table order', () => {
    const listed = (why: string) => [...why.matchAll(/(?:^| )v(\d+\.\d+\.\d+\.\d+): \(/g)].map(m => m[1]!);
    const sinces = [...new Set(BEHAVIOR_CHANGES.map(c => c.since))].sort(compareReleases);
    for (const after of ['0', sinces.at(-6)!, sinces.at(-3)!]) {
      const shown = listed(behaviorChangesNotice(null, { after })!.why);
      expect(shown.length).toBeGreaterThan(1);
      expect(shown).toEqual([...shown].sort(compareReleases));
    }
  });
});

describe('concurrent initializations', () => {
  test('processes racing on one brain and channel deliver it exactly once', async () => {
    const home = freshHome();
    const script = join(home, 'race.ts');
    const modulePath = join(import.meta.dir, '..', 'src', 'core', 'behavior-change-notice.ts');
    writeFileSync(script, `
      const { takeLocalBehaviorNotice } = await import(${JSON.stringify(modulePath)});
      const old = new Date(Date.now() - 3 * 86400000).toISOString();
      const engine = { executeRaw: async () => [{ at: old }], getConfig: async () => null };
      const n = await takeLocalBehaviorNotice(engine, 'stdio', { cfg: null, brainKey: 'race' });
      console.log(JSON.stringify({ delivered: n !== null }));
    `);
    const env = { ...process.env, GBRAIN_HOME: home, GBRAIN_CHAT_FALLBACK_CHAIN: '' } as Record<string, string>;
    const procs = Array.from({ length: 6 }, () => Bun.spawn(['bun', script], { env, stdout: 'pipe', stderr: 'pipe' }));
    const outs = await Promise.all(procs.map(async p => { await p.exited; return new Response(p.stdout).text(); }));
    const delivered = outs.map(o => JSON.parse(o.trim().split('\n').pop()!).delivered as boolean);
    expect(delivered.filter(Boolean)).toHaveLength(1);
    expect(readFileSync(join(noticeDir(home), 'race.baseline'), 'utf8').trim()).toBe('0');
  }, 60_000);
});

describe('upgrades across releases (each step a new process pinned to a gbrain VERSION)', () => {
  const modulePath = join(import.meta.dir, '..', 'src', 'core', 'behavior-change-notice.ts');
  const WAVE9 = '`setsid`';
  const OPT_OUT = 'no longer send text to an embedding provider';
  const V68 = 'cycle.lint_fix false';

  /** One gbrain process at `version`: takes the notice on `channel` (`http:<client>` for an HTTP client) for brain `key`. */
  async function runAt(home: string, version: string, key: string, channel: string, opts: { createdAgoMs?: number } = {}): Promise<string | null> {
    const script = join(home, `step-${++seq}.ts`);
    writeFileSync(script, `
      Bun.plugin({ setup(b) { b.onLoad({ filter: /[\\\\/]src[\\\\/]version\\.ts$/ }, () => ({ contents: ${JSON.stringify(`export const VERSION = '${version}';`)}, loader: 'ts' })); } });
      const { existsSync, readFileSync, writeFileSync } = await import('node:fs');
      const { takeLocalBehaviorNotice, takeHttpBehaviorNotice } = await import(${JSON.stringify(modulePath)});
      const storePath = ${JSON.stringify(join(home, 'brain-config.json'))};
      const store = existsSync(storePath) ? JSON.parse(readFileSync(storePath, 'utf8')) : {};
      const created = new Date(Date.now() - ${opts.createdAgoMs ?? 3 * DAY}).toISOString();
      const engine = {
        executeRaw: async () => [{ at: created }],
        getConfig: async (k) => store[k] ?? null,
        setConfig: async (k, v) => { store[k] = v; writeFileSync(storePath, JSON.stringify(store)); },
      };
      const channel = ${JSON.stringify(channel)};
      const n = channel.startsWith('http:')
        ? await takeHttpBehaviorNotice(engine, channel.slice(5), { cfg: null, brainKey: ${JSON.stringify(key)} })
        : await takeLocalBehaviorNotice(engine, channel, { cfg: null, brainKey: ${JSON.stringify(key)} });
      console.log(JSON.stringify({ why: n?.why ?? null }));
    `);
    const env = { ...process.env, GBRAIN_HOME: home, GBRAIN_CHAT_FALLBACK_CHAIN: '' } as Record<string, string>;
    const p = Bun.spawn(['bun', script], { env, stdout: 'pipe', stderr: 'pipe' });
    const [out, err] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text(), p.exited]);
    const last = out.trim().split('\n').pop();
    if (!last) throw new Error(`step at ${version} printed nothing: ${err}`);
    return JSON.parse(last).why as string | null;
  }

  test('a brain that saw the notice gets nothing from a later release that adds no behavior changes', async () => {
    const home = freshHome();
    for (const channel of ['cli', 'http:client-a']) {
      expect(await runAt(home, NEWEST, 'seen', channel)).toContain(NEWEST_TEXT);
      expect(await runAt(home, NEWEST, 'seen', channel)).toBeNull();
      expect(await runAt(home, '0.60.99.0', 'seen', channel)).toBeNull();
    }
  }, 60_000);

  test('a brain at baseline 0.60.68 that saw the 0.60.68 notice sees only the later items, once', async () => {
    const home = freshHome();
    mkdirSync(noticeDir(home), { recursive: true });
    writeFileSync(join(noticeDir(home), 'b68.baseline'), '0.60.68.0\n');
    writeFileSync(join(noticeDir(home), 'behavior_changes_0.60.68.0.b68.cli.shown'), '2026-10-05T00:00:00.000Z\n');
    writeFileSync(join(home, 'brain-config.json'), JSON.stringify({ [HTTP_SHOWN_KEY]: JSON.stringify({ id: '[email protected]', clients: { 'client-a': '2026-10-05T00:00:00.000Z' } }) }));
    for (const channel of ['cli', 'http:client-a']) {
      const why = await runAt(home, NEWEST, 'b68', channel);
      expect(why).toContain(noticeHeader('0.60.68.0'));
      expect(why).toContain(WAVE9);
      expect(why).toContain(OPT_OUT);
      expect(why).not.toContain(V68);
      expect(why).not.toContain('v0.60.68.0');
      expect(await runAt(home, NEWEST, 'b68', channel)).toBeNull();
      expect(await runAt(home, NEXT_PATCH, 'b68', channel)).toBeNull();
    }
  }, 60_000);

  test('a brain older than 0.60.68 sees every item, labeled with its release, once', async () => {
    const home = freshHome();
    for (const channel of ['cli', 'stdio', 'http:client-a']) {
      const why = await runAt(home, NEWEST, 'old', channel);
      expect(why).toContain(noticeHeader('0'));
      expect(why).toContain(`v0.60.68.0: (1) On a managed brain`);
      expect(why).toContain(`v0.60.74.0: (4) A shell job`);
      expect(why).toContain(`v0.60.77.0: (10) think answers`);
      expect(why).toContain(`v0.60.78.0: (12) On a brain with embedding turned off`);
      expect(why).toContain(`v0.60.79.0: (13) Frontmatter is parsed as YAML 1.2`);
      expect(await runAt(home, NEWEST, 'old', channel)).toBeNull();
      expect(await runAt(home, '0.60.99.0', 'old', channel)).toBeNull();
    }
    expect(readFileSync(join(noticeDir(home), 'old.baseline'), 'utf8').trim()).toBe('0');
  }, 60_000);

  test('a fresh brain sees nothing, then or after later upgrades', async () => {
    const home = freshHome();
    for (const channel of ['cli', 'http:client-a']) {
      expect(await runAt(home, NEWEST, 'new', channel, { createdAgoMs: 0 })).toBeNull();
      expect(await runAt(home, '0.60.99.0', 'new', channel, { createdAgoMs: 2 * DAY })).toBeNull();
    }
    expect(readFileSync(join(noticeDir(home), 'new.baseline'), 'utf8').trim()).toBe(NEWEST);
  }, 60_000);
});

describe('fence rows (#6188 D25, D26)', () => {
  const NORMALIZE = 'Fixable facts and takes fences are now rewritten instead of held or refused';
  const REPAIR = 'Malformed facts and takes fences are now repaired automatically';
  const fenceRows = BEHAVIOR_CHANGES.filter(c => typeof c.text === 'string' && (c.text.startsWith(NORMALIZE) || c.text.startsWith(REPAIR)));
  const earliest = fenceRows.map(c => c.since).sort(compareReleases)[0]!;
  const before = BEHAVIOR_CHANGES.map(c => c.since).filter(v => compareReleases(v, earliest) < 0).sort(compareReleases).at(-1)!;
  const freshEngine = (createdAt: string) => ({ executeRaw: async () => [{ at: createdAt }], getConfig: async () => null }) as unknown as BrainEngine;

  test('an upgraded brain sees the never-block row and the automatic repair row, each with its opt-out, the sweep disclosure and undo guidance', async () => {
    expect(fenceRows.length).toBe(2);
    const home = freshHome();
    mkdirSync(noticeDir(home), { recursive: true });
    writeFileSync(join(noticeDir(home), 'upgraded.baseline'), `${before}\n`);
    __resetBehaviorNoticeForTests();
    await withEnv({ GBRAIN_HOME: home, ...NO_CHAIN }, async () => {
      const why = (await takeLocalBehaviorNotice(freshEngine(new Date().toISOString()), 'cli', { cfg: null, brainKey: 'upgraded' }))?.why ?? '';
      expect(why).toContain(NORMALIZE);
      expect(why).toContain(REPAIR);
      for (const command of ['gbrain config set fences.normalize false', 'gbrain config set fences.repair.llm false', 'gbrain config set fences.repair.enabled false']) {
        expect(why).toContain(command);
      }
      expect(why).toContain('its first run after upgrading repairs every malformed fence it finds in each source, rewriting and committing those files');
      expect(why).toContain('gbrain doctor --only fence_integrity');
      expect(why).toContain('`git revert` undoes it');
      expect(why).toContain('turning these settings off stops future repairs and does not undo past ones');
    });
  });

  test('a fresh install sees neither row', async () => {
    __resetBehaviorNoticeForTests();
    await withEnv({ GBRAIN_HOME: freshHome(), ...NO_CHAIN }, async () => {
      expect(await takeLocalBehaviorNotice(freshEngine(new Date().toISOString()), 'cli', { cfg: null, brainKey: 'fresh-fences' })).toBeNull();
    });
  });
});

describe('fix wave 11 rows inside the notice length cap', () => {
  const BREAKING = [
    'gbrain pages purge-deleted --dry-run --json',
    'exits 3 with an ask_user payload',
    'gbrain apply-migrations --yes',
    'drop_timeline: true',
    'gbrain sources list --json',
    'no_counterparty',
  ];

  test('an upgrade into the wave sees every breaking row and its replacement command within the rendered 2,000 characters', () => {
    const first = BEHAVIOR_CHANGES.findIndex(c => typeof c.text === 'string' && c.text.includes(BREAKING[0]!));
    expect(first).toBeGreaterThan(0);
    const after = BEHAVIOR_CHANGES[first - 1]!.since;
    const notice = behaviorChangesNotice(null, { after });
    expect(notice).not.toBeNull();
    const rendered = renderNotice(notice!, cliRenderContext()).why;
    expect(rendered.length).toBeLessThanOrEqual(2_000);
    for (const command of BREAKING) expect(rendered).toContain(command);
    expect(notice!.why).toContain('gbrain doctor --only behavior_changes shows this again.');
  });
});