Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

GBRA-217 A2: docs (reasons from Git, purge and reasons), key files, Postgres arm row, tools-json golden

garrytan7f0dad5fc2da
diff --git a/docs/architecture/key-files/page-history.md b/docs/architecture/key-files/page-history.md
index 6c7dcb200d..207b1b74eb 100644
--- a/docs/architecture/key-files/page-history.md
+++ b/docs/architecture/key-files/page-history.md
@@ -5,3 +5,6 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
Page-write reasons: admission, the snapshot column, the Git trailer and the remote read projection.
- `src/core/persistence/change-reason.ts` — GBRA-217 page-write reasons ([page history](../../guides/page-history.md#reasons)). `admitChangeReason` canonicalises a `reason` (one line, at most 500 code points) and refuses `change_reason_rejected` (`reason_too_long`, `reason_contains_secret` via `scanTextSpans`) before admission, so no journal row ever holds a refused reason; `page-mutations.ts` runs it before `callerIntent`, so the canonical reason joins replay identity, and `page-batch.ts` runs it per item (all or nothing). `withChangeReason` wraps a page preparer in `service.ts`: its apply stamps `page_versions.change_reason` on the snapshots that transaction created for the page, and, for a world-visible page whose file is published, appends `gbrain-reason: <path>: <text>` to `prepared.file.commit` (a `GitCommitNote` with `trailers[]`), which both the door (`commitThroughDoor`) and the effect commit (`commitMessage`, one trailer line each, `commitMessageArgs` switching to `-F` over 8 KiB) read after apply. The outcome's `reason_recorded.git` is `committed` (strict), `queued`, `private`, `not_file_backed`, `no_repository` (repo-less) or `none`; `settledReasonRecorded` turns `queued` into `superseded` with a `reason_not_committed` notice on the receipt when the Git effect was superseded. Read side: `replacedBecauseSql` in `engine-sql/pages.ts` (remote readers see a reason only when the successor snapshot is world-visible and not `successor_pruned`, which the prunes in `page-state/versions.ts` set). Tests: `test/page-change-reason-gbra217.test.ts`, `test/page-change-reason-git-gbra217.test.ts`, `test/page-change-reason-mcp-gbra217.test.ts`.
+- `src/core/reason-trailers.ts` — GBRA-217 reasons read back from Git ([reasons from Git](../../guides/page-history.md#reasons-from-git)). `readReasonTrailers` streams one `git log` through `hardenedGitStream` with `REASON_LOG_OPTIONS` (`hardened-git.ts`: `-z --first-parent --diff-merges=first-parent --root --name-only --no-renames` and a `%x00%H%x00%(trailers:key=gbrain-reason,valueonly,unfold)` format; no pathspec, no grep), parses records as they stream and stops at a commit cap. `scanSyncReasons` maps each repository path to its newest first-parent commit's trailer (canonicalised by `canonicalChangeReason`, over-long ones counted as malformed, secrets via `scanTextSpans` reported by commit and path, `reason_purge_tombstones` pairs skipped) and counts touches per path; `importHistoryFor` turns that into the `VersionHistory` an import passes to `createVersion` (more than one commit, or a failed or capped scan, sets `historyGap`). `gitTopLevel` returns null outside a repository, so a repo-less or plain-folder source runs no scan. `reasonScanNotices` builds `reason_scan_failed` / `reason_scan_capped` / `reason_trailer_secret`. `cachedSyncReasonScan` shares one scan per (source, root, range) for managed preparations; purge clears it. `scanTrailersCarrying` is purge's read (cap 200,000, or the user's `--reason-scan-limit`). Caps 10,000 (sync) and 200,000 (purge), 120 s timeout. Seams: `__setReasonScanCapsForTests`, `__setReasonGitStreamForTests`. Test: `test/reason-trailers-gbra217.test.ts` (both engines).
+- `src/commands/sync/reasons.ts` + `src/core/persistence/sync-reasons.ts` — the sync wiring. Classic: `incremental.ts` scans `last_commit..pin` once per pass when it imports or renames files (not for a company brain), `full.ts` scans the whole history only when the source already has pages, and `imports.ts` / `renames.ts` / `runImport` pass each file's `history` to `importFile`; `withReasonNotices` puts the notices and `reason_trailers_malformed` on the `SyncResult` (`sync/run.ts` renders them). Managed: `sync-prepare.ts` calls `managedFileHistory` (claim step `reason_scan`) only when the page exists, and `performManagedPass` adds the pass's notices through `withManagedReasonNotices`. Content never waits on the scan.
+- `src/core/facts/purge-reasons.ts` — A7 ([purge and reasons](../../guides/page-history.md#purge-and-reasons)). `scanPurgeTrailers` runs before the purge transaction (no checkout: nothing to scan; a failed read refuses `reason_purge_scan_failed`, `fix.next = wait`; over the cap `reason_purge_scan_capped`, ask_user with `--reason-scan-limit`). Inside the transaction `redactGitEffectReasons` rewrites `commit_line` / `commit_trailers` / legacy `commit_trailer` on queued, failed and committed git effects (a running one refuses `purge_blocked_pending_recovery`) and `recordReasonTombstones` rechecks `head..HEAD` and inserts text-free `reason_purge_tombstones` rows. `purge.ts` `redactPageVersions` sets a quoting `change_reason` to `[purged]`; `purge-verify.ts` checks it and reports pushed commits as the `git_commit_messages` residual.
diff --git a/docs/guides/memory-boundaries.md b/docs/guides/memory-boundaries.md
index cfe6e81c81..1e9699c771 100644
--- a/docs/guides/memory-boundaries.md
+++ b/docs/guides/memory-boundaries.md
@@ -409,7 +409,9 @@ and [isolated local backup guide](in-agent-setup.md#6-back-up-the-complete-local
A write's [reason](page-history.md#reasons) is stored with the page's history
and, when the page's file reaches Git, in the commit message. A purge removes
the database copies it covers, but a commit already pushed keeps its message
-text, just as it keeps the file's earlier contents.
+text, just as it keeps the file's earlier contents. Purge records those commits
+so no later sync stores the reason again ([purge and
+reasons](page-history.md#purge-and-reasons)).
`forget` **expires**: the fact stops being recalled, cannot be saved again in
the same source and visibility, and its row is struck in the page's Markdown.
diff --git a/docs/guides/page-history.md b/docs/guides/page-history.md
index a241738575..2cde438559 100644
--- a/docs/guides/page-history.md
+++ b/docs/guides/page-history.md
@@ -92,8 +92,9 @@ you make yourself can give a reason the same way:
git commit --trailer "gbrain-reason: policies/refunds.md: Client asked for the 30-day window."
```
-A pushed commit message cannot be changed, so treat a reason like any other
-text you push. There is no operation to add a reason to a past write.
+A sync reads these trailers back into page history ([reasons from
+Git](#reasons-from-git)). A pushed commit message cannot be changed, so treat a
+reason like any other text you push. There is no operation to add a reason to a past write.
### Repo-less brains
@@ -114,6 +115,99 @@ the replacing version was later pruned (large pages keep a few versions), its
visibility can no longer be checked and the reason is withheld from remote
callers. Remote reasons go through the same text sanitizer as version bodies.
+## Reasons from Git
+
+When `gbrain sync` imports a changed file from a Git checkout, it reads the
+`gbrain-reason` trailers of the commits it is importing and stores the
+file's reason on the version that import archives. A commit you make yourself
+with `git commit --trailer "gbrain-reason: <path>: <text>"` therefore shows up
+in `get_versions` as `replaced_because`, the same as a reason given to
+`put_page`.
+
+How a sync picks the reason for a file:
+
+- It reads the commits between the last synced commit and the new one along the
+ first-parent line, which is the history the checked-out branch came from. A
+ merge counts as changing every file it changed relative to its first parent.
+- The newest of those commits that changed the file decides. Its trailer for
+ that file is the reason. If it has none, the version gets no reason, so an
+ older reason is never shown against newer text.
+- A merge that resolved a conflict decides with its own trailer, so put the
+ trailer in the merge message. A commit on a merged side branch never decides,
+ whether its edit was kept or discarded.
+- The trailer names the file by its path in the repository (or under the
+ source's folder when the source is a subfolder), then `: ` and the text. A
+ trailer that names no file its commit changed is skipped and counted in the
+ sync result's `reason_trailers_malformed`.
+- A reason from Git gets the same cleanup and limits as a written reason. One
+ longer than 500 characters is skipped and counted the same way.
+- A file's first import creates its page and archives nothing, so it stores no
+ reason, as with a page's first write.
+
+When one sync imports more than one commit for a file, the versions in between
+were never stored. The sync marks the page as having a gap in its history, so
+readers of old versions know some are missing.
+
+A trailer already in Git that looks like a credential is not stored. The sync
+prints the `reason_trailer_secret` notice, which names the commit and the file,
+never the value. Rotate that credential: Git history keeps the commit message.
+
+If reading the trailers fails (a Git error, or more than two minutes), the sync
+prints `reason_scan_failed`. If the range holds more than 10,000 commits, it
+prints `reason_scan_capped` instead of reading them. Either way the content is
+imported, because reasons never hold up content. Every version that sync
+archives stores no reason, and each page it changed is marked with a history
+gap. This release does not backfill reasons for that range: the sync still
+moves its last synced commit forward, and a later sync does not read the range
+again. The reasons are still in Git, and the notice's command lists them:
+
+```bash
+git log --first-parent --format='%H %(trailers:key=gbrain-reason,valueonly)' <range>
+```
+
+A commit and file that a purge has tombstoned (below) never gives a reason
+again, not even on a full re-import.
+
+A source with no Git checkout (a repo-less brain, or a folder imported with
+`gbrain import`) reads no trailers, prints none of these notices and marks no
+gap. Its reasons come only from the writes that carry them.
+
+## Purge and reasons
+
+`gbrain forget <id> --purge` ([expire versus purge](memory-boundaries.md#purge))
+reaches every copy of a reason that quotes the claim:
+
+- **Versions.** The reason is replaced with `[purged]` on every version that
+ carries it, inline and segmented alike, and counted in
+ `removed.page_versions`.
+- **Queued and kept Git commits.** The source's Git effects whose commit message
+ would quote the claim, whether queued, failed or kept after they ran, are
+ redacted in the same transaction: the line becomes `[purged]` and the trailer
+ that quotes it is dropped (`removed.persistence_effects`). If one is being
+ written right now, the purge stops with `purge_blocked_pending_recovery`;
+ retry once it finishes.
+- **Commits already in the repository.** Purge never rewrites Git history, so a
+ pushed commit keeps its message text, as it keeps the file's earlier
+ contents. Before it deletes anything, purge reads the `gbrain-reason` trailers
+ on the source's first-parent history up to `HEAD` (up to 200,000 commits) and
+ records each commit and file whose reason quotes the claim. The record holds
+ no text. No later sync, cold re-import or re-derive stores that reason again.
+ The receipt counts these in `removed.reason_purge_tombstones` and lists the
+ commits under the `git_commit_messages` residual.
+
+Purge refuses before it changes anything when it cannot read that history:
+
+- `reason_purge_scan_failed`: reading the trailers failed (a Git error or a
+ timeout). Nothing was changed; wait, then run the same purge again.
+- `reason_purge_scan_capped`: the history is longer than 200,000 commits. Your
+ agent asks you to choose: purge now and check only the newest commits, with
+ `--reason-scan-limit <n>` set to the number you pick, or stop. With a limit, a
+ reason in an older commit is not tombstoned and a re-import could store it
+ again; the receipt says so.
+
+On a source with no Git checkout there is no history to read, so purge redacts
+the database copies and never raises either refusal.
+
## Choosing how to record a change
A reason explains an edit to one document. Pick the shape that matches what
diff --git a/test/fixtures/goldens/cli/tools-json.json b/test/fixtures/goldens/cli/tools-json.json
index 0f55a875dc..2ce2fe99be 100644
--- a/test/fixtures/goldens/cli/tools-json.json
+++ b/test/fixtures/goldens/cli/tools-json.json
@@ -2,8 +2,8 @@
"golden": {
"exitCode": 0,
"stderr": "",
- "stdoutBytes": 264473,
- "stdoutSha256": "f5647f0a0d45a36ed8685afa000792cef233379d012eeceec6fa2f9366d1b0ee",
+ "stdoutBytes": 265594,
+ "stdoutSha256": "8151ee27ee0fbd9cd271ced0d710c63172ec96af3d57fb4fe50e7f6398ae2843",
"toolNames": [
"remember",
"entity",
@@ -613,6 +613,7 @@
"expected_revision": "string?",
"force": "boolean?",
"ingested_via": "string?",
+ "reason": "string?",
"request_id": "string?",
"slug": "string",
"source_id": "string?",
@@ -660,6 +661,10 @@
"description": "Server-set remotely.",
"type": "string"
},
+ "reason": {
+ "description": "Why this change, one line (max 500 chars); kept in page history.",
+ "type": "string"
+ },
"request_id": {
"description": "Reuse only to retry.",
"type": "string"
@@ -1056,6 +1061,7 @@
"parameters": {
"edits": "array",
"expected_revision": "string",
+ "reason": "string?",
"request_id": "string?",
"slug": "string",
"source_id": "string?",
@@ -1090,6 +1096,10 @@
"description": "From get_page include_content:true.",
"type": "string"
},
+ "reason": {
+ "description": "Why this change, one line (max 500 chars); kept in page history.",
+ "type": "string"
+ },
"request_id": {
"description": "Reuse only to retry.",
"type": "string"
@@ -1246,6 +1256,10 @@
"description": "Revision read; omit to create.",
"type": "string"
},
+ "reason": {
+ "description": "Why this change, one line (max 500 chars); kept in page history.",
+ "type": "string"
+ },
"slug": {
"description": "Page slug.",
"type": "string"
@@ -2979,7 +2993,7 @@
"scope": "read"
},
{
- "description": "Page version history, newest snapshot first: metadata only (id, snapshot_at, title, type, tags, frontmatter) for the newest 20 versions by default. Pass include_body: true for each version's compiled_truth and timeline, and a larger limit (at most 100 over MCP) for older versions. Trusted local and admin callers also get written_by and archived_by (who wrote each snapshot and whose write archived it). revert_version takes the id field.",
+ "description": "Page version history, newest snapshot first: metadata only (id, snapshot_at, title, type, tags, frontmatter) for the newest 20 versions by default. Pass include_body: true for each version's compiled_truth and timeline, and a larger limit (at most 100 over MCP) for older versions. Trusted local and admin callers also get written_by and archived_by (who wrote each snapshot and whose write archived it). replaced_because is the reason given for the write that replaced the snapshot (null when none was given). revert_version takes the id field.",
"idempotent": true,
"local_only": false,
"mutating": false,
@@ -3036,6 +3050,7 @@
"parameters": {
"expected_revision": "string?",
"force": "boolean?",
+ "reason": "string?",
"request_id": "string?",
"slug": "string",
"source_id": "string?",
@@ -3052,6 +3067,10 @@
"description": "Ignore the revision.",
"type": "boolean"
},
+ "reason": {
+ "description": "Why this change, one line (max 500 chars); kept in page history.",
+ "type": "string"
+ },
"request_id": {
"description": "Reuse only to retry.",
"type": "string"
@@ -6971,6 +6990,7 @@
"id": "number?",
"match": "string?",
"reason": "string?",
+ "reason_scan_limit": "number?",
"request_id": "string?",
"source_id": "string?",
"status": "boolean?",
@@ -7011,6 +7031,10 @@
"description": "Optional short reason stored in the text-free purge ledger.",
"type": "string"
},
+ "reason_scan_limit": {
+ "description": "Check only the newest N commits for change reasons quoting the claim (after a reason_purge_scan_capped refusal, with the user's choice); older commits are not tombstoned.",
+ "type": "number"
+ },
"request_id": {
"description": "Reuse only to retry.",
"type": "string"
diff --git a/test/postgres-unit-arms.txt b/test/postgres-unit-arms.txt
index 858931c537..7137cffef0 100644
--- a/test/postgres-unit-arms.txt
+++ b/test/postgres-unit-arms.txt
@@ -413,6 +413,7 @@ test/purge-missing-cache-6911.test.ts
test/purge-read-surfaces.test.ts
test/purge-sync-tombstone-hold-7130.test.ts
test/read-meta-diag.test.ts
+test/reason-trailers-gbra217.test.ts
test/recall-page-fill.test.ts
test/receipt-compaction-newest-sync-gbra130.test.ts
test/reconcile-clears-stalled-hold-7364.test.ts