Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Tell operators to upgrade every host before adding a page rule
garrytan9817bebde880
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex d8f60af545..b961395deb 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -30,7 +30,7 @@ identifiers and attribution are available in the pre-removal Git revision#### Page rules: restrict one exact page (GST-2462)- `src/core/access/folder-rules.ts`: a rule can name one page with `slug:` instead of `prefix:` (`gbrain access rule add --slug <page>`, `src/commands/access-rules.ts`). It is stored in the same rulebook without the trailing `/` and covers only that slug, never a folder of the same name or a longer slug. A `prefix:` without `/` is still refused and now names the slug form.-- Migration v303 (provisional number, `access_page_rules`): both prefix checks accept the page form, and `gbrain_access_folder_rules` / `gbrain_access_pending_covers` match a slash-less prefix only when it equals the slug; `src/core/search/private-visibility.ts` and the rule preview use the same matcher. Folder prefixes match exactly as before, so no page is restamped on upgrade. Reads are decided in the database, so they are right for every gbrain sharing it once it is migrated; an older gbrain that syncs an `access.yml` holding a page rule reads the file as invalid, so that source reads as nobody remotely until it is upgraded.+- Migration v303 (provisional number, `access_page_rules`): both prefix checks accept the page form, and `gbrain_access_folder_rules` / `gbrain_access_pending_covers` match a slash-less prefix only when it equals the slug; `src/core/search/private-visibility.ts` and the rule preview use the same matcher. Folder prefixes match exactly as before, so no page is restamped on upgrade. Upgrade every gbrain host that shares the brain before adding a page rule. Reads are decided in the database, so an older host still keeps the page restricted, but it refuses its own `gbrain access rule` commands and, on a git-backed source, stops syncing that source with `stored rulebook holds a malformed rule` until it is upgraded.- `src/core/persistence/service.ts`, `terminal-classify.ts`, `verb-errors.ts`, `page-prepare.ts`: a write refused because the page's canonical file is missing names the page rule as the way to narrow who reads the page, beside the ghost-page repair.- Docs: `docs/guides/access-designations.md`, `docs/tutorials/company-brain.md`, `docs/guides/write-refusals.md#canonical_file_missing`.- Tests: `test/access-page-rule-fileless.test.ts` (a root page named after its folder and a page whose file left git on a managed git source, and a repo-less brain, on PGLite and Postgres: put refuses and names the route, the rule hides each page from unbound callers while the owner reads it, nothing else is covered, no page file is written, and removing the rule restores the reads after approval).diff --git a/docs/guides/access-designations.md b/docs/guides/access-designations.mdindex 7962d57612..88b2598320 100644--- a/docs/guides/access-designations.md+++ b/docs/guides/access-designations.md@@ -127,7 +127,8 @@ Pinned-question pages are the owner's own and read as private. The owner reads t`readable_by: [alice-example, group:team-a]` keeps a page to the members and groups it lists; `gbrain access ruleadd --prefix <folder>/ --readers <list>` does the same for a folder, and `--slug <page>` for exactly one page (a page-at the source root, or one whose file left git, which a `visibility` edit cannot reach). This is the boundary between people in a+at the source root, or one whose file left git, which a `visibility` edit cannot reach; upgrade every host that shares+the brain first, because an older one stops syncing a git-backed source that holds a page rule). This is the boundary between people in ashared brain, and it binds the owner too: the owner reads such a page only when listed. No grant, hatch or ownerbinding relaxes it. Use it for a page that belongs to specific people in a shared brain; a single-user brain needsnone. The page's writers set it; widening a folder rule waits for `gbrain access apply`. A credential bound to adiff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.mdindex b93eab36df..cbade42837 100644--- a/docs/guides/write-refusals.md+++ b/docs/guides/write-refusals.md@@ -52,7 +52,7 @@ of making a duplicate.| Reason | Error code | What it means | Recovery || --- | --- | --- | --- || <a id="file_database_drift"></a>`file_database_drift` | `source_changed` | The page's canonical file and its database copy disagree, usually because the file was edited outside a coordinated write. Neither copy was overwritten. The receipt records the cause as `error_detail.origin: file_database_drift` (GST-1601). A file with no `type:` line keeps the stored type, and titles compare trimmed, so those alone do not cause this. Drift only in ordinary frontmatter keys (not a policy, privacy, lineage or trust key such as `readable_by`, `derived_from` or `trust_tier`, nor title, type or tags) does not refuse a write that leaves the frontmatter unchanged, such as `remember`: the write lands and the file keeps its own frontmatter, so that drift is left for reconcile (#8109). With `gbrain config set persistence.adopt_local_edits.source.<source> true` (off by default), a `remember`, `capture` or `add_timeline_entry` that meets a one-sided local edit (Git `HEAD` still holds the database copy; on a repo-less brain, any edit) is not refused: once the file has been unchanged for `persistence.adopt_quiet_ms` (default 5000), the owner commits that file on its own (`gbrain: adopt local edit to <path>`, trailers `gbrain-adopted:` and `gbrain-author: unknown`; page history reason `adopted_local_edit`), then applies the write on top, and the receipt names `adopted`. A two-sided edit, a file that does not import, an edit to the title, type or a protected key, `put_page` and every other verb still refuse; doctor `local_edit_adoptions` lists adoptions of the last 24 h (GST-1601). The refusal also stays for a file over the page size limit or a page stored in segments, an unmerged path or a merge, cherry-pick, revert, rebase, `git bisect` (`BISECT_LOG`) or uncommitted `git merge --squash` (`SQUASH_MSG`) in progress, and a stale editor save (a file equal to an earlier stored revision, or missing a Facts or timeline row the last write added); the quiet wait never passes 30 s, since writes behind it on the same checkout wait meanwhile (#8755). It also stays when `git rev-parse --absolute-git-dir` answers with anything but one absolute, existing directory in valid UTF-8; a `git cherry-pick -n` leaves no marker, and its staged paths stay out of the adoption's commit (#8826). An adoption whose commit landed before its publication failed is published on its replay even after the write it was made for ended, and one that ends without committing after that commit names it on its receipt (`outcome.persistence.git_commit`, `landed_before_row: true`; #8824, #8767). | The receipt's fix (`gbrain sources writer failures <source>`, `gbrain write-request <request_id> --json`) previews keeping the database copy for that one page with `gbrain repair file-drift --source <source> --slug <slug> --prefer database` (`--prefer file` previews importing the file instead); a person picks the side, then the agent runs the apply command the preview prints. A group of such receipts gets `--all-drifted --since <instant>` with the oldest receipt's time, so only pages that drifted since then are selected. For a hand merge: `gbrain sources reconcile <source> <slug> --brain <brain> --preview`, review the preview, resolve it, then `--apply <resolved-preview-file> --request-id <new uuid>`. Retry the original write with a **new** request ID. A page that records no file of its own (no `source_path`, typically written by an older release whose write-through also put `ingested_via` / `ingested_at` / `source_kind` in the file only) reconciles against the file at its slug path only when you add `--adopt-slug-path` to the preview; the refusal names the flag in that case, and apply records that file as the page's origin. See [repair a file/database disagreement](concurrent-writes.md#repair-a-filedatabase-disagreement). Many pages at once: `gbrain sources reconcile <source> --brain host --audit --conflicts` lists them and `gbrain repair file-drift` resolves them, preferring the file or the database copy ([file drift](repair.md#file-drift)). |-| <a id="canonical_file_missing"></a>`canonical_file_missing` | `source_changed` (a caller write; maintenance refuses before admission) | The page's recorded canonical file is gone while its database page is still live (a ghost page: the file was moved or deleted outside gbrain). A caller write refuses with "The canonical file was removed outside coordinated publication." and nothing is written; retrying it refuses the same way. A maintenance write (fact-fence adoption, enrichment, `dream`) is refused before admission: no request id, no receipt (before #6696 each cycle settled a `conflict` receipt). `gbrain sources writer failures <source>` reports such receipts as category `canonical_file_missing`. Neither copy was changed. | Decide which copy is right. A visibility edit cannot publish while the file is gone, so to keep the page and only narrow who reads it, add a page rule on the brain host: `gbrain access rule add --slug <slug> --readers <member> --source <source>` (it previews; `--yes` applies; list the owner's member to keep the owner reading; removing the rule undoes it). No file is written for the page. If the file should exist, restore it at its recorded path and preview the page with `gbrain sources reconcile <source> <slug> --brain host --preview`, or sync. If the page should go, preview the ghost-page repair with `gbrain repair ghost-pages --source <source>` (read-only; it prints the apply command with its hash) and apply it with `--apply --expect <hash> --yes` only after the user agrees; a soft-deleted page can be restored with `gbrain restore <slug> --force` until the autopilot purge 72 h later. `gbrain pages ghosts --source <source>` and doctor `ghost_pages` list them, doctor `maintenance_write_drift` lists held-back maintenance writes. See [ghost pages](repair.md#ghost-pages). |+| <a id="canonical_file_missing"></a>`canonical_file_missing` | `source_changed` (a caller write; maintenance refuses before admission) | The page's recorded canonical file is gone while its database page is still live (a ghost page: the file was moved or deleted outside gbrain). A caller write refuses with "The canonical file was removed outside coordinated publication." and nothing is written; retrying it refuses the same way. A maintenance write (fact-fence adoption, enrichment, `dream`) is refused before admission: no request id, no receipt (before #6696 each cycle settled a `conflict` receipt). `gbrain sources writer failures <source>` reports such receipts as category `canonical_file_missing`. Neither copy was changed. | Decide which copy is right. A visibility edit cannot publish while the file is gone, so to keep the page and only narrow who reads it, add a page rule on the brain host: `gbrain access rule add --slug <slug> --readers <member> --source <source>` (it previews; `--yes` applies; list the owner's member to keep the owner reading; removing the rule undoes it; upgrade every gbrain host that shares the brain first). No file is written for the page. If the file should exist, restore it at its recorded path and preview the page with `gbrain sources reconcile <source> <slug> --brain host --preview`, or sync. If the page should go, preview the ghost-page repair with `gbrain repair ghost-pages --source <source>` (read-only; it prints the apply command with its hash) and apply it with `--apply --expect <hash> --yes` only after the user agrees; a soft-deleted page can be restored with `gbrain restore <slug> --force` until the autopilot purge 72 h later. `gbrain pages ghosts --source <source>` and doctor `ghost_pages` list them, doctor `maintenance_write_drift` lists held-back maintenance writes. See [ghost pages](repair.md#ghost-pages). || <a id="refusal_breaker"></a>`refusal_breaker` | the code of the earlier refusals | The same maintenance write (same source, slug, page revision, planner and intent) was refused `persistence.maintenance.refusal_breaker_threshold` times (default 3; `0` turns it off) in the last 24 hours, so maintenance submits nothing for it instead of adding another receipt (#6696). It is tried again once the page, the planner or the write changes, or when the oldest refusal is 24 hours old. | Read the last refusal with `gbrain write-request -- <request_id>` (named in the message) and fix what it names. Doctor `maintenance_write_drift` lists every held-back write with its exit. || <a id="canonical_file_absent"></a>`canonical_file_absent` | `source_changed` (`restore_page` / `gbrain restore`) | On a brain without managed persistence, a restore that writes no file (`sync.write_through` off, a sandbox, a database-only source) of a soft-deleted page whose recorded file is no longer among the files sync imports (#6609). A plain restore would be undone by the next `gbrain sync --full`, so nothing was restored. Not retryable; the fix asks the user. | Ask the user. To keep the page with its file: put the file back at its recorded path, commit it and `gbrain sync --source <source>`. To keep it database-only: `gbrain restore <slug> --source-id <source> --detach` (MCP `restore_page` with `detach: true`), which forgets the recorded file and stamps `database_only_reason='detached'`. See [restoring a page whose file is gone](../storage-tiering.md#restoring-a-page-whose-file-is-gone). || <a id="pending_import"></a>`pending_import` | `source_changed` (detail `file_database_drift`, reason `pending_import`) | The page's canonical file holds a change committed through Git (another agent's commit, a pull) that managed sync has not imported yet: the file on disk is exactly the blob `HEAD` holds for its path and not the one the source's last imported commit holds. The message is "The canonical file holds a committed Git change that sync has not imported yet." Nothing was overwritten. Since #6693 the receipt records origin `pending_import`; a write refused because sync holds the file records origin `sync_held` (see [held files](#held-files-and-content-refusals)). | A `remember` needs nothing from the caller: its `fix.next` is `wait`, the fact is kept in the receipt, and the first managed sync that imports the file (any outcome, a partial run included) makes one replay attempt on the original caller's lane with the fact's original `valid_from` and expiry (the sync result's `replayedRemembers` counts examined, replayed, waiting, skipped, remaining; at most 50 per run and 30 s). Do not save the fact again. A remember refused while sync held its file is replayed the same way once the repaired file is imported. A replay that is refused (authority revoked, page rewritten) stays listed by `gbrain repair failed-writes --source <source>` for a person. Any other write (`put_page`, `add_timeline_entry`) is never replayed automatically, because its body would replace the imported change: wait for the source's running sync owner (`gbrain serve`, autopilot or a sync job) to import the commit, which the refusal's read-only fix `gbrain sync status --source <source> --json` shows, then read the page again and resubmit with a new request ID. Neither refusal tells the caller to start a sync, because a second sync beside a running owner competes with it; when status shows no owner running, ask the user to sync the source on its host. An uncommitted hand edit still refuses `file_database_drift` and needs reconcile. With `persistence.refresh_barrier` on, a `put_page`, `capture`, `remember` or `add_timeline_entry` waits for the import instead of being refused ([deferred writes](#pending_import_expired)). |diff --git a/docs/tutorials/company-brain.md b/docs/tutorials/company-brain.mdindex 03b7b4d457..ea2154869d 100644--- a/docs/tutorials/company-brain.md+++ b/docs/tutorials/company-brain.md@@ -144,7 +144,7 @@ gbrain access rule list --source team-a # store, revisions, applied ruA remote read of a page under a rule needs the caller's member to be on every rule covering it and on the page's own `readable_by`; hatches, grants and `--as` never relax it. Narrowing applies at once. Moving a rule's prefix restricts the new folder at once and keeps the old folder under the old readers until approval. A change that widens (removing a rule or a reader, or releasing a moved rule's old folder) is held until `gbrain access apply --source team-a` previews who would gain access and `gbrain access apply --source team-a --yes --expect <plan_hash>` approves it. If an apply stops halfway, its prefixes read as nobody until `gbrain access resume --source team-a`. `gbrain access rule history` and `rule revert --to <revision>` work over the revision log, and `gbrain export` carries the applied rules so `gbrain import` installs them before any page.-**Page rules: keep one page to some members.** `gbrain access rule add --slug notes/plan-example --readers alice-example --source team-a` (preview, then `--yes`) covers exactly that slug, never a folder of the same name or a longer slug; in `access.yml` it is `slug: notes/plan-example` in place of `prefix:`. It writes nothing to the page, so it also narrows a page at the source root, or one whose file was removed from git outside gbrain, where a `put_page` with `visibility: private` refuses `source_changed` ([canonical_file_missing](../guides/write-refusals.md#canonical_file_missing)). It binds the owner too, so list the owner's member to keep the owner reading it. Removing the rule is the undo, a widening held until `gbrain access apply`.+**Page rules: keep one page to some members.** `gbrain access rule add --slug notes/plan-example --readers alice-example --source team-a` (preview, then `--yes`) covers exactly that slug, never a folder of the same name or a longer slug; in `access.yml` it is `slug: notes/plan-example` in place of `prefix:`. It writes nothing to the page, so it also narrows a page at the source root, or one whose file was removed from git outside gbrain, where a `put_page` with `visibility: private` refuses `source_changed` ([canonical_file_missing](../guides/write-refusals.md#canonical_file_missing)). It binds the owner too, so list the owner's member to keep the owner reading it. Removing the rule is the undo, a widening held until `gbrain access apply`. Upgrade every gbrain host that shares the brain first: an older host keeps the page restricted, but refuses its own `gbrain access rule` commands and stops syncing a git-backed source that holds a page rule until it is upgraded.Renaming a page into a ruled folder restricts it at once, and the atoms, concepts, chronicle events and `derived_from` pages made from it follow it, through later renames too. A page that later takes the old slug does not inherit them: they stay under the moved page's rules.diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex c737981cc2..ee25a93f1e 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1537,8 +1537,8 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;{ since: '0.60.676.0', id: 'write_capacity_low_saved_gst2107', text: 'The `write_capacity_low` notice a write receipt carries now opens with "This write was saved" and its fix is the read-only `gbrain doctor --only persistence_capacity --json` (actor agent) instead of a `gbrain config set` cap raise for the user, so an agent reading the end of a successful write no longer reports it as refused. The one-more-year value doctor, the notice snapshot and `/metrics` recommend now uses the 7-day mean rate, so one bulk day is no longer projected for a year; days-to-exhaustion still uses the larger of the mean and the last 24 hours. A `write_quota_exhausted`, `write_quota_insufficient` or background-pause refusal names the same value doctor does instead of sizing the year from the latest 1,000 admissions.' },{ since: '0.60.676.0', id: 'ingest_backfill_409_recovery_gst2112', text: 'A `revision_backfill_pending` refusal (a write to a page the revision backfill has not reached, including the 409 a webhook capture to such a page gets from `POST /ingest`) now names the command that resumes the backfill, `gbrain apply-migrations --force-schema` on the brain host, instead of `gbrain apply-migrations --yes`, which does not resume it once the schema is current. A capture answered 409 stores and queues nothing, so its sender sends it again after the backfill; an `ingest_capture` job already queued for such a page goes straight to dead and is re-run with `gbrain jobs retry <id>`.' },{ since: '0.60.678.0', id: 'unmanaged_push_history_scan_8902', text: 'Four pushes from a checkout that is not a managed worktree now scan every local commit they publish for secrets, not only what they just wrote: the access-policy commit (`gbrain access rule` and the other policy writers), the durability-scaffolding commit of `gbrain sources harden`, `gbrain sources push`, and the first push of `gbrain bootstrap repo` (the whole history, since the remote has no such branch yet). A credential that a commit made with plain `git commit` added, even one a later commit removed, or one in a commit message, now refuses `publish_secret_found` naming the file, line, rule and commit (never the value), and nothing is pushed; history the scan cannot read in full refuses `publish_scan_unreadable`. The local commits stay where they are. `gbrain sources push` now pushes the exact commit it scanned, leased on the remote tip it read, and an allowlist (`.gbrain-scan-allow`) edit it commits itself still publishes; one a script committed is left for the user to review and push. Remove the value from the unpublished commits, or allowlist a false positive by fingerprint, then rerun.' },- { since: 'TBD', id: 'privacy_label_ignored_gst2462', text: 'A page write (put_page, `gbrain import`, `gbrain sync`) that stores a page with an `access` or `confidentiality` value gbrain does not read as private (for example `access: personal`) and no `visibility` now carries one `privacy_label_ignored` safety notice: it names the key and value (a bulk run counts pages by value and names no page), says remote callers read the page like an unlabelled one and, on a source with a git checkout, that the label does not keep it out of git, and asks before adding `visibility: private`. `gbrain doctor --only privacy_label_ignored` counts such pages by value (a warning when the value plainly means private). Who can read a page is unchanged: the recognized values and `visibility.honor_aliases` are as before.' },- { since: 'TBD', id: 'access_page_rules_gst2462', text: 'A folder rule can now name one exact page: `gbrain access rule add --slug <page> --readers <list>` (`slug:` in `.gbrain/access.yml`) restricts that page alone, never a folder of the same name, without writing the page, so a page at the source root or one whose file left git can be narrowed. A write refused because the page\'s file is missing now names this route beside the ghost-page repair. Reads are decided in the database, so they are right for every gbrain sharing it once it is migrated; an older gbrain that syncs an `access.yml` holding a page rule reads the file as invalid, so that source reads as nobody remotely until it is upgraded.' },+ { since: '0.60.680.0', id: 'privacy_label_ignored_gst2462', text: 'A page write (put_page, `gbrain import`, `gbrain sync`) that stores a page with an `access` or `confidentiality` value gbrain does not read as private (for example `access: personal`) and no `visibility` now carries one `privacy_label_ignored` safety notice: it names the key and value (a bulk run counts pages by value and names no page), says remote callers read the page like an unlabelled one and, on a source with a git checkout, that the label does not keep it out of git, and asks before adding `visibility: private`. `gbrain doctor --only privacy_label_ignored` counts such pages by value (a warning when the value plainly means private). Who can read a page is unchanged: the recognized values and `visibility.honor_aliases` are as before.' },+ { since: '0.60.680.0', id: 'access_page_rules_gst2462', text: 'A folder rule can now name one exact page: `gbrain access rule add --slug <page> --readers <list>` (`slug:` in `.gbrain/access.yml`) restricts that page alone, never a folder of the same name, without writing the page, so a page at the source root or one whose file left git can be narrowed. A write refused because the page\'s file is missing now names this route beside the ghost-page repair. Upgrade every gbrain host that shares the brain before adding a page rule. Reads are decided in the database, so an older host still keeps the page restricted, but it refuses its own `gbrain access rule` commands and, on a git-backed source, stops syncing that source with `stored rulebook holds a malformed rule` until it is upgraded.' },];/** The newest disclosed change's release: the notice id moves only when a release adds rows. */diff --git a/src/core/schema-migrations/v303-access-page-rules.ts b/src/core/schema-migrations/v303-access-page-rules.tsindex 91a1ddd4c8..ad13fa5e3c 100644--- a/src/core/schema-migrations/v303-access-page-rules.ts+++ b/src/core/schema-migrations/v303-access-page-rules.ts@@ -12,9 +12,9 @@ import type { Migration } from './types.ts';// pending-coverage matchers cover a slash-less prefix only when it equals the// slug (the SQL twin of folder-rules.ts ruleCovers). Folder prefixes match as// before, so no stamp changes on upgrade; nothing is rewritten. Reads are-// decided here, so an older binary sharing the database reads them right; one-// that syncs an access.yml holding slug: finds it invalid, which reads as-// nobody (fail closed). No schema.sql mirror: like v283, these exist only through+// decided here, so an older binary sharing the database keeps the page+// restricted; its rule commands and its sync of a git-backed source refuse the+// stored rulebook until it is upgraded (fail closed). No schema.sql mirror: like v283, these exist only through// migrations. Provisional number: renumbered at the merge slot.const FOLDER_OR_PAGE = "(length(prefix) <= 512 AND prefix ~ '^(([a-z0-9][a-z0-9._-]*/)+|([a-z0-9][a-z0-9._-]*/)*[a-z0-9][a-z0-9._-]*)$' AND position('..' in prefix) = 0)";