Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

gbrain upgrade and stable release notes start with a short summary of what changed (#9474)

Garry Tan30b20975e463
diff --git a/behavior-changes.d/README.md b/behavior-changes.d/README.md
index 2e56f4469f..90021dc2a6 100644
--- a/behavior-changes.d/README.md
+++ b/behavior-changes.d/README.md
@@ -35,7 +35,10 @@ line and nobody picks a version before the release.
reached stable (the notice text names the reverted pull request,
`#<number>`), or `deprecation: <id>` naming the
[deprecations.d](../deprecations.d/) record whose `remove_after` date has
- passed. The front matter is not part of the notice text.
+ passed. The front matter is not part of the notice text. The kind also
+ decides where the row shows in the short summary `gbrain post-upgrade`
+ prints: `breaking` and `action` under "Needs you", `default` under
+ "Behavior changes", `fix` and `add` as counts.
That is all. `bun run check:public-surface` refuses a new row without
`kind`, and a `breaking` row without an exception or a matured deprecation.
diff --git a/changelog.d/capy-stable-notes-header.md b/changelog.d/capy-stable-notes-header.md
new file mode 100644
index 0000000000..64749bedc8
--- /dev/null
+++ b/changelog.d/capy-stable-notes-header.md
@@ -0,0 +1,6 @@
+**`gbrain upgrade` and the stable release notes now start with a short summary of the behaviour changes since the version you had.**
+
+### Added
+- Once the new version is installed, `gbrain upgrade` (through `gbrain post-upgrade`) prints the summary before its migrations run: the changes that need you first, then changed defaults, then a count of fixes and additions, and a pointer to `gbrain doctor --only behavior_changes` for the full text. Each change shows its first sentence. Under `--json` the summary goes to stderr with the other human lines, so the JSON document on stdout is unchanged.
+- When stable moves, its GitHub release notes open with the same summary for the range since the previous stable release, above the changelog entries. A summary too long for the page by itself is left out, so the notes always fit.
+- Rows written before `kind:` existed are counted as not classified yet. The generated behaviour-change table now carries each row's `kind`, so new rows land in the right group.
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
index e951b9a66a..2333082df8 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -722,8 +722,10 @@ release.yml publishes every batch release with `prerelease: true` and
release installs follow. Each promotion (`scripts/promote-stable.ts`, from the
promote dispatch or the daily check) ends by marking the promoted release
Latest and clearing its pre-release flag. A forward promotion also replaces its
-notes with every CHANGELOG entry since the previous stable, newest first; the
-oldest entries drop with a link to the full CHANGELOG once the notes would pass
+notes with a short summary of the behaviour changes since the previous stable
+(`upgradeSummary()` in `src/core/upgrade-summary.ts`, the same summary
+`gbrain post-upgrade` prints, left out when it alone would not fit), then every
+CHANGELOG entry since it, newest first; the oldest entries drop with a link to the full CHANGELOG once the notes would pass
GitHub's 125,000-character limit. A rollback keeps the notes.
A forward promotion never moves Latest to an older release than the one it
diff --git a/docs/STABILITY.md b/docs/STABILITY.md
index 126b9781ff..a3091237ce 100644
--- a/docs/STABILITY.md
+++ b/docs/STABILITY.md
@@ -112,8 +112,9 @@ Know one limit before you go back. Upgrades can move your database to a newer sc
## Where changes that need your attention are announced
- **The upgrade notice.** After an upgrade, the first command (or the first tool result an agent gets) shows a one-time `behavior_changes` notice. It lists each behaviour change in the releases you skipped over, in plain sentences, often naming the setting that turns it off. Read it again at any time with `gbrain doctor --only behavior_changes`.
+- **The upgrade summary.** Once the new version is installed, `gbrain upgrade` prints a short summary of the behaviour changes since the version you had, before its migrations run: the ones that need you first, then changed defaults, then a count of fixes and additions. Changes from before each one was given a kind are counted as not classified yet.
- **The changelog.** [CHANGELOG.md](../CHANGELOG.md) has an entry for every release.
-- **The GitHub release.** When stable moves, its GitHub release becomes "Latest" and its notes list every changelog entry since the previous stable release. While this rule is new, Latest can still point at a newer release that is not stable; that ends the first time stable passes it.
+- **The GitHub release.** When stable moves, its GitHub release becomes "Latest" and its notes open with the same short summary of behaviour changes since the previous stable release, then list every changelog entry since it. While this rule is new, Latest can still point at a newer release that is not stable; that ends the first time stable passes it.
## What the fast builds are for
diff --git a/docs/architecture/key-files/agent-contract.md b/docs/architecture/key-files/agent-contract.md
index 7a7514065b..4bb0d5d832 100644
--- a/docs/architecture/key-files/agent-contract.md
+++ b/docs/architecture/key-files/agent-contract.md
@@ -33,6 +33,7 @@ Spec: `docs/designs/AGENT_OPERATOR_WAVE.md`; wire goldens: `test/fixtures/agent-
- `src/mcp/hidden-tool-hint.ts` + `src/core/ops/cli-equivalent.ts` — F6: on the owner's stdio pipe a real tool outside the surface/read-only access gets `unknown_tool` naming itself and its CLI equivalent (`cliEquivalent`: `cliOnly` argv, curated overrides, `cliHints.name`, else `gbrain call`). Where `request_tools` is callable and session widening is on, the fix is `request_tools {surface:'full'}` (`next: run`, argv kept); otherwise the CLI equivalent with actor `user` and a `user_message`; `why` names the lasting route (`GBRAIN_SURFACE=full` in the harness's per-server env, or a `--surface full` re-registration) and that an inherited `GBRAIN_SURFACE` overrides a pinned `--surface`. Read-only access never offers a widen. HTTP stays opaque. `scripts/generate-plugin-tree.ts` appends the same map as a per-skill note to generated starter-gap skills. Test: `test/hidden-tool-hint.test.ts`. D2: `hiddenToolRoute(op, ToolConnection)` is the one decision for every transport (`callable` | `widen {surface}` | `host {read_only|surface|grant}`): a widen is offered only when the widened connection could call the tool (read-only access, `GBRAIN_MCP_FORCE_SURFACE`, the grant's snapshot/scopes and an operator pin all hold); dispatch builds the connection with `toolConnection(opts)`. `hiddenToolNext` turns a route into the D2 fix (the call itself; request_tools; on HTTP the D4 grant repair; on stdio the CLI equivalent with the call's arguments as flags).
- `Operation.cliOnly` + `cliOnlyRefusal` (`src/core/ops/callable.ts`) — F5: owner-only ops (they refuse every MCP caller) are never listed on MCP; a call gets `trusted_local_only` (error `permission_denied`) with the exact CLI command.
- `src/core/behavior-change-notice.ts` — the one-time `behavior_changes` safety notice: a live `chat_fallback_chain` (local view: entries, providers, refusal behavior, removal fix; HTTP view: only that a chain is configured), managed-brain lint repairs (`cycle.lint_fix`), smaller transcript parts re-embedded once (`TRANSCRIPT_REINGEST_MULTIPLIER`), a mention-linker rescan (v0.60.68.0), and fix wave 9's six upgrade-visible changes (v0.60.74.0). `BEHAVIOR_CHANGES` is the one table of disclosed changes, each with the release that introduced it; rows a PR adds live in `behavior-changes.d/<id>.md` and reach the table through `src/core/behavior-changes.generated.ts` (`RELEASED_BEHAVIOR_CHANGES`, spread at its end (the notice lists releases oldest first whatever the table order)) once a release dates them, and function rows use `since: releasedIn(id)` (`FENCE_REPAIR_MEASURED` is the automatic fence repair row's measurement sentence, replaced by the Tier 3 eval's measured rates); `BEHAVIOR_NOTICE_SINCE` is the newest row's release (never `VERSION`), so the notice id `behavior_changes@<since>` moves only when a release appends rows. Content: the rows newer than the last notice release this brain × channel (× HTTP client) was shown, or than its baseline when never shown. Baseline: the brain's baseline under `GBRAIN_HOME/notices/behavior-changes/<brainKey>.baseline` (`gbrain init` stamps a database it creates; otherwise the first look records `0` when `upgrade-state.json` shows an upgrade from an older release or the oldest `sources.created_at` is past `FRESH_BRAIN_GRACE_MS`). Markers: CLI and stdio claim a `wx` file per notice × brain × channel (an unwritable home still delivers, once per process); the newest marker names the last release shown; HTTP keeps up to `HTTP_SHOWN_CAP` client ids, each with the release it was shown, in the `notices.behavior_changes.http` config row (a row from an older build counts its clients as shown its id's release) (no migration; a failed write still delivers). Delivery: `completeEngineStartup` in `src/cli.ts` (stderr; not `serve` or `doctor`), and `sessionSafetyNotices` in `src/mcp/dispatch.ts` on success and failure results. `gbrain doctor --only behavior_changes` reads every row newer than the baseline without writing. Pinned by `test/behavior-c... (line truncated to 2000 chars)
+- `src/core/upgrade-summary.ts` — the short "what changed since vX" header `gbrain post-upgrade` prints: behavior-table rows after a release, grouped by their behavior-changes.d `kind:` (Needs you: breaking and action; Behavior changes: default; fix and add counted; rows without a kind counted as not classified yet), the first sentence of each, pointing at `gbrain doctor --only behavior_changes`.
- `src/core/post-upgrade-notice.ts` — F7 `post_upgrade` safety notice (contract_version + behavior-table URL): `gbrain post-upgrade` writes it once; the first stdio MCP session per upgraded version gets it (persisted under GBRAIN_HOME). `src/cli/op-notices.ts` (also `retrievalIncompleteLine`, search/query's `Retrieval incomplete:` line: `projection_pending` only when `coverage` says some pending page could match, with the count, once per window across calls) renders op notices on the local CLI (`--json` objects gain `notices`; human output on stderr).
- `src/core/ops/op-fix.ts` — Lane B builders for filled, surface-correct op errors (type-only agent-output import: ops sit in the snapshot-schema closure). `opTransport(ctx)` (cli/stdio/http from `remote`+`transport`), `paramUse(ctx, param, value?)` (`--no-pull` vs `no_pull: true`), `readFix` (diagnostic step, `mcp` + `argv`), `hostFix`/`hostOnlyError` (B6: host-only command, actor agent on CLI / user on stdio / host_admin on http with relay `user_message`), `invalidParam` (B2/B3: param, choices or type+description, one example; never echoes the raw value), `scopeDeniedError` (B5: `insufficient_scope`, frozen `error` via `legacy_error`, client id + current scopes in `why`, the exact `gbrain auth rescope`/`rescope-token` command, consent `credentials`). Test: `test/op-fix.test.ts`, `test/scope-denial-contract.test.ts`.
- `src/core/persistence/page-identity.ts` — B4: `pageIdentityError(present, msg)` (a deleted page throws canonical `page_not_found` with the frozen wire/journal `error` `page_identity_changed`; a replaced page keeps `page_identity_changed`), `isMissingPageMessage` (replays recover the distinction from the stored message; no schema change), `yamlLocator` (content-free ` at line L, column C`). Replays (`writeResponse` in `persistence/service.ts`) set `OperationError.receiptFields` (never serialized); `toAgentError` fills the registry fix template (`{slug}`/`{source_id}`/`{request_id}`/`{operation}`, strict per-field patterns, unfillable → dropped) and applies the principal-aware receipt rule (CLI principal → `gbrain write-request`; same-principal MCP → `get_write_request` when callable; otherwise host inspection, actor host_admin). Test: `test/write-receipt-remediation.test.ts`.
diff --git a/llms-full.txt b/llms-full.txt
index c65cb41595..94d47d4d6f 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -2899,8 +2899,9 @@ Know one limit before you go back. Upgrades can move your database to a newer sc
## Where changes that need your attention are announced
- **The upgrade notice.** After an upgrade, the first command (or the first tool result an agent gets) shows a one-time `behavior_changes` notice. It lists each behaviour change in the releases you skipped over, in plain sentences, often naming the setting that turns it off. Read it again at any time with `gbrain doctor --only behavior_changes`.
+- **The upgrade summary.** Once the new version is installed, `gbrain upgrade` prints a short summary of the behaviour changes since the version you had, before its migrations run: the ones that need you first, then changed defaults, then a count of fixes and additions. Changes from before each one was given a kind are counted as not classified yet.
- **The changelog.** [CHANGELOG.md](../CHANGELOG.md) has an entry for every release.
-- **The GitHub release.** When stable moves, its GitHub release becomes "Latest" and its notes list every changelog entry since the previous stable release. While this rule is new, Latest can still point at a newer release that is not stable; that ends the first time stable passes it.
+- **The GitHub release.** When stable moves, its GitHub release becomes "Latest" and its notes open with the same short summary of behaviour changes since the previous stable release, then list every changelog entry since it. While this rule is new, Latest can still point at a newer release that is not stable; that ends the first time stable passes it.
## What the fast builds are for
diff --git a/scripts/build-behavior-changes.ts b/scripts/build-behavior-changes.ts
index be54df67e1..bf935206df 100644
--- a/scripts/build-behavior-changes.ts
+++ b/scripts/build-behavior-changes.ts
@@ -124,6 +124,7 @@ export function build(root: string): Built {
const files = existsSync(join(root, FRAGMENT_DIR)) ? readdirSync(join(root, FRAGMENT_DIR)).filter(f => f !== 'README.md').sort() : [];
const texts = new Map<string, string>();
+ const kinds = new Map<string, string>();
for (const f of files) {
const id = f.replace(/\.md$/, '');
if (!f.endsWith('.md') || !ID.test(id)) { problems.push(`${FRAGMENT_DIR}/${f}: a fragment is named <id>.md, the id lowercase letters, digits and _, starting with a letter (3-96 characters)`); continue; }
@@ -134,6 +135,7 @@ export function build(root: string): Built {
else if (text.length > NOTICE_CAP) problems.push(`${FRAGMENT_DIR}/${f} is ${text.length} characters; the notice renders at most ${NOTICE_CAP}`);
else if (/<!--|^---/.test(text)) problems.push(`${FRAGMENT_DIR}/${f} holds markup; it is the notice text only`);
texts.set(id, text);
+ if (parsed.front.kind) kinds.set(id, parsed.front.kind);
}
const table = tableIds(read(root, NOTICE_FILE));
for (const id of texts.keys()) {
@@ -145,14 +147,14 @@ export function build(root: string): Built {
}
for (const id of table.tbd) if (!sinceOf.has(id) && !pendingIds.has(id)) problems.push(`the releasedIn('${id}') row in ${NOTICE_FILE} has no <!-- behavior-change: ${id} --> marker, so no release would date it`);
- const rows = order.filter(id => texts.has(id)).map(id => ` { since: '${sinceOf.get(id)}', id: '${id}', text: ${JSON.stringify(texts.get(id))} },`);
+ const rows = order.filter(id => texts.has(id)).map(id => ` { since: '${sinceOf.get(id)}', id: '${id}', ${kinds.has(id) ? `kind: '${kinds.get(id)}', ` : ''}text: ${JSON.stringify(texts.get(id))} },`);
const map = order.map(id => ` ${id}: '${sinceOf.get(id)}',`);
const text = [
'// Generated by scripts/build-behavior-changes.ts from behavior-changes.d/ and the CHANGELOG markers; do not edit.',
'// Regenerate: bun scripts/build-behavior-changes.ts (the release does it). Docs: behavior-changes.d/README.md',
'',
'/** The plain-text rows of behavior-changes.d/, each dated by the release whose CHANGELOG section marks it. */',
- 'export const RELEASED_BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; id: string; text: string }> = [',
+ 'export const RELEASED_BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; id: string; kind?: string; text: string }> = [',
...rows,
'];',
'',
diff --git a/scripts/promote-stable.ts b/scripts/promote-stable.ts
index 1fce2aa5e5..ada405e50f 100644
--- a/scripts/promote-stable.ts
+++ b/scripts/promote-stable.ts
@@ -43,8 +43,9 @@
* 8. the release's GitHub release is marked "Latest" (pre-release cleared):
* release.yml publishes every batch release as a pre-release, so the
* stable channel is the one release GitHub calls Latest. A forward
- * promotion replaces its notes with every CHANGELOG entry since the
- * previous stable (rolledUpNotes()); a rollback keeps the notes. If this
+ * promotion replaces its notes with a short summary of the behavior
+ * changes since the previous stable (upgradeSummary()), then every
+ * CHANGELOG entry since it (rolledUpNotes()); a rollback keeps the notes. If this
* last step fails, stable has already moved: the refusal names
* `bun scripts/release-channel.ts backfill --apply`, which sets it.
*
@@ -63,6 +64,7 @@ import { spawnSync } from 'node:child_process';
import { appendFileSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
+import { upgradeSummary } from '../src/core/upgrade-summary.ts';
import { judgeMatrixRun, MATRIX_RECEIPT_ARTIFACT, type BreakIssue, type MatrixReceipt, type MatrixRunRow } from './stable-matrix.ts';
export const DOCS = 'docs/RELEASING.md#stable-channel-promotion';
@@ -500,7 +502,7 @@ export async function promote(deps: PromoteDeps, inputs: PromoteInputs): Promise
};
const message = renderTagMessage(fields);
const changelog = rollback ? null : await deps.git(['show', `${releaseRef}:CHANGELOG.md`]);
- const notes = changelog === null ? null : rolledUpNotes(changelog.code === 0 ? changelog.stdout : '', fields.previous, version, deps.repo);
+ const notes = changelog === null ? null : rolledUpNotes(changelog.code === 0 ? changelog.stdout : '', fields.previous, version, deps.repo, fields.previous ? upgradeSummary(fields.previous, version) : null);
// The evidence record: carried forward from the previous record commit (none before the first promotion).
const prior = await readPriorRecord(deps);
@@ -560,9 +562,10 @@ export const RELEASE_NOTES_MAX = 120_000;
* The stable release's notes: every CHANGELOG.md section newer than `previous` up to and including `version`, newest
* first, under one line naming the previous stable. Oldest sections drop first when the roll-up would pass
* RELEASE_NOTES_MAX, and a link to the full CHANGELOG at the tag says so. With no previous stable it is the release's
- * own entry; with no matching section it is the same link stub release.yml writes.
+ * own entry; with no matching section it is the same link stub release.yml writes. The behavior-change summary sits
+ * under the opening line, and is left out when it alone would pass RELEASE_NOTES_MAX.
*/
-export function rolledUpNotes(changelog: string, previous: string | null, version: string, repo: string): string {
+export function rolledUpNotes(changelog: string, previous: string | null, version: string, repo: string, summary: string[] | null = null): string {
const link = `https://github.com/${repo}/blob/v${version}/CHANGELOG.md`;
const wanted = (v: string) => compareVersions(v, version) <= 0 && (previous === null ? compareVersions(v, version) === 0 : compareVersions(v, previous) > 0);
const sections: string[][] = [];
@@ -577,7 +580,9 @@ export function rolledUpNotes(changelog: string, previous: string | null, versio
current?.push(line);
}
if (sections.length === 0) return `See [CHANGELOG.md](${link}) for v${version}.\n`;
- const intro = previous === null ? `Stable release v${version}.\n` : `Stable release v${version}: every change since the previous stable release, v${previous}, newest first.\n`;
+ const opening = previous === null ? `Stable release v${version}.\n` : `Stable release v${version}: every change since the previous stable release, v${previous}, newest first.\n`;
+ const summarized = summary ? `${opening}\n${summary.join('\n')}\n` : opening;
+ const intro = summarized.length + 200 > RELEASE_NOTES_MAX ? opening : summarized;
const bodies = sections.map(s => `${s.join('\n').trimEnd()}\n`);
const kept: string[] = [];
let size = intro.length;
diff --git a/src/commands/upgrade.ts b/src/commands/upgrade.ts
index b57ba5336e..5191bd0933 100644
--- a/src/commands/upgrade.ts
+++ b/src/commands/upgrade.ts
@@ -890,6 +890,8 @@ export async function runPostUpgrade(args: string[] = []): Promise<void> {
const state = JSON.parse(readFileSync(statePath, 'utf-8'));
const from = state?.last_upgrade?.from;
if (from) {
+ const summary = (await import('../core/upgrade-summary.ts')).upgradeSummary(from);
+ if (summary) console.log(['', ...summary, ''].join('\n'));
const { migrations } = await import('./migrations/index.ts');
for (const m of migrations) {
if (isNewerThan(m.version, from)) {
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 800fffa983..ff31b9bd7b 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -231,7 +231,7 @@ const releasedIn = (id: string): string => (Object.hasOwn(BEHAVIOR_CHANGE_RELEAS
* row is a behavior-changes.d/<id>.md fragment (RELEASED_BEHAVIOR_CHANGES once a release dates it); a new function row
* goes here as `{ since: releasedIn('<id>'), id: '<id>', text: ... }`.
*/
-export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText; id?: string }> = [
+export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText; id?: string; kind?: string }> = [
{ since: '0.60.68.0', text: (chain, remote) => {
if (!chain) return null;
if (remote) return 'A chat fallback chain is configured on this brain host: when a chat call\'s own model fails it is retried on other models. Its entries and providers are visible to the brain host operator in gbrain doctor --only chat_fallback_chain.';
diff --git a/src/core/behavior-changes.generated.ts b/src/core/behavior-changes.generated.ts
index 4ea5568674..6f510b60b7 100644
--- a/src/core/behavior-changes.generated.ts
+++ b/src/core/behavior-changes.generated.ts
@@ -2,7 +2,7 @@
// Regenerate: bun scripts/build-behavior-changes.ts (the release does it). Docs: behavior-changes.d/README.md
/** The plain-text rows of behavior-changes.d/, each dated by the release whose CHANGELOG section marks it. */
-export const RELEASED_BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; id: string; text: string }> = [
+export const RELEASED_BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; id: string; kind?: string; text: string }> = [
{ since: '0.60.706.0', id: 'db_wins_unimported_gst2579', text: "A database-wins file-drift repair no longer overwrites a newer change to the file that sync has not imported. `gbrain repair file-drift --prefer database` by `--held` or `--all-drifted` now lists such a page `kept_newer_file` (a file edited since the last import) or `kept_newer_delete` (a file another writer deleted) and leaves it held; naming the page with `--slug` previews it and names the commit it would discard (sha, author, date). Every file-drift apply now asks for the user's consent, so a script that applies without `--yes` exits 3. `gbrain sources reconcile --apply` refuses `source_changed` when its result takes the database copy over such an edit. A database copy newer than the file (the file still holds what sync imported, or gbrain's own write of a revision the page has since moved past) repairs as before; gbrain's own writer commit of a revision the database never took counts as newer. The keep_db policy is unchanged." },
{ since: '0.60.708.0', id: 'extract_receipt_sealed_7620', text: "An extraction run's receipt page (type `extract_receipt`, under `extracts/`) is now chunked and sealed in the transaction that writes it. Remote/MCP `search` and `query` on the extracted source no longer report `safe_index_pending` or `projection_pending` after every extraction, doctor `safe_index_pending` no longer counts new receipts, and remote readers can now find receipts like other generated pages (demoted in ranking). Receipts an earlier release wrote stay unsealed until `gbrain repair safe-chunks --apply`. A receipt is database-only bookkeeping on every brain, with or without a Git repository: when its slug already holds a content page or a page with a file in Git, the receipt is not written (the extraction logs a warning and carries on) instead of overwriting that page." },
{ since: '0.60.708.0', id: 'commit_push_dry_run_checks_paths', text: "`gbrain git commit-push --dry-run` now asks git about the planned paths the way the real run stages them, and runs the real run's checks before staging, so it exits 1 with the real run's code and text where that run would refuse (`commit_outside_source_root` for a path outside `gbrain.sourceRoot` unless `--allow-outside-source-root` is passed, `commit_prestaged_paths`, and `commit_paths_invalid` for a path outside a sparse-checkout definition or one that matches nothing) instead of exiting 0 and listing it. It still takes no lock and writes nothing." },
@@ -90,7 +90,7 @@ export const RELEASED_BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; id: strin
{ since: '0.60.725.0', id: 'notifier_sync_disabled_gst2515', text: "The commit notifier now honours a source's sync setting: a source with sync turned off (config.syncEnabled=false) is no longer synced when HEAD moves, and a retry it owed is dropped. An explicit sync request (a sync trigger or webhook) still runs once; if that run fails, the notifier waits for a new request instead of retrying it. To have commits sync that source again, turn sync back on with gbrain sources set-sync <id> on." },
{ since: '0.60.726.0', id: 'transcript_archive_default_gst2768', text: "On a personal brain the conversation archive is now on: the maintenance pass (the idle upkeep of an agent's gbrain serve, gbrain maintain --unattended or its schedule, and autopilot) writes one redacted page per conversation per local day from your Claude Code, Codex, OpenClaw, Hermes and Grok sessions, plus a day index, into the conversations source, then fills in older days a capped run at a time. To turn it off, run gbrain transcripts archive off (pages already written stay). A shared team brain is only offered the archive and stays off until its owner runs gbrain transcripts archive on. On a keyless brain nothing leaves this machine. With an embedding key, the archived text of new days is sent to that provider to be embedded, like any new page (unattended upkeep caps that at maintenance.embed_daily_usd; autopilot and a managed brain's write coordinator embed new pages as they arrive); older history is written keyword-only and its embedding waits until you see the price with gbrain embed --held --dry-run and approve it. No facts are extracted and no Dream synthesis runs on archive pages. gbrain doctor --only transcript_archive_freshness says whether the archive is keeping up." },
{ since: '0.60.731.0', id: 'stable_important_three_classes_gst2818', text: "The stable channel now moves within a day only for a security fix, a data-loss fix or a fix for a regression in a release that is already on stable. Everything else, a fix that only unblocks one setup included, waits for the weekly move; if you need such a fix sooner, install its release by tag (docs/STABILITY.md, \"Pinning a version\")." },
- { since: '0.60.732.0', id: 'owner_purge_tombstones_survive_9469', text: "A page the owner purged while a derived page kept it private now gets its purge records whichever later run removes it (an automatic expiry purge, or a run after a failed or deferred one), on repo brains and on brains without a repository, so a restore no longer brings it back. Restoring a backup now removes the same rows a live page purge removes (write requests, files, derived generation items and their effects), not only the page itself, and stops with purge_replay_incomplete, naming the purge it could not replay, instead of reporting success on a partial sweep. A new doctor warning, purge_mirror, says when recent purges are missing from this machine's purge mirror, so restoring an older backup would not replay them (#9469)." },
+ { since: '0.60.732.0', id: 'owner_purge_tombstones_survive_9469', kind: 'fix', text: "A page the owner purged while a derived page kept it private now gets its purge records whichever later run removes it (an automatic expiry purge, or a run after a failed or deferred one), on repo brains and on brains without a repository, so a restore no longer brings it back. Restoring a backup now removes the same rows a live page purge removes (write requests, files, derived generation items and their effects), not only the page itself, and stops with purge_replay_incomplete, naming the purge it could not replay, instead of reporting success on a partial sweep. A new doctor warning, purge_mirror, says when recent purges are missing from this machine's purge mirror, so restoring an older backup would not replay them (#9469)." },
];
/** The release of every marked id, so a function row dated releasedIn(id) takes the release that disclosed it. */
diff --git a/src/core/upgrade-summary.ts b/src/core/upgrade-summary.ts
new file mode 100644
index 0000000000..b63caf6e2c
--- /dev/null
+++ b/src/core/upgrade-summary.ts
@@ -0,0 +1,53 @@
+/**
+ * The short "what changed for you" header shown by `gbrain post-upgrade` and
+ * on stable release notes: the behavior changes between two releases, grouped
+ * by the `kind:` each behavior-changes.d row declares (behavior-changes.d/README.md).
+ * Rows from before kinds existed count as not yet classified.
+ */
+import { BEHAVIOR_CHANGES, compareReleases } from './behavior-change-notice.ts';
+
+export interface SummaryRow { since: string; kind?: string; text: string }
+
+const ENTRY_MAX = 240;
+const DOCTOR = 'gbrain doctor --only behavior_changes';
+
+function firstSentence(text: string): string {
+ const sentence = text.split(/(?<=[.!?])\s+(?=[A-Z`(])/)[0]!;
+ return sentence.length > ENTRY_MAX ? `${sentence.slice(0, ENTRY_MAX - 1).trimEnd()}…` : sentence;
+}
+
+const plural = (n: number, one: string, many: string) => `${n} ${n === 1 ? one : many}`;
+
+/** The header lines for rows released after `after`, up to and including `upTo`; null when none apply. */
+export function changeSummary(rows: ReadonlyArray<SummaryRow>, after: string, upTo?: string): string[] | null {
+ const inRange = rows.filter(r => compareReleases(r.since, after) > 0 && (!upTo || compareReleases(r.since, upTo) <= 0));
+ if (inRange.length === 0) return null;
+ const of = (...kinds: string[]) => inRange.filter(r => kinds.includes(r.kind ?? ''));
+ const needsYou = of('breaking', 'action');
+ const changed = of('default');
+ const fixes = of('fix').length;
+ const additions = of('add').length;
+ const unclassified = inRange.filter(r => !r.kind).length;
+ const lines = [`What changed since v${after}: ${plural(inRange.length, 'change', 'changes')}.`];
+ const group = (title: string, list: SummaryRow[]) => {
+ if (list.length === 0) return;
+ lines.push('', `${title} (${list.length}):`, ...list.map(r => `- ${firstSentence(r.text)}`));
+ };
+ group('Needs you', needsYou);
+ group('Behavior changes', changed);
+ const tail: string[] = [];
+ if (fixes + additions > 0) tail.push(`Plus ${plural(fixes, 'fix', 'fixes')} and ${plural(additions, 'addition', 'additions')}.`);
+ if (unclassified > 0) tail.push(`${plural(unclassified, 'change is', 'changes are')} not classified yet.`);
+ tail.push(`\`${DOCTOR}\` lists every change in full.`);
+ lines.push('', tail.join(' '));
+ return lines;
+}
+
+/** The header for this binary's own behavior table since release `from`. */
+export function upgradeSummary(from: string, upTo?: string): string[] | null {
+ const rows = BEHAVIOR_CHANGES.flatMap(c => {
+ const text = typeof c.text === 'string' ? c.text : c.text(null, false);
+ return text ? [{ since: c.since, kind: c.kind, text }] : [];
+ });
+ return changeSummary(rows, from, upTo);
+}
diff --git a/test/scripts/build-behavior-changes.test.ts b/test/scripts/build-behavior-changes.test.ts
index b5ad0ddae1..d1f4d175db 100644
--- a/test/scripts/build-behavior-changes.test.ts
+++ b/test/scripts/build-behavior-changes.test.ts
@@ -35,7 +35,7 @@ function run(root: string, argv: string[]): { code: number; out: string } {
return { code, out: lines.join('\n') };
}
-const rowsOf = (text: string) => [...text.matchAll(/^ {2}\{ since: '([^']+)', id: '([^']+)', text: (".*") \},$/gm)].map((m) => ({ since: m[1], id: m[2], text: JSON.parse(m[3]!) }));
+const rowsOf = (text: string) => [...text.matchAll(/^ {2}\{ since: '([^']+)', id: '([^']+)', (?:kind: '([a-z-]+)', )?text: (".*") \},$/gm)].map((m) => ({ since: m[1], id: m[2], ...(m[3] ? { kind: m[3] } : {}), text: JSON.parse(m[4]!) }));
const releasesOf = (text: string) => Object.fromEntries([...text.matchAll(/^ {2}([a-z0-9_]+): '([^']+)',$/gm)].map((m) => [m[1], m[2]]));
describe('build()', () => {
@@ -69,7 +69,7 @@ describe('build()', () => {
'behavior-changes.d/bad_kind_abc.md': '---\nkind: sideways\nexception: data-loss\nowner: someone\n---\nText.\n',
});
const { text, problems } = build(root);
- expect(rowsOf(text).find((r) => r.id === 'kinded_row_abc')?.text).toBe('A kinded change.');
+ expect(rowsOf(text).find((r) => r.id === 'kinded_row_abc')).toEqual({ since: '0.1.0.0', id: 'kinded_row_abc', kind: 'breaking', text: 'A kinded change.' });
expect(problems).toEqual([
'behavior-changes.d/bad_kind_abc.md: front matter line "owner: someone" is not one of kind, exception, deprecation',
'behavior-changes.d/bad_kind_abc.md: kind: sideways is not one of breaking, action, default, fix, add',
diff --git a/test/scripts/promote-stable.test.ts b/test/scripts/promote-stable.test.ts
index 14282ffb7e..6e1c41ffe8 100644
--- a/test/scripts/promote-stable.test.ts
+++ b/test/scripts/promote-stable.test.ts
@@ -24,6 +24,7 @@ import {
} from '../../scripts/promote-stable.ts';
import type { MatrixReceipt } from '../../scripts/stable-matrix.ts';
import { offeredVersion } from '../../src/core/self-upgrade.ts';
+import { upgradeSummary } from '../../src/core/upgrade-summary.ts';
import { RECORD_MAX_BYTES } from '../../src/core/stable-channel.ts';
import { parseStableRecord } from '../../src/core/stable-channel.ts';
@@ -858,6 +859,27 @@ describe('GitHub Latest release', () => {
expect(rolledUpNotes('', '0.60.360.0', '0.60.361.0', REPO)).toBe(`See [CHANGELOG.md](https://github.com/${REPO}/blob/v0.60.361.0/CHANGELOG.md) for v0.60.361.0.\n`);
});
+ test('rolledUpNotes puts the behavior-change summary between the opening line and the entries', () => {
+ const notes = rolledUpNotes(CHANGELOG, '0.60.360.0', '0.60.361.0', REPO, ['What changed since v0.60.360.0: 1 change.', '', 'Needs you (1):', '- Run gbrain sync once.']);
+ expect(notes.split('\n').slice(0, 6)).toEqual([
+ 'Stable release v0.60.361.0: every change since the previous stable release, v0.60.360.0, newest first.',
+ '',
+ 'What changed since v0.60.360.0: 1 change.',
+ '',
+ 'Needs you (1):',
+ '- Run gbrain sync once.',
+ ]);
+ expect(notes.indexOf('- Run gbrain sync once.')).toBeLessThan(notes.indexOf('## [0.60.361.0]'));
+ });
+
+ test('rolledUpNotes leaves out a summary that alone would pass GitHub\'s size limit', () => {
+ const summary = ['What changed since v0.60.360.0: 1000 changes.', '', 'Needs you (1000):', ...Array.from({ length: 1000 }, () => `- ${'x'.repeat(240)}`)];
+ const notes = rolledUpNotes(CHANGELOG, '0.60.360.0', '0.60.361.0', REPO, summary);
+ expect(notes.length).toBeLessThanOrEqual(RELEASE_NOTES_MAX);
+ expect(notes).not.toContain('Needs you (1000):');
+ expect(notes).toBe(rolledUpNotes(CHANGELOG, '0.60.360.0', '0.60.361.0', REPO));
+ });
+
test('rolledUpNotes drops the oldest entries past GitHub\'s size limit and links the rest', () => {
const big = (v: string) => [`## [${v}] - 2026-10-21`, '', 'x'.repeat(50_000), ''].join('\n');
const notes = rolledUpNotes(['0.60.363.0', '0.60.362.0', '0.60.361.0'].map(big).join('\n'), '0.60.360.0', '0.60.363.0', REPO);
@@ -873,7 +895,8 @@ describe('GitHub Latest release', () => {
await promote(h.deps, inputs());
expect(h.writes).toHaveLength(1);
expect(h.writes[0]).toMatchObject({ method: 'PATCH', path: `repos/${REPO}/releases/42`, body: { prerelease: false, make_latest: 'true' } });
- expect(h.writes[0]!.body.body).toBe(rolledUpNotes(CHANGELOG, '0.60.360.0', '0.60.361.0', REPO));
+ expect(h.writes[0]!.body.body).toBe(rolledUpNotes(CHANGELOG, '0.60.360.0', '0.60.361.0', REPO, upgradeSummary('0.60.360.0', '0.60.361.0')));
+ expect(h.writes[0]!.body.body).toContain('gbrain doctor --only behavior_changes');
expect(h.calls.findIndex(c => c.startsWith('push'))).toBeGreaterThanOrEqual(0);
expect(h.logs.at(-1)).toContain('the GitHub release v0.60.361.0 is now Latest, with notes rolled up');
});
diff --git a/test/upgrade-summary.test.ts b/test/upgrade-summary.test.ts
new file mode 100644
index 0000000000..4e8d45b9d3
--- /dev/null
+++ b/test/upgrade-summary.test.ts
@@ -0,0 +1,70 @@
+import { afterAll, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { changeSummary, upgradeSummary } from '../src/core/upgrade-summary.ts';
+
+const rows = [
+ { since: '0.1.0.0', kind: 'breaking', text: 'Too old to show.' },
+ { since: '0.1.1.0', kind: 'breaking', text: 'The --old flag is gone. Use --new instead.' },
+ { since: '0.1.1.0', kind: 'action', text: 'Run `gbrain sync` once after upgrading.' },
+ { since: '0.1.2.0', kind: 'default', text: 'Search now ranks recent pages first.' },
+ { since: '0.1.2.0', kind: 'fix', text: 'A fix.' },
+ { since: '0.1.2.0', kind: 'add', text: 'An addition.' },
+ { since: '0.1.2.0', kind: 'add', text: 'Another addition.' },
+ { since: '0.1.2.0', text: 'A row from before kinds.' },
+ { since: '0.1.3.0', kind: 'breaking', text: 'Not released yet.' },
+];
+
+describe('changeSummary', () => {
+ test('groups the rows after from, up to upTo, by kind', () => {
+ expect(changeSummary(rows, '0.1.0.0', '0.1.2.0')).toEqual([
+ 'What changed since v0.1.0.0: 7 changes.',
+ '',
+ 'Needs you (2):',
+ '- The --old flag is gone.',
+ '- Run `gbrain sync` once after upgrading.',
+ '',
+ 'Behavior changes (1):',
+ '- Search now ranks recent pages first.',
+ '',
+ 'Plus 1 fix and 2 additions. 1 change is not classified yet. `gbrain doctor --only behavior_changes` lists every change in full.',
+ ]);
+ });
+
+ test('omits empty groups and counts; null when nothing is in range', () => {
+ expect(changeSummary([{ since: '0.2.0.0', text: 'Old row.' }], '0.1.0.0')).toEqual([
+ 'What changed since v0.1.0.0: 1 change.',
+ '',
+ '1 change is not classified yet. `gbrain doctor --only behavior_changes` lists every change in full.',
+ ]);
+ expect(changeSummary(rows, '0.1.3.0')).toBeNull();
+ });
+
+ test('cuts a long first sentence', () => {
+ const line = changeSummary([{ since: '0.2.0.0', kind: 'action', text: `${'word '.repeat(80)}end.` }], '0.1.0.0')![3]!;
+ expect(line.length).toBe(242);
+ expect(line.endsWith('…')).toBe(true);
+ });
+
+ test('upgradeSummary reads this binary\'s table, function rows included', () => {
+ const lines = upgradeSummary('0')!;
+ expect(lines[0]).toMatch(/^What changed since v0: \d+ changes\.$/);
+ expect(lines.at(-1)).toContain('gbrain doctor --only behavior_changes');
+ });
+});
+
+describe('gbrain post-upgrade', () => {
+ const home = mkdtempSync(join(tmpdir(), 'gbrain-upgrade-summary-'));
+ afterAll(() => rmSync(home, { recursive: true, force: true }));
+
+ test('prints the header for the changes since the release it upgraded from', () => {
+ mkdirSync(join(home, '.gbrain'), { recursive: true });
+ writeFileSync(join(home, '.gbrain', 'upgrade-state.json'), JSON.stringify({ last_upgrade: { from: '0' } }));
+ const { DATABASE_URL: _d, GBRAIN_DATABASE_URL: _g, ...env } = process.env;
+ const run = Bun.spawnSync(['bun', join(import.meta.dir, '..', 'src', 'cli.ts'), 'post-upgrade', '--no-autopilot-install'], {
+ env: { ...env, GBRAIN_HOME: home, GBRAIN_NO_AUTOPILOT_INSTALL: '1' }, stdout: 'pipe', stderr: 'pipe',
+ });
+ expect(run.stdout.toString()).toContain(upgradeSummary('0')!.join('\n'));
+ }, 60_000);
+});