Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Stable moves within a day only for security, data-loss and stable-regression fixes (GST-2818) (#9461)
Garry Tanddb2537c416e
diff --git a/behavior-changes.d/stable_important_three_classes_gst2818.md b/behavior-changes.d/stable_important_three_classes_gst2818.mdnew file mode 100644index 0000000000..9556f6739e--- /dev/null+++ b/behavior-changes.d/stable_important_three_classes_gst2818.md@@ -0,0 +1 @@+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").diff --git a/changelog.d/README.md b/changelog.d/README.mdindex 688e1d1c83..3f13bbed75 100644--- a/changelog.d/README.md+++ b/changelog.d/README.md@@ -16,8 +16,11 @@ of the GitHub release notes.```Optional front matter marks the change important for the stable channel-(`important: security|regression|data-loss|blocker`), which makes the merge-lane open a release right after it lands the PR. Releases are PATCH only, so+(`important: security|regression|data-loss`, where regression means a+regression in a release that is on stable), which makes the merge lane open a+release right after it lands the PR. Any other class is refused+(docs/RELEASING.md#daily-stable-check); a fix that only unblocks someone rides+the weekly cut. Releases are PATCH only, soa `bump:` line other than `patch` is refused (scripts/build-behavior-changes.ts).A PR that changes behavior also names its behavior-changes.d row here(`<!-- behavior-change: <id> -->`, see behavior-changes.d/README.md).diff --git a/changelog.d/stable-important-three-classes.md b/changelog.d/stable-important-three-classes.mdnew file mode 100644index 0000000000..25f1e16e6a--- /dev/null+++ b/changelog.d/stable-important-three-classes.md@@ -0,0 +1,8 @@+**Stable moves within a day only for security, data-loss and stable-regression fixes; everything else waits for the weekly move.**++### Changed+- An important fix, the kind that moves the stable channel early, is now only a security fix, a data-loss fix or a fix for a regression in a release that is on stable. A fix that unblocks one setup, or a regression only alpha releases have, rides the weekly move unless a maintainer promotes by hand. `gbrain upgrade --help`, docs/STABILITY.md, docs/RELEASING.md ("Daily stable check") and changelog.d/README.md say so.+- `scripts/build-behavior-changes.ts` (in `check:regen-all`) refuses a changelog fragment whose `important:` class is anything but `security`, `regression` or `data-loss`, naming the three and docs/RELEASING.md#daily-stable-check, the same way it refuses a `bump:` other than `patch`. A `# comment` after a front-matter value is no longer read as part of it.+- Tests: `test/scripts/build-behavior-changes.test.ts` covers the refused and accepted `important:` values.++<!-- behavior-change: stable_important_three_classes_gst2818 -->diff --git a/docs/RELEASING.md b/docs/RELEASING.mdindex 9d94b98366..d4e7ba3f8c 100644--- a/docs/RELEASING.md+++ b/docs/RELEASING.md@@ -159,9 +159,10 @@ reader of the log should see.- `changelog.d/<branch-slug>.md`: the PR's CHANGELOG entry with no versionheading (bold one-line summary, then the itemized sections; voice rulesbelow). /ship writes it. Front matter may say- `important: security|regression|data-loss|blocker`; releases are PATCH+ `important: security|regression|data-loss`, where regression means one in+ a release that is on stable ("Daily stable check"); releases are PATCHonly, so `scripts/build-behavior-changes.ts` (in `check:regen-all`) refuses- a `bump:` line other than `patch`. Format:+ a `bump:` line other than `patch` and any other `important:` class. Format:[changelog.d/README.md](../changelog.d/README.md).- One `behavior-changes.d/<id>.md` file per new upgrade-notice row, namedin the fragment as `<!-- behavior-change: <id> -->`@@ -883,9 +884,14 @@ and keeps stable between one day and one week behind what matters:- **Reason first.** It acts only when a merged PR labelled `stable:important` is in apublished release but not in stable, or stable is more than 7 days old anda newer release exists (the weekly floor). Otherwise it does nothing. The- merge lane sets the label at merge on a security, regression or data-loss- fix, or a fix for something that blocks a crew or a user (on a train PR,- the train carries it); a label added after the merge counts too.+ merge lane sets the label at merge on a security fix, a data-loss fix or a+ fix for a regression in a release that is on stable (on a train PR, the+ train carries it); a label added after the merge counts too. Anything else,+ a regression only alpha has or a fix that unblocks one setup included, rides+ the weekly floor unless a maintainer promotes by hand. The rule: an+ important fix reaches stable within a day once it passes the full gate and+ soak; everything else rides a weekly cut; stable never sits more than seven+ days behind gated changes on master.- **Soak first.** The candidate is the newest release newer than stable whosecommit is on master and whose exact tree passed a successful`STABLE_SOAK_WORKFLOW` run with the integrity gates (`privacy_leaks`,diff --git a/docs/STABILITY.md b/docs/STABILITY.mdindex 71d55425ca..f451321a63 100644--- a/docs/STABILITY.md+++ b/docs/STABILITY.md@@ -39,7 +39,7 @@ Since 16 November 2026, stable comes with a written promise about what a script1. **Every release passes the full test suite first.** A release is published only after the full unit and end-to-end test runs pass on its exact code.2. **A stable candidate then passes a production-shaped test.** gbrain runs a two-hour load test on a brain of 600,000 pages, at two network delays (2 ms and 65 ms), with privacy probes. It must pass the privacy-leak, read-error, version-skew, process-health and session checks in every run. The test has to have run on the release's exact files; a test of a nearby commit doesn't count.3. **Stable moves only for a reason.** A scheduled check runs twice a day (05:17 and 13:17 UTC). It promotes the newest release that passed step 2, and only when there is a reason to move:- - an important fix (a security, regression or data-loss fix, or a fix for something that blocks people) has been released but is not in stable yet, or+ - an important fix (a security fix, a data-loss fix, or a fix for a regression in a release that is on stable) has been released but is not in stable yet, or- stable is more than 7 days old and a newer release exists.With no reason, stable stays where it is.@@ -47,9 +47,9 @@ Since 16 November 2026, stable comes with a written promise about what a script## How often stable moves-The scheduled check can move it at most twice a day; a maintainer can also promote, or roll back, by hand. An important fix can move it on any day. If nothing important is waiting, the 7-day rule is the next reason for stable to move, though it still waits for a release that passed the test in step 2.+The rule: an important fix reaches stable within a day once it has passed the full test suite and the load test in step 2; everything else rides a weekly move; and stable never sits more than seven days behind tested changes. The scheduled check can move it at most twice a day; a maintainer can also promote, or roll back, by hand. If nothing important is waiting, the 7-day rule is the next reason for stable to move, though it still waits for a release that passed the test in step 2. A fix for a problem only newer, non-stable releases have, or one that unblocks a single setup, waits for the weekly move; if you need it sooner, install that release by its tag (see "Pinning a version").-What that has meant so far: the first stable release was v0.60.474.0 on 28 October 2026. Between then and 15 November 2026 stable moved 9 more times: once on 6 November, 9.7 days later, and then on each of the 8 days from 8 to 15 November, because an important fix was waiting on each of those days. Each move carried every change released since the one before. To see the current pace, list every stable release:+What that has meant so far: the first stable release was v0.60.474.0 on 28 October 2026. Between then and 15 November 2026 stable moved 9 more times: once on 6 November, 9.7 days later, and then on each of the 8 days from 8 to 15 November, because an important fix was waiting on each of those days. Each move carried every change released since the one before. Until then an important fix also included a fix for something that blocked people. From the release that carries this change on (decided 16 November 2026), only security, data-loss and stable-regression fixes move stable early, so expect it to move about once a week. To see the current pace, list every stable release:```bashgit ls-remote --tags --refs https://github.com/garrytan/gbrain 'refs/tags/stable-v*'diff --git a/llms-full.txt b/llms-full.txtindex a629d7a05e..fa3f914797 100644--- a/llms-full.txt+++ b/llms-full.txt@@ -2826,7 +2826,7 @@ Since 16 November 2026, stable comes with a written promise about what a script1. **Every release passes the full test suite first.** A release is published only after the full unit and end-to-end test runs pass on its exact code.2. **A stable candidate then passes a production-shaped test.** gbrain runs a two-hour load test on a brain of 600,000 pages, at two network delays (2 ms and 65 ms), with privacy probes. It must pass the privacy-leak, read-error, version-skew, process-health and session checks in every run. The test has to have run on the release's exact files; a test of a nearby commit doesn't count.3. **Stable moves only for a reason.** A scheduled check runs twice a day (05:17 and 13:17 UTC). It promotes the newest release that passed step 2, and only when there is a reason to move:- - an important fix (a security, regression or data-loss fix, or a fix for something that blocks people) has been released but is not in stable yet, or+ - an important fix (a security fix, a data-loss fix, or a fix for a regression in a release that is on stable) has been released but is not in stable yet, or- stable is more than 7 days old and a newer release exists.With no reason, stable stays where it is.@@ -2834,9 +2834,9 @@ Since 16 November 2026, stable comes with a written promise about what a script## How often stable moves-The scheduled check can move it at most twice a day; a maintainer can also promote, or roll back, by hand. An important fix can move it on any day. If nothing important is waiting, the 7-day rule is the next reason for stable to move, though it still waits for a release that passed the test in step 2.+The rule: an important fix reaches stable within a day once it has passed the full test suite and the load test in step 2; everything else rides a weekly move; and stable never sits more than seven days behind tested changes. The scheduled check can move it at most twice a day; a maintainer can also promote, or roll back, by hand. If nothing important is waiting, the 7-day rule is the next reason for stable to move, though it still waits for a release that passed the test in step 2. A fix for a problem only newer, non-stable releases have, or one that unblocks a single setup, waits for the weekly move; if you need it sooner, install that release by its tag (see "Pinning a version").-What that has meant so far: the first stable release was v0.60.474.0 on 28 October 2026. Between then and 15 November 2026 stable moved 9 more times: once on 6 November, 9.7 days later, and then on each of the 8 days from 8 to 15 November, because an important fix was waiting on each of those days. Each move carried every change released since the one before. To see the current pace, list every stable release:+What that has meant so far: the first stable release was v0.60.474.0 on 28 October 2026. Between then and 15 November 2026 stable moved 9 more times: once on 6 November, 9.7 days later, and then on each of the 8 days from 8 to 15 November, because an important fix was waiting on each of those days. Each move carried every change released since the one before. Until then an important fix also included a fix for something that blocked people. From the release that carries this change on (decided 16 November 2026), only security, data-loss and stable-regression fixes move stable early, so expect it to move about once a week. To see the current pace, list every stable release:```bashgit ls-remote --tags --refs https://github.com/garrytan/gbrain 'refs/tags/stable-v*'diff --git a/scripts/build-behavior-changes.ts b/scripts/build-behavior-changes.tsindex c162824739..9fb71fc4ee 100644--- a/scripts/build-behavior-changes.ts+++ b/scripts/build-behavior-changes.ts@@ -16,6 +16,7 @@* newer than the CHANGELOG's top release heading (gstack-restamp --release runs this before it folds the* fragments). On every other tree they are pending and generate nothing, so a PR never changes the generated file.* A changelog.d fragment whose front matter says `bump:` anything but `patch` is refused: releases are PATCH only.+ * So is an `important:` class other than security, regression or data-loss: only those reach stable early.* Dependency-free and history-free: gstack's release check reruns it in a bare worktree of the release head.** Exit: 0 written or fresh, 1 stale or invalid (FAIL/Why/Fix printed), 2 usage.@@ -32,6 +33,7 @@ export const MARKER = /<!--\s*behavior-change:\s*([^\s]+)\s*-->/g;export const ID = /^[a-z][a-z0-9_]{2,95}$/;const NOTICE_CAP = 2_000;const DOCS = 'behavior-changes.d/README.md';+const IMPORTANT_CLASSES = ['security', 'regression', 'data-loss'];export interface Release { version: string | null; ids: string[] }export interface Built { text: string; problems: string[] }@@ -75,8 +77,11 @@ export function build(root: string): Built {? readdirSync(join(root, CHANGELOG_FRAGMENT_DIR)).filter(f => f.endsWith('.md') && f !== 'README.md').sort() : [];for (const f of pendingFiles) {const front = /^---\r?\n([\s\S]*?)\r?\n---\s*(\n|$)/.exec(read(root, join(CHANGELOG_FRAGMENT_DIR, f)))?.[1] ?? '';- const bump = /^\s*['"]?bump['"]?\s*:(.*)$/m.exec(front)?.[1]?.trim().replace(/^(['"])(.*)\1$/, '$2');+ const value = (re: RegExp) => re.exec(front)?.[1]?.replace(/\s+#.*$/, '').trim().replace(/^(['"])(.*)\1$/, '$2');+ const bump = value(/^\s*['"]?bump['"]?\s*:(.*)$/m);if (bump !== undefined && bump !== 'patch') problems.push(`${CHANGELOG_FRAGMENT_DIR}/${f} says bump: ${bump}; gbrain releases are PATCH only and the release takes the highest bump in the batch, so delete the bump: line (or write bump: patch)`);+ const important = value(/^\s*['"]?important['"]?\s*:(.*)$/m);+ if (important !== undefined && !IMPORTANT_CLASSES.includes(important)) problems.push(`${CHANGELOG_FRAGMENT_DIR}/${f} says important: ${important}; stable takes the fast path only for security, regression (in a release that is on stable) or data-loss, so write one of those or delete the important: line (docs/RELEASING.md#daily-stable-check)`);}const pending = [...pendingFiles.flatMap(f => markers(read(root, join(CHANGELOG_FRAGMENT_DIR, f)))), ...releases.filter(r => !r.version).flatMap(r => r.ids)];const sinceOf = new Map<string, string>();diff --git a/src/commands/upgrade.ts b/src/commands/upgrade.tsindex b45155edb8..8b8ca703df 100644--- a/src/commands/upgrade.ts+++ b/src/commands/upgrade.ts@@ -50,7 +50,7 @@ export function assessUpgradeOutcome(export async function runUpgrade(args: string[], opts: { targetVersion?: string } = {}) {if (args.includes('--help') || args.includes('-h')) {- console.log('Usage: gbrain upgrade [--channel stable|alpha] [--dry-run] [--stop-mcp] [--no-restart] [--swap-only] [--no-autopilot-install] [--no-bun-floor-check]\n gbrain upgrade --restart-only [--stop-mcp] [--dry-run] [--json]\n\nSelf-update the CLI, then restart every gbrain process on this host onto the new build.\n\nDetects install method (bun, bun-link, binary) and runs the appropriate update.\nAfter upgrading, shows what\'s new and offers to set up new features.\n\n--channel <name> stable (weekly, promoted after its gates passed on the exact release; the default) or alpha\n (every published release; latest is an alias). Precedence: --channel, GBRAIN_RELEASE_CHANNEL,\n self_upgrade.channel, stable. Persist it as self_upgrade.channel in config.\n--stop-mcp Stop MCP stdio servers agent harnesses started, instead of refusing; reconnect gbrain\n in each harness afterwards.\n--no-restart Install without restarting anything (doctor reports runtime_build_skew until\n \'gbrain upgrade --restart-only\' runs).\n--restart-only Restart serve, autopilot, the jobs supervisor and its worker (and, with --stop-mcp, MCP\n servers) onto the installed build, then verify every process reports it and the warm\n CLI socket accepts it. A process it cannot restart refuses with the exact step (exit 3).\n--dry-run Print the effective channel, where it came from and what would install; change nothing.\n With --restart-only: print the restart plan instead.\n--no-autopilot-install Skip autopilot installation and service rewrites.\n Also supported as GBRAIN_NO_AUTOPILOT_INSTALL=1.\n--no-bun-floor-check Upgrade even when the target release\'s Bun floor cannot be read or is above\n this host\'s Bun (manual upgrades only). Docs: docs/guides/upgrades-auto-update.md#bun-floor.\n--swap-only Perform ONLY the binary/source swap and skip post-upgrade\n (migrations run on the next launch). Used by the autopilot\n silent self-upgrade channel so the daemon can swap + relaunch\n without a 30-min blocking post-upgrade inside its tick.');+ console.log('Usage: gbrain upgrade [--channel stable|alpha] [--dry-run] [--stop-mcp] [--no-restart] [--swap-only] [--no-autopilot-install] [--no-bun-floor-check]\n gbrain upgrade --restart-only [--stop-mcp] [--dry-run] [--json]\n\nSelf-update the CLI, then restart every gbrain process on this host onto the new build.\n\nDetects install method (bun, bun-link, binary) and runs the appropriate update.\nAfter upgrading, shows what\'s new and offers to set up new features.\n\n--channel <name> stable (the default: weekly, sooner only for security, data-loss and stable-regression fixes,\n and only to a release whose gates passed on its exact code) or alpha (every published\n release; latest is an alias). Precedence: --channel, GBRAIN_RELEASE_CHANNEL,\n self_upgrade.channel, stable. Persist it as self_upgrade.channel in config.\n--stop-mcp Stop MCP stdio servers agent harnesses started, instead of refusing; reconnect gbrain\n in each harness afterwards.\n--no-restart Install without restarting anything (doctor reports runtime_build_skew until\n \'gbrain upgrade --restart-only\' runs).\n--restart-only Restart serve, autopilot, the jobs supervisor and its worker (and, with --stop-mcp, MCP\n servers) onto the installed build, then verify every process reports it and the warm\n CLI socket accepts it. A process it cannot restart refuses with the exact step (exit 3).\n--dry-run Print the effective channel, where it came from and what would install; change nothing.\n With --restart-only: print the restart plan instead.\n--no-autopilot-install Skip autopilot installation and service rewrites.\n Also supported as GBRAIN_NO_AUTOPILOT_INSTALL=1.\n--no-bun-floor-check Upgrade even when the target release\'s Bun floor cannot be read or is above\n this host\'s Bun (manual upgrades only). Docs: docs/guides/upgrades-auto-update.md#bun-floor.\n--swap-only Perform ONLY the binary/source swap and skip post-upgrade\n (migrations run on the next launch). Used by the autopilot\n silent self-upgrade channel so the daemon can swap + relaunch\n without a 30-min blocking post-upgrade inside its tick.');return;}diff --git a/test/scripts/build-behavior-changes.test.ts b/test/scripts/build-behavior-changes.test.tsindex 5945887337..5aaeae8ab7 100644--- a/test/scripts/build-behavior-changes.test.ts+++ b/test/scripts/build-behavior-changes.test.ts@@ -206,6 +206,18 @@ describe('build()', () => {expect(build(tree({ ...base, 'changelog.d/feature-x.md': '**Faster sync.**\n\nbump: minor appears in prose here.\n' })).problems).toEqual([]);});+ test('a changelog.d fragment whose important: class is not security, regression or data-loss is refused, naming the three and the doc', () => {+ const base = { VERSION: '0.1.0.0\n', 'CHANGELOG.md': changelog(section('0.1.0.0', 'First.')) };+ for (const [line, value] of [['important: blocker', 'blocker'], ["important: 'urgent'", 'urgent'], ['"important": Security', 'Security'], ['important:', ''], ['important: blocker # unblocks a crew', 'blocker']]) {+ const { problems } = build(tree({ ...base, 'changelog.d/fix-x.md': `---\n${line}\n---\n**Search works again.**\n` }));+ expect(problems).toEqual([`changelog.d/fix-x.md says important: ${value}; stable takes the fast path only for security, regression (in a release that is on stable) or data-loss, so write one of those or delete the important: line (docs/RELEASING.md#daily-stable-check)`]);+ }+ for (const value of ['security', 'regression', 'data-loss', "'data-loss'", 'regression # on stable']) {+ expect(build(tree({ ...base, 'changelog.d/fix-x.md': `---\nimportant: ${value}\n---\n**Search works again.**\n` })).problems).toEqual([]);+ }+ expect(build(tree({ ...base, 'changelog.d/fix-x.md': '**Search works again.**\n\nimportant: blocker appears in prose here.\n' })).problems).toEqual([]);+ });+test('an id starting with a digit is refused, so the generated map never holds an unquoted numeric key', () => {const root = tree({VERSION: '0.1.0.0\n',