Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Merge capy/gbra346-stable-install-default (B: #stable install pins, fresh init writes self_upgrade.channel stable)
garrytan2834fd206c80
diff --cc CHANGELOG.mdindex b87d4c7996,ced7cb75fc..f905fe5b30--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -12,26 -12,15 +12,35 @@@ identifiers and attribution are availab## [Unreleased]+**Updates follow a stable channel by default; every release is one setting away on alpha.**++gbrain publishes a release for nearly every merged change, more than a hundred a week. Every install followed all of them, so an always-on brain upgraded several times a week onto releases no one had run on a production-shaped brain. Installs now follow the stable channel: weekly releases a maintainer promoted after the soak passed on that release's exact tree. The alpha channel (the old `latest`, which still works as an alias) keeps every release.++### What changed++| Situation | Before | Now |+|---|---|---|+| A new or existing install with no channel set | offered every published release | offered the newest stable release; one notice on stderr says so, once per brain home |+| Following every release | the default | `gbrain config set self_upgrade.channel alpha` (or `--channel alpha`, `GBRAIN_RELEASE_CHANNEL=alpha`) |+| Which stable release is offered | `VERSION` at the `stable` tag | the published evidence record (`stable.json` on `stable-record`): version, commit, tree, soak run, withdrawn versions; a record without the evidence is never trusted |+| Stable has no usable answer | `stable_channel_unresolved` on upgrade | `stable_missing`, `stable_invalid` or `stable_unreadable`; the background check only reports it, an explicit upgrade exits non-zero, neither falls back to alpha |+| An install ahead of stable (it ran alpha) | — | offered nothing until stable passes it; never downgraded unless its version was withdrawn |+| Update cache and snooze | one file for every channel; a snooze ended when a newer release shipped | one per channel, tagged with the evidence policy; a snooze holds its whole window (24 h, 48 h, 7 days); a stable rollback below it clears it |+| `gbrain upgrade --dry-run` | refused without `--restart-only` | reports channel, its source, current and target version and the action, installing nothing |+| doctor `self_upgrade_health` | — | names the channel and its source, warns on an invalid channel or a failed stable check |+| `Promote stable` workflow | moved the `stable` tag | also commits the evidence record in the same atomic push; new `withdraw` input adds versions to `known_bad`; promoting the current stable again writes its record from the stable tag's message, moving no tag (the one-time backfill for releases promoted before the record existed) |++Install commands now name `stable` (`bun install -g github:garrytan/gbrain#stable`), so a new install starts on the channel it follows. Every install surface goes through one constant (`src/core/install-ref.ts`), checked by `bun run check:install-ref`; `latest-stable` still installs the newest release for anyone who pins it.++ **New installs now start on the stable channel: the soaked release, not every release.** The documented install (`bun install -g github:garrytan/gbrain#stable`) and the clone fallback (`git clone --branch stable`) follow the `stable` tag, which moves only to a published release whose exact tree passed the production soak, at least weekly. A fresh `gbrain init` (and so `gbrain setup claude-code` or `codex`) writes `self_upgrade.channel: stable`, so the update check and `gbrain upgrade` offer only stable releases. `#latest-stable` keeps working as the alpha line with every release. An existing brain is not changed: a re-init never sets or alters its channel.++ ### Itemized changes++ - Install pins move from `#latest-stable` to `#stable` in README, AGENTS.md, INSTALL_FOR_AGENTS.md, BOOTSTRAP_FOR_AGENTS.md, docs/INSTALL.md, the MCP, headless, in-agent and tutorial guides, the setup skills, the Codex plugin manifests and launcher, doctor's npm-squat fix, the bootstrap hints and the agent-workspace template. The bootstrap runbook fetch and the in-agent setup helper read the `stable` ref, and the in-agent helper pins the commit `refs/tags/stable` peels to.+ - `scripts/check-bootstrap-tag.sh` sanctions `stable` as the one distribution ref and now refuses `#latest-stable` in the entry docs.+ - `src/commands/init.ts`: a fresh install (new content database, no prior config file) persists `self_upgrade.channel: stable` on PGLite and Postgres. A re-init keeps whatever the config says, including no channel. `test/init-stable-channel.test.ts` covers the fresh, re-init and explicit-channel cases.+ - `docs/guides/upgrades-auto-update.md#stable-channel` describes stable as the default for new installs and `latest` as the alpha line.+## [0.60.593.0] - 2026-11-06**`gbrain repair failed-writes` now previews a brain with a large write journal in about a second instead of timing out.** On Postgres, the preview of refused writes read the request table once per refused write, and one of those reads walked the table from that write to its end. With hundreds of refused writes and a journal of over a million requests, the preview ran for minutes and the server's statement timeout ended it with a bare `internal_error`, so the operator had no way to see or recover the lost writes. The preview now classes refused writes together in set reads, each sized so it stays short even on a page with hundreds of refused writes and a long history. On a synthetic journal of 1.5 million requests with over 800 refused writes it took about a second (it took 265 seconds before), with the same classes and the same preview hash. When a preview read does still run past the timeout, it refuses `repair_preview_timeout` with a fix instead of `internal_error`, and nothing is saved.diff --cc docs/guides/upgrades-auto-update.mdindex 200ba1d435,c34d429af9..ba81da1745--- a/docs/guides/upgrades-auto-update.md+++ b/docs/guides/upgrades-auto-update.md@@@ -128,80 -128,46 +128,85 @@@ them in order and stop if the tag chec<a id="release-channel"></a>### Which version counts as available-Every update surface (the startup marker, `gbrain check-update`,-`gbrain self-upgrade`, doctor's `self_upgrade_health` and the `auto` channel)-reads the `VERSION` file at the ref of the brain's release channel-(`self_upgrade.channel`): the `stable` tag on the stable channel, the-`latest-stable` tag on `latest`. Master's `VERSION` is never offered: the-next PR stamps it before release.yml tags it, and a superseded version never-gets a tag (#6718, #6828).-<a id="stable-channel"></a>-**The stable channel.** New installs follow it: the documented install-(`github:garrytan/gbrain#stable`, or `git clone --branch stable`) starts on-it, and a fresh `gbrain init` writes `self_upgrade.channel: stable`. It is the-newest release a maintainer promoted after the production-shaped soak passed on-that release's exact git tree, at least weekly, through the `Promote stable`-workflow ([RELEASING.md](../RELEASING.md#stable-channel-promotion)), which moves-the `stable` tag to the release commit and records the soak scoreboard link in-the tag message (`git show stable`). `latest` is the alpha line: every-published release, the `latest-stable` tag that release.yml moves once a-release's checks pass and its assets publish. A brain created before this-default, with no channel set, stays on `latest` until you choose.+gbrain has two release channels, and every update surface (the startup+marker, `gbrain check-update`, `gbrain self-upgrade`, `gbrain upgrade`,+doctor's `self_upgrade_health` and the `auto` mode) follows the one in+effect:++| Channel | What it offers | Read from |+|---------|----------------|-----------|+| `stable` (default) | Weekly releases a maintainer promoted after testing on that release's exact git tree. | The evidence record `stable.json` on the `stable-record` branch, checked against the `stable` tag. |+| `alpha` | Every published release. | `VERSION` at the `latest-stable` tag, which release.yml moves on every publish. |++`latest` is accepted everywhere as an alias for `alpha`. The channel comes+from the first of these that is set: `--channel` on the command, the+`GBRAIN_RELEASE_CHANNEL` environment variable, `self_upgrade.channel` in the+brain home's config, then the default. An invalid value at the first one set+is an error (`invalid_params`), never a fall-through to the next. Channel state+lives under `GBRAIN_HOME`, so a repo-less brain and a repo brain behave the+same. When a channel is set, `gbrain doctor` prints `channel=<channel> (<source>)`.++New installs start on stable: the documented install++(`github:garrytan/gbrain#stable`, or `git clone --branch stable`) installs the++stable release, and a fresh `gbrain init` (new content database, no prior++config file) writes `self_upgrade.channel: stable`, so it never sees the++notice below.```bash-gbrain upgrade --channel stable # one run on the stable channel-gbrain config set self_upgrade.channel stable # make stable the default for this brain home-gbrain config set self_upgrade.channel latest # every published release (alpha)+gbrain config set self_upgrade.channel alpha # follow every release on this brain home+gbrain config set self_upgrade.channel stable # back to the default+gbrain upgrade --channel alpha # one run on alpha, config unchanged+gbrain upgrade --dry-run --json # what an upgrade would install, installing nothing```-With `self_upgrade.channel stable`, every update surface above reads `VERSION`-at the `stable` tag instead of `latest-stable`, so the marker, `check-update`,-`self-upgrade` and the `auto` channel only ever offer the stable release.-`gbrain upgrade` resolves it from `git ls-remote` (the `v<version>` tag on the-commit `stable` peels to) and installs exactly that release: a bun install is+An install with no channel set prints one notice, once per `GBRAIN_HOME`, on stderr (never under `--json`, `serve` or+`mcp`): `[gbrain notice release_channel] This install now follows the stable+channel ...`. It is not an `UPGRADE_AVAILABLE` marker. Setting any channel+silences it.++**The evidence record.** `Promote stable`+([RELEASING.md](../RELEASING.md#stable-channel-promotion)) moves the `stable`+tag and commits `stable.json` to the `stable-record` branch in one atomic+push. The record names the version, commit, tree, the soak run that passed on+that tree and a `known_bad` list of withdrawn releases. The update check reads+only that file (no API call, no git), so a missing record or a record without+the evidence its generation requires is never trusted. Generation 1 records+carry the soak run; from the matrix cutover on, `matrix_run` is required too.+`gbrain upgrade` also checks that `stable` and `v<version>` peel to the+record's commit, then installs exactly that release: a bun install isreinstalled pinned to `#v<version>` (remove, then add; it restores theprevious release if the add fails), a bun-link clone fast-forwards to the-release commit (never backward or across a fork), and the binary install-downloads that release's asset. A build already at or above the stable release-changes nothing: the stable channel never downgrades. A ClawHub install follows-ClawHub's own line and is refused with the reinstall command. When no release-has been promoted yet, or the remote cannot be read, the upgrade stops with-`stable_channel_unresolved` and changes nothing.+release commit, and the binary install downloads that release's asset.++**Never downgrade.** A build at or above the stable release is offered+nothing, so an install that ran ahead on alpha waits until stable passes it.+The one exception is a build on the record's `known_bad` list: it is offered+the current stable release even when that is older. A ClawHub install follows+ClawHub's own line and is refused with the reinstall command.++**The update cache and snooze are per channel.** Each channel keeps its own+answer (`update-check.<channel>.json`, which also records the evidence policy)+and its own snooze (`update-snoozed.<channel>.json`). Switching channel reads+that channel's answer; a cached answer from another policy, or the+unpartitioned cache of older builds, is never read. A snooze holds for its+whole window (24 h, then 48 h, then 7 days) however many releases ship+meanwhile; a stable rollback below the snoozed version clears it.++<a id="stable-channel-errors"></a>+**When stable has no usable answer.** The background check only records and+reports these; it never offers alpha instead. An explicit `gbrain upgrade` or+`gbrain self-upgrade` on stable exits non-zero with the code and installs+nothing.++| Code | Meaning | What to do |+|------|---------|------------|+| `stable_missing` | No release has been promoted yet (no record or no `stable` tag). | Wait for the first promotion, or `gbrain config set self_upgrade.channel alpha`. |+| `stable_invalid` | The record is malformed, lacks a required evidence key, lists its own version as known bad, or its version's tag is not the stable commit. | Wait for a maintainer to repair or re-promote stable, or switch to alpha. |+| `stable_unreadable` | The record or the tags did not answer (network, or a promotion still propagating). | Retry: `gbrain self-upgrade --check-only --json`. The last verified answer still shows in the notice, never as an install target. |++When the channel came from `--channel` or `GBRAIN_RELEASE_CHANNEL`, the fix+names that override instead of the config command. Builds before this release+reported `stable_channel_unresolved` (retired).A swap is a swap only when the version changed. When `gbrain upgrade` findsthe same version running after the install step (`bun update` on a tag whosediff --cc src/core/npm-squat-check.tsindex ebe2d983b1,d8bf387d0a..0208f72c64--- a/src/core/npm-squat-check.ts+++ b/src/core/npm-squat-check.ts@@@ -16,6 -16,6 +16,7 @@@import { closeSync, openSync, readFileSync, readSync, realpathSync } from 'node:fs';import { dirname, join, sep } from 'node:path';import type { Action } from './agent-output.ts';++import { INSTALL_PIN } from './install-ref.ts';export type GbrainBinaryKind = 'real' | 'foreign' | 'broken' | 'unknown';@@@ -58,8 -58,8 +59,8 @@@ export interface ClassifyGbrainBinaryOp/** Repository marker identifying this project's package.json. */const REAL_REPO_MARKER = 'garrytan/gbrain';- /** The documented install command (the `latest-stable` release ref). */- const INSTALL_ARGV = ['bun', 'install', '-g', `github:${REAL_REPO_MARKER}#latest-stable`];-/** The documented install command (the `stable` release ref). */-const INSTALL_ARGV = ['bun', 'install', '-g', `github:${REAL_REPO_MARKER}#stable`];++/** The documented install command (INSTALL_PIN, the one install ref in core/install-ref.ts). */++const INSTALL_ARGV = ['bun', 'install', '-g', INSTALL_PIN];/** #218 recovery: a Bun global install can skip the postinstall that applies schema migrations. */const SCHEMA_RECOVERY_ARGV = ['gbrain', 'apply-migrations', '--yes', '--no-autopilot-install'];