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.mdindex 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 thatreaches 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.tsindex 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. */