Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Move this PR's changelog entry and upgrade-notice rows into fragments for direct landing
garrytan7b4c7c27cd07
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 09f830a34a..3846aacefd 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -10,33 +10,6 @@ credits are retained; no result has been reassigned to another provider. Originaidentifiers and attribution are available in the pre-removal Git revision`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).-## [Unreleased]--### A keyless brain keeps itself tidy, and doctor says when upkeep last ran--**`gbrain maintain --unattended` runs the free upkeep a brain needs, and is safe to run from a scheduler.** It runs the same steps as `gbrain maintain --safe` (link and timeline extraction, stale-page checks, the free repair lanes) plus a new bookkeeping cleanup step. It never deletes a page and never starts a paid model call, with one exception you can switch off. On a brain with an embedding key, it embeds pages that are missing embeddings, capped at $1 a day per brain (`maintenance.embed_daily_usd`, 0 turns it off). It works the same on a brain with no git repository and no API keys. A run that has nothing to do, or that finds the brain busy, degraded, behind on migrations or already looked after by `gbrain autopilot`, exits 0 and says why. A step that fails three runs in a row is retried once a week instead of every run, and doctor names it.--- `gbrain maintain --status` shows when upkeep last ran, what each step did, what failed, and when the next run is due.-- A new doctor check, `unattended_maintenance`, reports the same thing. It warns when upkeep hasn't run for 48 hours or a step keeps failing, and its fix is `gbrain maintain --unattended`. A brain where `maintenance.auto` is `false`, or where autopilot runs upkeep, reads as ok.-- `gbrain maintain --purge` previews which soft-deleted pages are past their 72-hour window. `--yes --expect <hash>` purges exactly the previewed set, and refuses with `preview_changed` when the set moved since the preview. Upkeep never purges pages on its own.--### Smaller changes--- The old bookkeeping cleanup inside the cycle's `purge` phase is now its own phase, `bookkeeping_gc`, with the same retentions. It never touches a page, so upkeep can run it while `purge` stays manual. `purge`'s summary now counts only pages, sources and orphaned clone folders.-- `gbrain autopilot --install` on a PGLite brain or a brain with no repository now refuses with a structured error (`autopilot_pglite_daemon`, `autopilot_no_repo`) that points at `gbrain maintain --status`, instead of a plain message.-- doctor's `cycle_freshness` fix no longer asks for spend consent on a brain with no chat or embedding key, since nothing it runs there costs money.-- The cycle's skip message for a phase that needs a filesystem no longer claims the reason is a Postgres or remote engine.--### Itemized changes--- `src/core/maintenance/run.ts` (new): the `--safe` step list (moved from `src/commands/maintain.ts`, which re-exports it), `unattendedPlan`, and `runUnattendedMaintenance`. The run record is `maintenance.last_run` in the database config, so repo-less brains have one. Brain-wide steps run once per run, then one item per source.-- `src/core/maintenance/status.ts` (new): `readUpkeepStatus`, the one view behind `--status` and doctor.-- `src/commands/doctor/checks/unattended-maintenance.ts` (new): the `unattended_maintenance` check.-- `src/core/cycle/bookkeeping-gc.ts` (new) and `src/core/cycle/phase-table.ts`: `bookkeeping_gc`, and a `tier` (`free`, `paid`, `deletes`, `filesystem`) on every phase, which the upkeep step list is tested against.-- `src/core/cycle.ts`: `CycleOpts.stamp` (`full`, `source_only`, `none`) so a partial run can't claim a full cycle, and `deferFactEmbedding` so fact extraction stays free on a keyed brain.-- `src/commands/autopilot-refusals.ts` (new) and `src/core/error-registry.ts`: new codes `autopilot_no_repo`, `autopilot_pglite_daemon`, `cycle_already_running`, `engine_degraded`, `maintenance_disabled` and `maintenance_owned_by_autopilot`.-- Tests: `test/maintenance-unattended.test.ts` (PGLite and Postgres) and `test/e2e/maintain-unattended-keyless-pglite.test.ts`.-## [0.60.711.0] - 2026-11-13**Upgrade and maintenance stability for self-hosters: upgrades are tested from real releases every night, health alerts page only on what needs someone, routine maintenance noise heals itself, an upgrade adds nothing you didn't turn on, the serve restart after a self-upgrade runs once per build without freezing the autopilot, a macOS brain on an external volume starts under launchd, a new doctor check counts session connections against the pooler limit, and twenty dream-cycle, doctor and repair fixes stop phantom work and false failures.**diff --git a/behavior-changes.d/autopilot_refusals_structured_gbra438.md b/behavior-changes.d/autopilot_refusals_structured_gbra438.mdnew file mode 100644index 0000000000..e86d7e4c51--- /dev/null+++ b/behavior-changes.d/autopilot_refusals_structured_gbra438.md@@ -0,0 +1 @@+`gbrain autopilot --install` refusals (a PGLite brain without --force, no repo path) now go through the agent error contract: codes `autopilot_pglite_daemon` and `autopilot_no_repo`, a why, a fix and `--json` output, instead of a bare line on stderr; PGLite and repo-less users are pointed to `gbrain maintain --status`.diff --git a/behavior-changes.d/bookkeeping_gc_phase_gbra438.md b/behavior-changes.d/bookkeeping_gc_phase_gbra438.mdnew file mode 100644index 0000000000..d071c01b73--- /dev/null+++ b/behavior-changes.d/bookkeeping_gc_phase_gbra438.md@@ -0,0 +1 @@+The dream cycle has a new phase, `bookkeeping_gc`, after `purge`: it now does the retention GC that `purge` used to do (op checkpoints, brainstorm checkpoints, batch-retry audit files, volunteer events, decision receipts, applied captures, retrieval feedback), with the same retentions. `gbrain dream --json` reports those counts under `bookkeeping_gc` instead of `purge`, whose details keep only sources, pages and orphan clones; `--phase purge` no longer runs the GC.diff --git a/behavior-changes.d/cycle_freshness_keyless_consent_gbra438.md b/behavior-changes.d/cycle_freshness_keyless_consent_gbra438.mdnew file mode 100644index 0000000000..09f65830b7--- /dev/null+++ b/behavior-changes.d/cycle_freshness_keyless_consent_gbra438.md@@ -0,0 +1 @@+On a brain with no chat or embedding key, the `cycle_freshness` doctor fix (`gbrain dream --source <id>`) now asks no paid consent (`consent: []`, so `next: run`), because no phase it runs can spend.diff --git a/behavior-changes.d/cycle_skip_text_gbra438.md b/behavior-changes.d/cycle_skip_text_gbra438.mdnew file mode 100644index 0000000000..ae4ab4dd12--- /dev/null+++ b/behavior-changes.d/cycle_skip_text_gbra438.md@@ -0,0 +1 @@+A dream cycle phase skipped for want of a checkout no longer says (postgres/remote engine), which was wrong on PGLite: the summary is now: requires a local brain directory; this brain has no on-disk checkout; pass --dir <path> to run filesystem phases. The reason code `no_brain_dir` is unchanged.diff --git a/behavior-changes.d/unattended_maintenance_doctor_gbra438.md b/behavior-changes.d/unattended_maintenance_doctor_gbra438.mdnew file mode 100644index 0000000000..6665cf7b7b--- /dev/null+++ b/behavior-changes.d/unattended_maintenance_doctor_gbra438.md@@ -0,0 +1 @@+`gbrain doctor` has a new check, `unattended_maintenance`, which reads the free-upkeep record `maintenance.last_run`: it warns (and so can lower doctor status from healthy) when no upkeep run is recorded on a brain older than 48 hours, when the last run is older than 48 hours, or when one step failed three runs in a row; the fix is `gbrain maintain --unattended`. Upkeep turned off (`maintenance.auto false`) or owned by an autopilot reads ok. New commands: `gbrain maintain --unattended`, `--status` and `--purge` (preview, then `--yes --expect <hash>`).diff --git a/changelog.d/capy-gbra438-upkeep-core.md b/changelog.d/capy-gbra438-upkeep-core.mdnew file mode 100644index 0000000000..7421fc502f--- /dev/null+++ b/changelog.d/capy-gbra438-upkeep-core.md@@ -0,0 +1,30 @@+### A keyless brain keeps itself tidy, and doctor says when upkeep last ran++**`gbrain maintain --unattended` runs the free upkeep a brain needs, and is safe to run from a scheduler.** It runs the same steps as `gbrain maintain --safe` (link and timeline extraction, stale-page checks, the free repair lanes) plus a new bookkeeping cleanup step. It never deletes a page and never starts a paid model call, with one exception you can switch off. On a brain with an embedding key, it embeds pages that are missing embeddings, capped at $1 a day per brain (`maintenance.embed_daily_usd`, 0 turns it off). It works the same on a brain with no git repository and no API keys. A run that has nothing to do, or that finds the brain busy, degraded, behind on migrations or already looked after by `gbrain autopilot`, exits 0 and says why. A step that fails three runs in a row is retried once a week instead of every run, and doctor names it.++- `gbrain maintain --status` shows when upkeep last ran, what each step did, what failed, and when the next run is due.+- A new doctor check, `unattended_maintenance`, reports the same thing. It warns when upkeep hasn't run for 48 hours or a step keeps failing, and its fix is `gbrain maintain --unattended`. A brain where `maintenance.auto` is `false`, or where autopilot runs upkeep, reads as ok.+- `gbrain maintain --purge` previews which soft-deleted pages are past their 72-hour window. `--yes --expect <hash>` purges exactly the previewed set, and refuses with `preview_changed` when the set moved since the preview. Upkeep never purges pages on its own.++### Smaller changes++- The old bookkeeping cleanup inside the cycle's `purge` phase is now its own phase, `bookkeeping_gc`, with the same retentions. It never touches a page, so upkeep can run it while `purge` stays manual. `purge`'s summary now counts only pages, sources and orphaned clone folders.+- `gbrain autopilot --install` on a PGLite brain or a brain with no repository now refuses with a structured error (`autopilot_pglite_daemon`, `autopilot_no_repo`) that points at `gbrain maintain --status`, instead of a plain message.+- doctor's `cycle_freshness` fix no longer asks for spend consent on a brain with no chat or embedding key, since nothing it runs there costs money.+- The cycle's skip message for a phase that needs a filesystem no longer claims the reason is a Postgres or remote engine.++### Itemized changes++- `src/core/maintenance/run.ts` (new): the `--safe` step list (moved from `src/commands/maintain.ts`, which re-exports it), `unattendedPlan`, and `runUnattendedMaintenance`. The run record is `maintenance.last_run` in the database config, so repo-less brains have one. Brain-wide steps run once per run, then one item per source.+- `src/core/maintenance/status.ts` (new): `readUpkeepStatus`, the one view behind `--status` and doctor.+- `src/commands/doctor/checks/unattended-maintenance.ts` (new): the `unattended_maintenance` check.+- `src/core/cycle/bookkeeping-gc.ts` (new) and `src/core/cycle/phase-table.ts`: `bookkeeping_gc`, and a `tier` (`free`, `paid`, `deletes`, `filesystem`) on every phase, which the upkeep step list is tested against.+- `src/core/cycle.ts`: `CycleOpts.stamp` (`full`, `source_only`, `none`) so a partial run can't claim a full cycle, and `deferFactEmbedding` so fact extraction stays free on a keyed brain.+- `src/commands/autopilot-refusals.ts` (new) and `src/core/error-registry.ts`: new codes `autopilot_no_repo`, `autopilot_pglite_daemon`, `cycle_already_running`, `engine_degraded`, `maintenance_disabled` and `maintenance_owned_by_autopilot`.+- Tests: `test/maintenance-unattended.test.ts` (PGLite and Postgres) and `test/e2e/maintain-unattended-keyless-pglite.test.ts`.++<!-- behavior-change: unattended_maintenance_doctor_gbra438 -->+<!-- behavior-change: bookkeeping_gc_phase_gbra438 -->+<!-- behavior-change: autopilot_refusals_structured_gbra438 -->+<!-- behavior-change: cycle_skip_text_gbra438 -->+<!-- behavior-change: cycle_freshness_keyless_consent_gbra438 -->diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex 1639be295d..800fffa983 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1574,12 +1574,6 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;{ since: '0.60.704.0', id: 'qm_context_pack_scope_read_gst2407', text: 'An attested `context_pack` that names `source_id` now reads that one source as its audience instead of being refused on a client that reads named sources as the scope: its entities and `entity_refs`, the core block, the counterparty brief and hot facts come from that source only, with no member-page fact, no page restricted to named readers and privacy never relaxed. A call that sends `entity_refs` without `source_id`, an `entity_refs` entry in another source, or `session_id` is refused with `invalid_params` before anything is read. A client set `--attest-read person` reads as the person, narrowed to that source the same way. Contract `docs/contracts/qm-memory-provider/v5.json` marks `context_pack` `scope_read: true`; v1 to v4 are unchanged.' },{ since: '0.60.704.0', id: 'qm_admin_attest_read_gst2407', text: 'The owner can now set how a client reads named sources from another machine: `gbrain mcp admin attest <client> --attest-read person|scope|none`, backed by `attestRead` on `/admin/api/access/attest`. It refuses what `gbrain auth rescope --attest-read` refuses (no attest right, or a client with scope sources set to person), previews with `--dry-run` and logs `attest_read` in the `access_admin` row.' },...RELEASED_BEHAVIOR_CHANGES,- // GBRA-438 PR 1: free unattended upkeep (core/maintenance/run.ts); since TBD until the merge slot, rows are data and cannot move.- { since: 'TBD', id: 'unattended_maintenance_doctor_gbra438', text: '`gbrain doctor` has a new check, `unattended_maintenance`, which reads the free-upkeep record `maintenance.last_run`: it warns (and so can lower doctor status from healthy) when no upkeep run is recorded on a brain older than 48 hours, when the last run is older than 48 hours, or when one step failed three runs in a row; the fix is `gbrain maintain --unattended`. Upkeep turned off (`maintenance.auto false`) or owned by an autopilot reads ok. New commands: `gbrain maintain --unattended`, `--status` and `--purge` (preview, then `--yes --expect <hash>`).' },- { since: 'TBD', id: 'bookkeeping_gc_phase_gbra438', text: 'The dream cycle has a new phase, `bookkeeping_gc`, after `purge`: it now does the retention GC that `purge` used to do (op checkpoints, brainstorm checkpoints, batch-retry audit files, volunteer events, decision receipts, applied captures, retrieval feedback), with the same retentions. `gbrain dream --json` reports those counts under `bookkeeping_gc` instead of `purge`, whose details keep only sources, pages and orphan clones; `--phase purge` no longer runs the GC.' },- { since: 'TBD', id: 'autopilot_refusals_structured_gbra438', text: '`gbrain autopilot --install` refusals (a PGLite brain without --force, no repo path) now go through the agent error contract: codes `autopilot_pglite_daemon` and `autopilot_no_repo`, a why, a fix and `--json` output, instead of a bare line on stderr; PGLite and repo-less users are pointed to `gbrain maintain --status`.' },- { since: 'TBD', id: 'cycle_skip_text_gbra438', text: 'A dream cycle phase skipped for want of a checkout no longer says (postgres/remote engine), which was wrong on PGLite: the summary is now: requires a local brain directory; this brain has no on-disk checkout; pass --dir <path> to run filesystem phases. The reason code `no_brain_dir` is unchanged.' },- { since: 'TBD', id: 'cycle_freshness_keyless_consent_gbra438', text: 'On a brain with no chat or embedding key, the `cycle_freshness` doctor fix (`gbrain dream --source <id>`) now asks no paid consent (`consent: []`, so `next: run`), because no phase it runs can spend.' },];/** The newest disclosed change's release: the notice id moves only when a release adds rows. */