Skip to content

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.md
new file mode 100644
index 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.md
index 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, so
a `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.md
new file mode 100644
index 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.md
index 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 version
heading (bold one-line summary, then the itemized sections; voice rules
below). /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 PATCH
only, 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, named
in 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 a
published release but not in stable, or stable is more than 7 days old and
a 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 whose
commit 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.md
index 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 script
1. **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:
```bash
git ls-remote --tags --refs https://github.com/garrytan/gbrain 'refs/tags/stable-v*'
diff --git a/llms-full.txt b/llms-full.txt
index 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 script
1. **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:
```bash
git 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.ts
index 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.ts
index 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.ts
index 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',