Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: commit ledger, foreign_writers and owner-path guard; behavior-change rows

garrytan83c38dff4a1f
diff --git a/docs/guides/shared-checkout-git.md b/docs/guides/shared-checkout-git.md
index f96093bdd5..f378344b0b 100644
--- a/docs/guides/shared-checkout-git.md
+++ b/docs/guides/shared-checkout-git.md
@@ -547,6 +547,86 @@ A person who needs a plain commit once bypasses it for that one command:
GBRAIN_COMMIT_GUARD=off git commit -m "fix the README by hand" -- README.md
```
+<a id="owner-path-guard"></a>
+### Owner-path guard (managed worktrees)
+
+`gbrain git guard --install` refuses a managed canonical worktree. Its owner
+installs the guard there with
+`gbrain sources guard <source> --install [--mode enforce]` instead. It runs
+only on the source's owner host (any other host is refused
+`permission_denied`), under the worktree's writer lock, from the trusted local
+CLI. The hook goes in a hooks directory private to that worktree
+(`<worktree git dir>/gbrain-hooks`), and only that worktree's
+`core.hooksPath` points at it (`git config --worktree`; gbrain enables
+`extensions.worktreeConfig` when the repository has linked worktrees), so a
+person's own linked checkout of the same repository keeps its hooks. It refuses,
+changing nothing, when another tool's hook lives at the worktree's current
+hooks path.
+
+`--mode enforce` also refuses cherry-pick, revert, rebase and sequencer
+commits: in a managed worktree only the owner commits. The owner's writers
+pass unchanged: the effect worker commits with an empty hooks directory, page
+writes through the door and the in-memory merges are plumbing that runs no
+commit hook, sync's auto-init turns hooks off, `commit-push` names the commit
+lock it holds, and a refresh fast-forward runs no commit hook.
+`gbrain sources guard <source> --status` prints whether it is installed, its
+mode and the effective hooks path; `--uninstall` removes it.
+
+A writer that turns hooks off itself (`git -c core.hooksPath=/dev/null commit`)
+is not stopped by any hook. The [commit ledger](#commit-ledger) names it.
+
+<a id="commit-ledger"></a>
+## Commit ledger
+
+Every commit gbrain makes is appended as one JSON line to
+`<git common dir>/gbrain/commit-ledger.jsonl`: the sha, the writer
+(`commit_push`, `door`, `merge`, `replay`, `effect`, `sync_init`,
+`workspace_push`, `bootstrap`, `hosted_repo`), the worktree, ref, pid and host.
+The file sits inside `.git`, so it is never tracked, and every worktree of the
+repository shares it. Appends take their own lock
+(`commit-ledger.lock` beside it) for microseconds, never while git runs. The
+first append writes a `start` line; at 4 MiB the file rotates to
+`commit-ledger.1.jsonl` (one previous file is kept). A `git commit` gbrain runs
+writes an `intent` line first (the HEAD before it and the message's sha256)
+and the commit line after; a plumbing commit is recorded before its ref moves.
+A failed append never fails the commit: gbrain logs it once, and doctor then
+reports that commit as foreign. Nothing reads or writes the ledger in a
+repo-less brain.
+
+<a id="foreign-writers"></a>
+## Foreign writers (doctor `foreign_writers`)
+
+`gbrain doctor --only foreign_writers` reads every registered source checkout
+on this host, managed worktrees included, once per repository. It is read-only.
+
+- **Foreign commits.** It reads the reflogs of local ref moves (`logs/HEAD`,
+ `logs/refs/heads/*` and each linked worktree's `HEAD` log). A commit created
+ here (`commit`, `--amend`, cherry-pick, revert, rebase or `pull --rebase`
+ picks, `am`, or an `update-ref` after `commit-tree`) that the ledger does not
+ name was made by another writer. Merges, fast-forwards, pulls, resets,
+ checkouts, branch moves and clones are not commits made here. Each is
+ labelled `plain`, `amend`, `rewrite` or `plumbing`; a plain commit made while
+ the enforce guard was installed reads `plain (guard bypassed)`. Any foreign
+ commit fails the check, naming the newest one:
+ `Commit <sha12> (<kind>, "<subject>", <time>) in <checkout> was not made by
+ gbrain; route that writer through gbrain git commit-push or a page write`.
+ Ask the user which job makes such commits before changing anything.
+- **Covered window.** Reflog entries older than the ledger's start (or its
+ oldest retained line after rotation) are reported as uncovered, never
+ foreign. A repository gbrain has not committed in yet has an empty window.
+- **Unconfirmed commits.** A commit whose parent and message match an open
+ intent within 60 seconds (gbrain crashed between `git commit` and the
+ ledger line) is a warning and is never written back to the ledger.
+- **Dirty page files.** Untracked and modified files under the source roots
+ are listed by age (their mtime), leaving out files gbrain is about to commit
+ (a queued or running git effect, or the write-through pending ledger). Files
+ older than 30 minutes warn.
+
+The JSON (`details`) carries the window per repository, every foreign commit
+(sha, kind, ref, time, subject, committer), the unconfirmed ones, ref moves it
+could not read, and at most 20 dirty files with the total count. A brain with
+no Git checkout reports `not_applicable`.
+
## Limits
- **Two agents editing the same file at the same time still conflict.** The
@@ -568,9 +648,10 @@ GBRAIN_COMMIT_GUARD=off git commit -m "fix the README by hand" -- README.md
[source root](#source-roots) recorded, gbrain refuses to publish one that
reaches outside it. `gbrain doctor` reports such unpushed commits
(`commits_outside_source_root`), a checkout behind its upstream for over an
- hour (`checkout_lagging`), pending or long-staged files (`dirty_age`), and
+ hour (`checkout_lagging`), pending or long-staged files (`dirty_age`),
local versions the opt-in [quarantine](#quarantine) parked
- (`quarantined_changes`).
+ (`quarantined_changes`), and every commit gbrain did not make
+ ([`foreign_writers`](#foreign-writers)).
- **No page-aware merge.** Two edits to the same page meet as a text conflict;
a merge driver that understands page sections is a planned follow-up.
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 5f3c140e04..c20fb817f2 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1451,6 +1451,10 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.583.0', id: 'sync_write_through_off_writeback_7084', text: 'With `sync.write_through` off, a managed `gbrain sync` no longer writes its canonical correction of a file (the frontmatter, title or tags the page keeps when an upstream edit drops them) back into the checkout (#7084, #8118). The page keeps the correction in the database only, as on a read-only mirror source, and `git status` stays clean. With `sync.write_through` on, nothing changes. Files already rewritten by earlier versions are not touched; restore them with `git checkout -- <paths>` or commit them.' },
{ since: '0.60.583.0', id: 'managed_sync_dry_run_counts_7087', text: 'A managed `gbrain sync --dry-run` now reports the files the run would add, modify, soft-delete and rename, and prints them as one line (#7087). It used to report the cursor\'s committed counts: zero before a run, or the previous run\'s counts when nothing had changed.' },
{ since: '0.60.583.0', id: 'frontmatter_missing_source_dir_7889', text: 'A registered source whose directory does not exist is no longer reported frontmatter-clean (#7889). The frontmatter audit marks it `missing` (and lists it under `missing_sources`), and doctor `frontmatter_integrity` and `frontmatter_repairable` warn with the path and ask you to restore it or run `gbrain sources set-path <id> <path>`; they no longer call it clean or blame a timeout.' },
+ // PR B (convergence lane L4): commit ledger, foreign_writers, owner-path guard. since is stamped at the merge slot.
+ { since: 'TBD', id: 'commit_ledger_prb', text: 'Every commit gbrain makes is now recorded as one line in `<git common dir>/gbrain/commit-ledger.jsonl` (inside `.git`, never tracked, rotated at 4 MiB to `commit-ledger.1.jsonl`). A failed append never fails the commit; it is logged once.' },
+ { since: 'TBD', id: 'doctor_foreign_writers_prb', text: 'New doctor check `foreign_writers`: in every source checkout on this host, managed worktrees included, a commit gbrain\'s commit ledger does not name fails the check with the newest such commit and a fix that asks who makes it; an unconfirmed commit (a crash between `git commit` and the ledger line) and page files left uncommitted for over 30 minutes warn. Commits before the ledger started are reported as uncovered, not foreign. A repo-less brain reports not_applicable.' },
+ { since: 'TBD', id: 'sources_guard_prb', text: 'New `gbrain sources guard <source> --install|--uninstall|--status [--mode enforce]`: the commit guard on a managed source\'s worktree, from its owner host only, installed in a hooks directory private to that worktree. `--mode enforce` also refuses cherry-pick, revert, rebase and sequencer commits. `gbrain git guard` is unchanged.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */