Garry's Opinionated OpenClaw/Hermes Agent Brain
Committing and pushing in a brain checkout other agents share
Goal
Many writers commit to the same brain checkout on one machine: interactive sessions, sub-agents, cron jobs, the post-commit hook, gbrain's own page writes and sometimes a host sync daemon. Every one of them commits and pushes with one command, and none of them can stash, rebase, revert or ship another writer's half-written files.
Say to your agent: "Commit the meeting notes you just wrote to my brain and push them."
Your agent runs scripts/brain-commit-push.sh "meetings: 2026-04-03 product review" meetings/2026-04-03.md
(or gbrain git commit-push -m "<msg>" -- <paths> when the brain has no helper).
Say to your agent: "Bring my brain checkout up to date before you start writing."
Your agent runs scripts/brain-commit-push.sh --pull (or gbrain git commit-push --pull).
Say to your agent: "The push conflicted on people/alice-example.md. Keep the version on GitHub."
Your agent runs gbrain git commit-push --push-only --expect-remote <sha> --resolve people/alice-example.md=theirs,
copying the remote commit from the conflict report.
Why the old way broke
Skills used to tell each agent to run git pull --rebase (sometimes with
--autostash) and then a plain push, directly in the shared working tree. A
rebase stashes every other process's uncommitted work for as long as it runs.
When it crashes, times out, hits a busy index.lock or conflicts, it leaves a
.git/rebase-merge directory with someone else's files inside its autostash.
Every later pull then refuses, and an agent that "repairs" it by hand can
silently revert another agent's in-flight edit. A repo-wide git add -A or
git commit -a has the same problem from the other side: it commits whatever
another writer has half-written.
The protocol in plain words
gbrain git commit-push does five things, in this order:
- Takes this checkout's commit lock, briefly. One commit lock per
checkout, held only while it stages and commits (and later while it
fast-forwards the checkout), never across the network. A second writer
waits (60 seconds by default) and then fails with
commit_lock_busyinstead of skipping silently. The push itself runs under a separate push lock, so a slow remote never blocks commits or gbrain's own page writes. - Commits only the paths you name. It stages and commits exactly those
paths (
git add -u -- <paths>for tracked ones, so a deletion under an ignored directory still commits,git add -A -- <paths>for new files, thengit commit --only -- <paths>), each marked literal (:(literal)<path>), so a name with*,?or[matches only itself. The repository's hooks run as they do for a plaingit commit: a pre-commit check that picks files by pattern still sees them and can refuse the commit. Another writer's dirty files are never staged, committed, stashed or touched. A file another writer already staged under a directory you named is refused (commit_prestaged_paths) instead of swept in; name the file to claim it. A path outside the brain's source root is refused (commit_outside_source_root). When git refuses the commit (a hook, a missing identity, a busy index), the paths are unstaged again, so nothing is left in the shared index for another writer's commit to pick up. - Pushes your commit, and merges remote commits in memory when the push is
rejected. It fetches, builds the merge without touching any working tree
(
git merge-tree --write-treeon git 2.38 and later, a three-way merge in a temporary index on older git) and pushes the merge commit. Local commits whose patch the remote already has (a cherry-picked or rebased copy) are left out of that merge: the local commits are replayed in memory onto the remote tip without them, so a copy the remote edited since never conflicts and a copy the remote reverted is never put back. The merge commit's message lists the commits it left out. It makes up to eight attempts, backing off, while the remote keeps moving. One push at a time runs per checkout and it publishes the newest local commit, so writers that queue behind it share its push. The post-commit hook never waits: when a push is already running it asks that push to publish its commit too (push_deferred). - Advances the shared checkout fast-forward only.
git merge --ff-onlyrefuses, and changes nothing, when another writer moved HEAD or has a local edit in a file the merge must change. The push has still landed; the checkout just lags until the next commit-push or pull (pushed_checkout_lagging). - Stops on a real conflict. When both sides changed the same file, it changes nothing and asks you which version wins (conflicts).
Remote commits therefore arrive as merge commits named
gbrain: merge origin/<branch> into <branch>, so brain history is no longer
linear. That is the price of never rewriting a working tree other writers
are using.
Commands
A brain hardened with gbrain sources harden has a committed helper,
scripts/brain-commit-push.sh. It hands the same arguments to
gbrain git commit-push, so either form works:
# Commit and push the files you wrote (paths are relative to the current directory)
scripts/brain-commit-push.sh "people: add alice-example" people/alice-example.md
gbrain git commit-push -m "people: add alice-example" -- people/alice-example.md
# Publish commits already on the branch (the hook's job; also the retry after a push failure)
scripts/brain-commit-push.sh --push-only
gbrain git commit-push --push-only
# Bring remote commits in (fast-forward, or an in-memory merge); never pushes
scripts/brain-commit-push.sh --pull
gbrain git commit-push --pull
# Commit and push the write-through files gbrain could not commit (doctor's dirty_age names them)
gbrain git commit-push --pending
# Stop tracking files and keep them on disk (see "Untrack" below)
gbrain git commit-push --untrack -m "stop tracking the archive" -- archive-example
# Preview: runs the real run's path checks (a path outside the source root, a sparse-checkout
# exclusion and the rest refuse here too), prints the paths, branch and lock it would use; takes no lock, writes nothing
gbrain git commit-push --dry-run -m "people: add alice-example" -- people/alice-example.md
Flags: --path <dir> acts on a checkout other than the one containing the
current directory (the paths are then relative to <dir>, like git -C),
-m repeats like git commit (each one is a new paragraph, so a second -m
carries a trailer), --json prints one JSON result (or the error envelope),
--require-clean makes --pull skip when the checkout has any local edit
(the rule the unattended pull cron uses), --scan-timeout <seconds> gives the
secret scan every push runs a longer budget than its 300 s default. The command is local only: it pushes
with this machine's git credentials and is never exposed over MCP.
When gbrain is not installed on the machine, or the installed one predates the
scan on every push (its git commit-push --help has no --scan-timeout), the
helper falls back to a locked path-scoped commit and pushes nothing, because only gbrain scans the commits it
publishes for secrets. It exits 4 (0 when the branch is already on the remote),
logs the commit as local-only and tells you to install gbrain and run
gbrain git commit-push --push-only. A named path git left out of the commit
is reported as commit_paths_skipped, as gbrain git commit-push reports it;
the helper then exits 1, or 4 when the commit is not on the remote.
In a managed canonical worktree (gbrain sources writer git-durability) its
persistence owner is the only Git publisher. Save pages with put_page,
edit_page, remember or capture. For files written there outside gbrain
(see files that are not pages),
gbrain git commit-push -m "<msg>" -- <paths> commits only the named paths
under the checkout's commit lock and reports committed_local (or
nothing_to_commit) with managed: true: it never fetches, merges, pushes or
moves the checkout, and refuses --pending, --branch, --resolve and
--allow-outside-source-root there (commit_paths_invalid). Its
unpublished field counts the commits the upstream lacks as last fetched
(null when no fetched upstream can be read), upstream names the branch's
configured upstream (null when it has none), and it writes no push-log line. Commits wait for
the owner's next Git publish; gbrain git commit-push --push-only --keep-checkout
publishes them now. --push-only without --keep-checkout is still refused with
writer_coordinator_required.
A checkout with no Git remote at all (git remote prints nothing and the
branch names none) has nothing to publish to: gbrain git commit-push -m "<msg>" -- <paths>
commits only the named paths under the commit lock and reports
committed_local with no_remote: true, saying nothing was pushed.
--push-only, --pending, --branch, --resolve/--expect-remote and
--require-clean are refused there (commit_paths_invalid). Add a remote and
set the branch upstream, then gbrain git commit-push --push-only publishes the
local commits. A branch that names a remote which does not exist still refuses
(git_unavailable).
The one form a managed worktree accepts is --push-only --keep-checkout. It
publishes the commits already on the branch, merging a moved remote in memory,
but never moves the checkout and skips its pre-push hook, so
gbrain sources refresh stays the only way remote files enter the checkout.
The owner's Git effects use it on their own when another machine pushed first;
you run it only to settle a conflict the owner reports.
Say to your agent: "My brain's Git backups stopped pushing. Find out why and get them moving again."
The agent reads gbrain sync status --source <id> --json (git_push_holds) or
gbrain doctor --json (parked_effects). Effects parked after repeated push
failures go through gbrain sources writer retry-effects <source> --parked-pushes
(preview with --dry-run); a conflict names the user's choice first.
Preview the secret scan
gbrain git scan [--path <dir>] [--from <rev>] [--to <rev>] [--json] runs the
scan a push runs, over --from..--to (by default the upstream as last fetched,
up to HEAD), with the checkout's .gbrain-scan-allow, and changes nothing:
no fetch, lock, commit or push. It says whether a push would refuse
(would_refuse) and lists each finding's commit, path, line, rule and
fingerprint, never the value. Before an upgrade,
--from $(git rev-list -1 --before="30 days ago" HEAD) shows what the last 30
days of commits would have hit. gbrain git commit-push --dry-run names the
marker that makes a checkout a managed canonical worktree, or none; every push
mode scans either way.
A finding that is not a secret: add its fingerprint (sha256: and 16 hex
characters, as the preview prints it) as a line of .gbrain-scan-allow at the
checkout root (# starts a comment). A rule that fires on many harmless values
in one kind of file takes a rule entry instead, path:<glob> pattern:<rule>,
which allows only that rule in the matching files; the preview lists each hit it
allowed with the line that allowed it, and names any line that allows nothing
because it is malformed or names an unknown rule
(details). The scan reads the file from the working
tree, so the next push uses it without a commit. That is deliberate: the file is
the local user's answer to the scan, and writing it takes local write access to
the checkout, which could push directly anyway. In a managed root below the
repository's top level the file sits at that root and its path globs match
paths relative to it. Keep it out of commits (list it
in .git/info/exclude): a commit that changes it changes what the scan sees, so
no automatic push publishes it. A fingerprint accepts that exact value wherever
it appears; a line without sha256: is a path glob and accepts every finding in
the files it matches.
Outcomes
Every run ends in exactly one of these. Successes exit 0; every failure prints
an [Error <code>] line (or a JSON envelope with --json) and exits non-zero.
Follow the error's fix.next as the
agent operator protocol describes.
| Outcome or code | Exit | What the agent does next |
|---|---|---|
pushed |
0 | Done. Report the commit; a hosted link to the file works now. |
push_deferred |
0 | Only with --require-clean (the post-commit hook): another push was running in this checkout and was asked to publish HEAD too when it finishes. Nothing to do. |
nothing_to_commit |
0 | The paths had no change. Any earlier local commit on the branch was still pushed, so nothing is waiting (with no_remote: true or managed: true, nothing is pushed; a managed checkout's unpublished counts the commits still waiting). |
committed_local |
0 | A managed canonical worktree, or a checkout with no Git remote (no_remote: true): the paths were committed locally and nothing was pushed (a managed result's unpublished counts the commits waiting). Report the commit; it reaches a remote on the owner's next publish, or after a remote is added and --push-only runs. |
pushed_checkout_lagging |
0 | The push landed but this checkout was not advanced; a [gbrain notice] names the files that blocked it. Change nothing: the next commit-push or --pull catches the checkout up. Never stash or reset to "fix" it. |
commit_lock_busy |
1 | Another writer held the lock for the whole wait; nothing was committed. Retry once. If it is still busy, tell the user which checkout and lock path the message names and stop. |
checkout_not_a_source |
1 | The checkout commit-push resolved from the working directory (no --path) is not one of the brain's source checkouts on this host, typically a wrapper that changed into another repository; nothing was staged. The message lists the brain's checkouts. Tell the user to make the script pass --path with the absolute brain checkout. A repository that only encloses a source checkout (a brain cloned inside another repository) is not one; a source registered at a subdirectory its checkout tracks is. A host whose brain records no source checkout, or a checkout with gbrain.sourceRoot set, is never refused this way. |
commit_paths_invalid |
1 | No paths, a path outside the checkout, the checkout root itself, or a path git would not stage (one outside a sparse-checkout definition included). Name the explicit files you wrote and rerun. |
commit_paths_skipped |
1 | Git left a named path out of the commit: a modified file flagged assume-unchanged or skip-worktree (reason assume_unchanged, skip_worktree) a file inside a nested Git repository (not_staged), or, under a named folder, a tracked file the index holds as staged for removal while it is still on disk, as after git rm --cached (staged_for_removal; nothing is committed, and the refusal names both ways out: gbrain git commit-push --untrack to stop tracking it, git restore --staged to keep it tracked). The other named paths were committed (and, on a classic checkout, pushed); detail lists each skipped path with its reason and a plain why (for example "it sits inside the nested Git repository brain/imports"), the commit and the pushed head, or the push failure (publish) when the push failed too; the push log gets one [push] SKIPPED, NEEDS ATTENTION line with the same reasons. --dry-run runs the same check and reports the same paths and reasons, without writing the push log. An empty or broken .git folder, a .git file pointing at a repository that no longer exists, or a .git link to the repository's own .git, is not a nested repository: Git commits the files under it, and so does commit-push. A path spelled through a symlinked folder (a source path that links into the repository) names the file at its real place in the checkout. Check the flags with git ls-files -v -- <path>; clear them only after the user agrees, one flag per call (git update-index --no-assume-unchanged -- <path>, git update-index --no-skip-worktree -- <path>; given both, git clears only the first), and remember skip-worktree is often set on purpose to keep local edits out of commits, or move the file out of the nested repository, then rerun. A skip-worktree file absent from disk (a sparse checkout), a flagged gitlink and ignored files under a named directory are not reported. |
commit_paths_unmerged |
1 | A named file still has unresolved merge conflicts in the index (after a merge, rebase or stash pop that stopped on a conflict), so committing it would publish its conflict markers; nothing was staged or committed, and the file stays unmerged. detail lists the files. Show the user git diff -- <file>, resolve each one with them (edit out the markers, keeping the changes from both sides that belong in the file: one side may be a write gbrain made, so never discard a side wholesale), mark it resolved with git add -- <file>, then rerun. git ls-files -u -- <file> prints nothing once it is resolved. A write-through file gbrain could not commit this way stays in the pending ledger until it is resolved. |
commit_prestaged_paths |
1 | Another writer staged files under a directory you named; nothing was staged or committed. Name your own files explicitly. Unstage the others (git restore --staged -- <file>, which keeps their bytes) only after the user agrees. |
commit_outside_source_root |
1 | The commit, or a local commit about to be published, changes files outside the brain's source root; nothing was pushed. Show the user git show --stat <sha>; rerun with --allow-outside-source-root only if they want it published. |
git_index_locked |
1 | A git command that does not take the writer lock held index.lock. Retry once after a few seconds. |
git_index_stale |
1 | An index.lock older than 10 minutes blocks the checkout. Check that no git command is running there, tell the user, and remove the named lock file only with their agreement. |
git_operation_in_progress |
1 | A rebase, merge, cherry-pick or revert is unfinished in the checkout. gbrain never aborts it for you. Follow stuck rebase. |
git_detached_head |
1 | The checkout is on a detached HEAD or an unborn branch. Check out the branch the remote tracks (git switch <branch>), or make the first commit, then rerun. |
publish_secret_found |
1 | On every push gbrain git commit-push makes (commit mode, --pending and --push-only; --scan-secrets is accepted for older scripts), so also the post-commit hook gbrain sources harden installs and scripts/brain-commit-push.sh, and on every automatic publish: the one gbrain sources refresh runs on its own, the push of a managed worktree's Git effects, doctor git_convergence's push fixes, the access-policy and durability-scaffolding commits, gbrain sources push and the first push of gbrain bootstrap repo (#8902; there the remote has no branch yet, so the whole history is scanned). A commit about to be pushed that gbrain did not make for a page write (its commit ledger records its own page-write commits, whose bodies are stored raw by design and are not scanned; a Git effect's commit counts only by the sha gbrain created for it, when its files held the bytes the effect wrote, so an amended or reworded copy is scanned; one that adopted a file edited outside gbrain, or one older than the retained ledger, is scanned) adds a value that looks like a secret, in its message, an added line (even one a later commit removed) or a merge resolution, adds text too large to scan, or changes .gbrain-scan-allow or a .gitattributes (files that decide what the scan sees); nothing was pushed. The message names each file, line, rule and commit, never the value. Ask the user: remove the value from those unpushed commits, or add a false positive's fingerprint to .gbrain-scan-allow, then retry. A commit that changes .gbrain-scan-allow or a .gitattributes is never published automatically: the user reviews it and pushes it. The exception is the commit gbrain sources push or gbrain bootstrap repo makes itself from files it has just scanned with that allowlist. Never publish them with a command that skips the scan. On a managed worktree its Git effects hold meanwhile (gbrain sync status and doctor list them; the page writes are safe in the database and in local commits); after the fix, gbrain sources writer retry-effects <source> --parked-pushes runs the ones that parked. |
publish_scan_unreadable |
1 | Wherever publish_secret_found can refuse: the scan could not read the commits about to be pushed in full (a missing or corrupt object, git output it does not recognise, or its time budget), so it reported no secret and nothing was pushed. When it ran out of time (a first push of a long history can need more than the 300 s default), the fix is the same command with --scan-timeout <seconds>, four times the budget and at least 1200: run it; the scan still reads every commit, and prints its progress on stderr. gbrain git commit-push, gbrain sources push and gbrain bootstrap repo take --scan-timeout. Otherwise run git fsck in the checkout, fix what it names, then retry. When the remote has no such branch, a managed worktree's Git effect scans the branch's whole history and creates it only when that scan passes; a history too large to scan in the owner process holds the effects with this code and names git ls-remote --heads <remote>: check the upstream, then point it at the right branch or review the history and push the branch yourself. Never publish with a command that skips the scan. On a managed worktree its Git effects hold meanwhile, as for publish_secret_found. |
integrate_conflict |
1 | Local and remote commits changed the same file; nothing was merged and the checkout is unchanged. Stop, relay the question to the user, then resolve. |
push_credential_refused |
1 | The Git host refused the push for the credential git used: "Repository not found" (HTTP 404, what a host tells an account that cannot see a private repository) or HTTP 403 (permission denied). The commit is durable locally; nothing was pushed and gbrain did not retry, because the host refuses the same credential every time (before this code, the refusal was push_unconfirmed, exit 4, and read as transient). The message names the credential helpers git asked, in the order it asked them, with the scope (system, global, local) and file that configure each, which one answered and the account login it gave; never the secret. gbrain asks git once more to learn this (git credential fill), only after a refusal. Tell the user: they make git use a credential for an account that can push to this repository (often a machine-wide helper answering before the checkout's own); then run gbrain git commit-push --push-only. gbrain never changes which credential git uses. Until a push lands, doctor's git_convergence warns about the checkout at once (credential_refused in its root details) and put_page's lastPushStatus reads needs_attention. The same refusal over SSH is classified too; there git asks no credential helper, so the message says the key ssh offers decides the account. A managed worktree's own Git-effect pushes keep their current retry. |
push_unconfirmed |
4 | The commit is durable locally but no push destination confirmed it (network, credentials, branch protection, a remote that kept moving, or another push that held the push lock for the whole wait). Fix what the message names, then run gbrain git commit-push --push-only. Never force-push. |
writer_coordinator_required |
1 | This is a managed worktree. Stop using git for pages; save them through put_page and the other gbrain write tools. scripts/brain-commit-push.sh refuses this way on a checkout marked managed and commits nothing; gbrain git commit-push refuses this way when git left a named page out of its commit (the same causes as commit_paths_skipped), after committing the other named paths locally. Ask the user before re-saving such a page through put_page with the managed source (gbrain put --source-id <source> <slug>, or source_id over MCP; without it the write goes to the default source): it replaces the stored page with the file's content. |
git_unavailable |
1 | A git command failed, often a missing user.name/user.email or a refusing pre-commit hook. Read the message, fix that, rerun. When the branch names a remote that does not exist (a typo or a broken clone), the run stops before committing: fix the name or add the remote, then rerun. A checkout with no remote at all commits locally instead (committed_local). |
git_command_stopped |
1 | A git command did not finish on its own: it ran past its time limit (reason timeout), its output passed a size limit (reason output_limit: one the calling code set, or the largest string the runtime can hold, about 2 GB), or it ended on a signal (reason signal): something outside gbrain killed it, often the out-of-memory killer, or git crashed (the message then says crashed with and names the signal, such as SIGSEGV; run git fsck on the checkout before the rerun). Unless it crashed, git itself works, and gbrain did not use the partial output. Rerun once; for a signal check the machine first, and if a time limit stops it again, tell the user which command and checkout the message names. Below that runtime limit the size of a listing is never a reason: gbrain reads git's whole output, so naming a folder that holds most of a large checkout works. |
--pull reports up_to_date, advanced, ahead (local commits not yet
pushed; run --push-only), skipped_dirty (only with --require-clean) or
lagging (a dirty file the pull must change blocked it; a notice names it).
All of these exit 0. A diverged branch whose two sides changed the same file
fails with integrate_conflict, the same as a push.
The helper's own exits: 2 for a usage error (no message, or no paths: it refuses a repo-wide commit), 4 when its no-gbrain fallback committed without pushing.
With --json, a success prints outcome, sha (the commit now on the
remote), committed (your commit, or null), branch, remote, paths,
integrated (remote commits merged in), checkout (advanced, unchanged
or lagging), lagging_reason when it lags, and repo.
Every run also appends a line to ~/.gbrain/brain-push.log, which
put_page's push status and gbrain doctor read. An unresolved
integrate_conflict is also recorded in the checkout itself
(git rev-parse --git-path brain-integrate-conflict.json), so put_page
reports it for that checkout until a publish resolves it.
Base check
A script that reads a file, edits it and commits can overwrite a change another writer committed in
between. --base closes that gap: record the blob when you read the file
(git rev-parse HEAD:<path>, or absent for a file that does not exist yet) and pass it back:
gbrain git commit-push --base notes/summary.md=<blob> -m "update summary" -- notes/summary.md
Under the commit lock and before anything is staged, each --base path's blob at HEAD must still
equal the one given. Otherwise the command refuses commit_base_moved naming the path, the base and
HEAD's blob; nothing is staged or committed. Read the file at HEAD again, redo the change and rerun with
the new base. Every --base path must also be one of the committed paths. Pages the agent also edits
are better written with gbrain put (put_page), which carries its own revision check.
Untrack: stop tracking files, keep them on disk
git rm --cached followed by a plain commit is the usual way to stop tracking a file, but in a shared
checkout the commit sweeps up whatever else is staged. --untrack does it in one locked step:
gbrain git commit-push --dry-run --untrack -m "stop tracking the archive" -- archive-example # preview
gbrain git commit-push --untrack -m "stop tracking the archive" -- archive-example
It removes every file the last commit holds under each named path from Git and the index, leaves the files
on disk, and commits exactly those deletions (anything else staged stays staged and out of the commit; a commit a
hook changed is taken back). A path the last commit holds nothing under, or a file marked skip-worktree, refuses
commit_paths_invalid before anything changes. In an ordinary checkout the commit is pushed like any other.
In a managed canonical worktree (the checkout gbrain's persistence owner writes), untracking a page file would
make the next sync delete that page, so --untrack there only takes files under a storage.db_only directory
that the source's gbrain.yml declares, at HEAD and on disk, and that .gitignore ignores. The source's
gbrain.yml sits in the folder the source is rooted in, which can be a folder below the checkout's top
(brain/gbrain.yml); a gbrain.yml anywhere else declares nothing. Only the brain records that folder, so every
untrack there reads the brain first: without migrations, in one read-only transaction, for at most 10 seconds. When
the brain cannot be read, every file refuses and nothing changes: an untrack in a managed checkout needs the brain
reachable, and on PGLite that means nothing else holds it, so stop the process that does (a running gbrain serve or
a sync), then rerun the untrack. A plain commit, and an untrack in a checkout with no managed source, never open the
brain. A file is matched by its path under the declared directory, whatever its extension, with three extra checks:
- A Markdown page file also needs its page slug under a declared directory, because sync keeps a page by its slug
(a folder spelled
Spaced Example/gives slugs underspaced-example/; declare that spelling too). A source rooted in a folder whose slugs start at the repository's top (slug_root_mode: git-root) keeps that folder in each slug, so the refusal asks you to declarebrain/<dir>/as well. - A code-extension file (
.json,.ts,.ymland the rest of sync's code list) is a page with a flattened slug on a source whose sync strategy imports code (codeorauto), and a database-only folder does not make that page database-only. The same brain read refuses one that is a page, whatever the source's strategy is now, and every one on a source whose strategy imports code, page or not yet (its next sync imports it, even one an earlier sync skipped under another strategy). On a Markdown source it also refuses one the source's last finished sync has not seen at its current version (a commit since that sync changed it, or the source has not finished a sync), because a sync that imports it after the check would leave a page the next sync deletes: rungbrain sync --source <id>(it runs even when automatic sync is off for the source), then rerun the untrack. On PGLite the read takes the data directory's one-process lock for its length. - A tracked symbolic link that points out of the declared directory, or a file reached through a symlinked
directory on disk, is refused, and so is a sibling folder that only shares the name as a prefix
(
backups-old/is not underbackups/).
The database row is canonical there, so every admitted page stays live with its content. Anything else refuses
untrack_not_db_only with the index as it was, and the fix names what is missing for each file: declare the folder
(add it under storage.db_only in the gbrain.yml the refusal names and its <dir>/ line to .gitignore, commit
both with gbrain git commit-push -m <msg> -- <that gbrain.yml> .gitignore), add only the .gitignore line, declare
the slug spelling, keep the code-file pages tracked, or free the brain and rerun. --dry-run --untrack makes the same checks, the brain read included,
and lists the files the real run removes. The commit stays local, like every commit-push there; the owner's next Git
publish, or gbrain git commit-push --push-only --keep-checkout, publishes it.
If you already ran git rm --cached by hand, a plain commit-push of those paths refuses
commit_paths_skipped and names the --untrack command that commits the removal.
To undo, git revert <untrack commit> (then commit-push --push-only as usual). The revert writes the
committed bytes back over the files on disk, so copy any local edit to them first.
Source roots
A brain can be one folder inside a larger repository. gbrain sources harden
records the source's folder in the checkout's local git config
(gbrain.sourceRoot, one value per source; nothing when the source is the
whole checkout). With a root recorded, gbrain git commit-push refuses to
commit a path outside it, and refuses to publish any local commit that changes
a file outside it (commit_outside_source_root), whoever made the commit.
That catches a commit made around gbrain, such as a cron's
git add <dir>/; git commit, which takes everything any writer had staged.
Merge commits are not judged: gbrain's in-memory merges bring remote files in.
gbrain's own page writes are always confined to their source's folder; the
one exception is the durability scaffolding gbrain sources harden commits at
the checkout root (the helper script and the agent instructions file).
Say to your agent: "commit-push refused a commit outside the source root. What is in it?"
The agent shows you git show --stat <sha> for each commit the error names.
If you want it published as it is, it reruns
gbrain git commit-push --push-only --allow-outside-source-root.
Page writes that could not commit
gbrain's own page writes (put_page, remember's facts fences, takes, timeline,
lint --fix) commit their one file under the commit lock on a hardened
checkout, waiting 2 seconds for it. They never commit without the lock, since
that races the lock holder on the shared index. When another writer holds the
lock longer, or git refuses the commit, the file is written but not committed,
and gbrain notes it in a pending ledger next to the lock
(git rev-parse --git-path brain-writethrough-pending.log). The next page
write that gets the lock commits the pending files with its own, and
gbrain git commit-push --pending commits and pushes them on demand.
gbrain doctor reports pending files older than 30 minutes as dirty_age.
A file flagged assume-unchanged or skip-worktree that differs from HEAD stays
in the ledger (git add skips or refuses it), and --pending then fails
commit_paths_skipped naming it.
Edits a gbrain commit reverted
When another writer committed a page file while one of gbrain's Git effects
was committing the same file, older gbrain versions could rebuild the effect's
commit on top of the other commit with the bytes gbrain had staged before it.
HEAD then went back to gbrain's version without any warning, the next sync
imported nothing for that file, and the other writer's edit survived only in
its own commit. Current versions never lay staged bytes over a commit that
changed the file: when that commit also changed the file on disk, it stays
HEAD, the effect completes superseded (reason committed_by_another_writer)
and the next sync imports it; when the file still holds gbrain's bytes, the
effect stages them again and commits them on top. A strict source's write
refuses git_target_changed instead.
To find edits a brain already lost this way, look for a gbrain commit (its
subject starts with gbrain:) whose one parent is someone else's commit, made at
most two minutes earlier, that changed a file the gbrain commit also changed.
The loop reads the history reachable from HEAD in one git log pass and then
diffs only those pairs. It writes nothing, takes no lock and doesn't run gbrain,
so it works the same before and after upgrading. On a synthetic history of
200,000 commits it took about 5 seconds and 360 MB of memory.
BRAIN=/path/to/brain-checkout
TOP=$(git -C "$BRAIN" rev-parse --show-toplevel)
g() { git -C "$TOP" -c core.quotePath=false "$@"; }
g log --format='%H%x09%P%x09%ct%x09%s' | awk -F'\t' '
{ parent[$1] = $2; at[$1] = $3; ours[$1] = ($4 ~ /^gbrain:/) }
END { for (c in parent) { p = parent[c]; if (ours[c] && p != "" && p !~ / / && (p in at) && !ours[p] && at[c] - at[p] <= 120) print c, p } }' |
while read -r c p; do
g diff-tree -r --no-commit-id --name-only "$c" | while IFS= read -r f; do
g diff-tree -r --no-commit-id --name-only --root -m --first-parent "$p" -- ":(literal)$f" | grep -qxF -- "$f" \
&& echo "$f: edit in $(g log -1 --format='%h (%an, %ci)' "$p") replaced by gbrain commit $(g log -1 --format=%h "$c")"
done
done
A hit looks like this, one line per file:
notes/alice-example.md: edit in 9ee21f7422 (Alice Example, 2026-11-12 10:23:27 +0000) replaced by gbrain commit 15134a6136
Each line is a candidate, not proof: a gbrain write made right after someone
else's commit on purpose looks the same. To confirm one, read both versions
(git show <their commit>:<file> and git show <gbrain commit>:<file>).
While the commit ledger still holds that time, the reverting effect also has an
earlier effect line there whose sha is not in history and whose parent is the
other commit's parent (git log -1 --format=%P <sha>). Ask the user which
version to keep, then write the chosen content back as an ordinary page write
(gbrain put or put_page with the page's current revision).
Scripts and the managed checkout
On a managed brain the persistence owner is the only Git writer in the
canonical checkout, and gbrain sources refresh is the only way upstream
commits come in. Four rules keep that checkout able to move:
- Scripts commit through gbrain, never with plain
git commit. A cron job or hook that writes files into the checkout and commits them with plain git leaves commits the upstream lacks and nobody publishes. The checkout diverges, and every later refresh refusesrefresh_divergedand changes nothing. Commit the files a script wrote withgbrain git commit-push --path <absolute checkout> -m "<msg>" -- <paths>(run from another repository without--path, it refusescheckout_not_a_source): on a managed worktree it commits only those paths under the commit lock (committed_local) and the owner publishes them on its next Git publish. Pages can also go throughput_page,edit_page,rememberorcapture. CLI calls go through the one wrapper. - Refresh on a schedule.
gbrain sources refresh <id>drains queued writes, refuses new ones until it finishes, fast-forwards withgit merge --ff-onlyand re-syncs every source on the checkout; run it from cron on the owner host (cron line).refresh_divergedmeans something committed outside gbrain:git log --format='%h %an %ad %s' @{upstream}..HEADlists the stray commits. Fix that writer first, then, after the user agrees, publish the stray commits merged with the upstream (gbrain git commit-push --push-only --keep-checkout --scan-secrets --path <checkout>) and retry the refresh, as the refusal says. Never force the checkout. When local commits there are expected (automations committing alongside a sibling checkout that pushes the same branch), each refresh runs that publish itself when the worktree's Git durability is on (sources.refresh_publish_divergedunset;falseturns it off,truepublishes with durability off too), after scanning the local commits for secrets (live sync); it never publishes over a rewritten upstream.gbrain sources git-reconcileruns that publish for every source checkout on the host, and autopilot runs it each tick. To keep one source's local commits on this machine while it still syncs, setsources.auto_reconcile.source.<id> false;set-sync off(below) stops its sync as well. - Stop syncing a source before rewriting its history. Before a
force-push or
git filter-repo, rungbrain sources set-sync <id> off(with the user's agreement) so automatic sync skips it, andgbrain sources mirror-readonly <id>so no managed write touches its checkout. A sync whose recorded base commit no longer exists makes sync and the maintenance cycle re-read the whole tree. After the rewrite, move the checkout onto the new history (upstream rewritten), thengbrain sources mirror-writable <id>andgbrain sources set-sync <id> on. - Decide what a gitignored path is. A page whose file a
.gitignorerule excludes cannot be committed, so its Git effect parks at once asgit_target_ignorednaming the rule (since v0.60.427.0). Either un-ignore it (remove or narrow the rule, commit that, thengbrain sources writer retry-effects <source> --parked-code git_target_ignored) or keep those pages database-only and leave the effects parked. Ask the user which; it decides whether those pages are in the Git backup.
Conflicts
A conflict means this machine's unpushed commit and the remote both changed the same file. On git 2.38 and later that means overlapping changes; on older git (Ubuntu 22.04 ships 2.34) any change to the same file on both sides counts as a conflict, even in different paragraphs.
Nothing changes when it happens: the local commit stays local, the checkout is
untouched and nothing is pushed. The error names the files, the local and
remote commits (in its detail), and a question to relay to the user. Until it
is resolved, every later commit-push from this checkout hits the same
conflict, even for other files, because the unpushed commit is still waiting.
A conflict reported by a scanned publish (a Git effect's push, a refresh
publish) comes only after the secret scan of what the local commits add to the
remote's current tip passed, and its resolve command keeps --scan-secrets.
One kind of conflict settles itself on push. When the remote's version of a
file is one this checkout already had at that path and later replaced with
another version (a stale clone or writer pushed an old copy back, often inside
a merge), gbrain keeps this machine's version: the remote's copy is history
this checkout already moved past. It looks at the last 200 commits that
changed the file. The push lists those files in superseded_remote_paths
(--json) and a [gbrain notice] line, and the merge commit message names
them. A version this checkout never had, a file the remote deleted, and a file
you name with --resolve stay ordinary conflicts. When both kinds meet in one
push, the error lists only the real conflicts (its detail.superseded names
the others), and the --resolve run keeps this machine's version of the
superseded files. --pull still reports them as conflicts; a
gbrain git commit-push --push-only settles them.
To resolve:
Ask the user which version of each file should win, or whether they want the two merged by hand. Choosing a side discards the other side's change to that file, so never pick one yourself.
Look at both versions if it helps the user decide:
git show HEAD:<path>(this machine) andgit show origin/<branch>:<path>(the remote).Rerun with
--expect-remote <remote sha>(copied from the error) and one--resolveper conflicted file, using the path exactly as the error printed it (relative to the checkout root; the error shell-quotes names with spaces or non-ASCII characters):# Keep this machine's version gbrain git commit-push --push-only --expect-remote 1a2b3c4d5e6f --resolve people/alice-example.md=ours # Keep the remote's version gbrain git commit-push --push-only --expect-remote 1a2b3c4d5e6f --resolve people/alice-example.md=theirs # Use a hand-merged copy written OUTSIDE the checkout gbrain git commit-push --push-only --expect-remote 1a2b3c4d5e6f --resolve people/alice-example.md=file:$HOME/.gbrain/merge-alice-example.mdIt builds the same in-memory merge with your choice for each file, pushes it and advances the checkout. A conflicted file left without a
--resolvefails again with every conflicted file listed. If the remote moved since the user chose, it reports the conflict again against the new remote commit instead of applying the choice to a version nobody saw. Delete the merged copy afterwards.A file/directory or rename conflict (one side has
topicas a file, the other as a folder) cannot be settled by picking a side per file, so--resolverefuses it. Move or remove the local path in a new commit (gbrain git commit-push -m "<msg>" -- <paths>), then rungbrain git commit-push --push-only.
Write a merged copy outside the checkout: editing the conflicted file in place leaves it dirty, so the checkout cannot fast-forward over it afterwards.
On a managed worktree the owner's Git effects hold with integrate_conflict
instead (the database already has every page write; only the Git backup
waits). The fix the owner reports adds --keep-checkout and the checkout's
--path; after the choice is pushed, run
gbrain sources writer retry-effects <source> --parked-pushes for the effects
that parked meanwhile, then gbrain sources refresh <source> to bring the
merged remote files in.
Shared append-only files (a log.md every workflow appends to) are the usual
source of conflicts: two appends at the end of the same file overlap. Keep
both sides by merging by hand with file:, or make such files derived instead
of hand-appended.
Quarantine (opt-in)
A checkout where no one is around to answer the conflict question (an unattended agent or a cron) can opt in to quarantine instead:
git -C <checkout> config gbrain.quarantine true
With it on, a content conflict no longer stops the push. gbrain publishes the
remote's version of each conflicted file and every non-conflicting change from
this machine, and keeps this machine's version under a ref named
refs/gbrain/quarantine/<time>-<commit>. Nothing is dropped: the parked
commit is also part of the published history. commit-push prints a
[gbrain notice] quarantine line (the quarantined field in --json), and
gbrain doctor reports the waiting ref as quarantined_changes until the
user is done with it.
Say to your agent: "What did gbrain quarantine?"
The agent shows you the doctor finding and the difference
(git diff <remote sha> <ref> -- <path>). Whatever should stay, it commits
again with gbrain git commit-push -m "<msg>" -- <path>; when you're
done, it deletes the ref with git update-ref -d <ref>.
File/directory and rename conflicts are never quarantined; they stop the push as described above. Quarantine is off by default.
Recovering a stuck rebase
An older helper or agent that ran git pull --rebase --autostash in the shared
checkout and crashed leaves .git/rebase-merge (or .git/rebase-apply)
behind. gbrain then refuses with git_operation_in_progress. The autostash
inside that directory can hold other writers' uncommitted edits, so save it
before anything else. Never delete the directory first.
Make sure the rebase is not still running: no
git rebaseorgit pullprocess in that checkout (ps -ef | grep '[g]it ').Save the autostash to the stash list, where it survives everything below:
cd <brain-checkout> for d in rebase-merge rebase-apply; do f="$(git rev-parse --git-path "$d/autostash")" [ -f "$f" ] && git stash store -m "autostash rescued from a stuck $d" "$(cat "$f")" done git stash listEnd the rebase.
git rebase --abortreturns the branch to where it was before the rebase started, so local commits are kept. If it refuses, usegit rebase --quit, which leaves HEAD, the index and the working tree as they are.Check whether the edits are back:
git rebase --abortre-applies the autostash when it can, sogit statusmay already show them. If so, the stash entry is only a spare copy. If not, show the user the rescued edits (git stash show -p stash@{0}) and ask before putting them back. With their agreement:git stash apply stash@{0}The writers those edits belong to commit them as usual, or you commit them withgbrain git commit-push -m "<msg>" -- <paths>if the user asks.Bring the checkout up to date:
gbrain git commit-push --pull.
Never run these in a shared checkout
Each one moves or captures files other writers are using:
git pull --rebase, and any pull with--autostash: stashes every writer's edits for as long as the rebase runs. Use--pullinstead.git stashin any form other thangit stash store,listorshow: hides other writers' edits.git add -A,git add .orgit commit -awithout explicit paths: commits other writers' half-written files. Name your paths.git reset --hard: discards other writers' edits.git push --force: deletes other writers' published commits.- A plain
git push: not destructive, but it does not take the writer lock or integrate a rejected push. Use--push-only. - Deleting
.git/rebase-mergebefore its autostash is saved (stuck rebase).
gbrain sources harden also sets rebase.autoStash=false, merge.autoStash=false
and pull.ff=only in the checkout's local git config, so a stray git pull
refuses instead of autostashing.
The repository lint bun run check:shared-tree-git fails a gbrain skill,
recipe, template or doc that teaches any of these in a code block or an inline
code span. A line that must name one (a warning, or a single-writer clone such
as a fresh export) carries # gbrain-allow-shared-tree-git: <reason> on the
same line inside a code block, or <!-- gbrain-allow-shared-tree-git: <reason> -->
on the line before it in prose. A list of them, like the one above, sits
between <!-- gbrain-allow-shared-tree-git-begin: <reason> --> and
<!-- gbrain-allow-shared-tree-git-end -->. git push --dry-run is read-only
and never flagged.
Lock contract for host daemons
A process outside gbrain that commits or pulls the same checkout (a host
git-sync service, your own cron script, an OpenClaw host's sync) joins the
protocol by taking the same lock. The simplest way is to call
gbrain git commit-push --pull and gbrain git commit-push -m "<msg>" -- <paths>,
which take it for you. A daemon that runs git itself follows this contract:
- Lock file:
git rev-parse --git-path brain-commit.lock(the commit lock), one per checkout (each linked worktree has its own). The lock is an exclusive OS file lock, the same oneflock -xtakes on Linux and macOS. The file existing means nothing; never delete it. - Legacy lock: helpers and hooks from before this protocol take
gbrain-push.lockin the same directory. gbrain takes both, alwaysbrain-commit.lockfirst; a daemon that may share a checkout with an old helper does the same, in the same order. - Hold it for local changes only: staging, committing, and moving the
checkout. Release it before pushing and push under
brain-publish.lock, as gbrain does. A daemon that pushes while holding the commit lock cannot make gbrain lose or revert its commits, but every gbrain writer waits for it:commit-pushfailscommit_lock_busyafter its wait, page writes leave their files pending, and gbrain's publisher reportspushed_checkout_laggingbecause it cannot advance the checkout. Its own plain push also loses races to gbrain's merged pushes and strands its commit untilgbrain git commit-push --push-onlyruns. - Commit with explicit paths (
git commit --only -- <paths>). A commit without paths takes everything any writer has staged in the shared index. - Mark your children: while holding the lock, set
BRAIN_COMMIT_LOCK_HELDto the lock file's absolute path in the environment of anything you start that may take it, such asgbrain git commit-pushor agit commitwhose post-commit hook runs gbrain. gbrain honors the marker only when it names this lock and the lock really is held, so a stale, copied or generic (1) marker cannot skip the lock. - Wait time: gbrain waits
GBRAIN_COMMIT_LOCK_WAIT_SECONDS(aliasGBRAIN_PUSH_LOCK_WAIT_SECONDS), default 60, then fails withcommit_lock_busy. Wait the same way and fail loudly; never skip silently. A push waitsGBRAIN_PUBLISH_LOCK_WAIT_SECONDS(default 300) for another push in the same checkout, then fails withpush_unconfirmed. - Inside the lock: integrate with
git fetchplusgit -c merge.autoStash=false merge --ff-only, or callgbrain git commit-push --pull; never rebase, stash or reset the shared tree.
cd <brain-checkout>
exec 8>"$(git rev-parse --git-path brain-commit.lock)"
flock -w "${GBRAIN_COMMIT_LOCK_WAIT_SECONDS:-60}" 8 || { echo "commit_lock_busy" >&2; exit 75; }
exec 9>"$(git rev-parse --git-path gbrain-push.lock)"
flock -w "${GBRAIN_COMMIT_LOCK_WAIT_SECONDS:-60}" 9 || { echo "commit_lock_busy" >&2; exit 75; }
export BRAIN_COMMIT_LOCK_HELD="$(git rev-parse --path-format=absolute --git-path brain-commit.lock)"
gbrain git commit-push --pull
gbrain git commit-push -m "host sync: daily notes" -- daily/
Commit guard (opt-in)
gbrain git guard --install adds a local, untracked prepare-commit-msg hook
to the checkout. It refuses every commit that gbrain did not make under the
commit lock: a plain git commit, -a, --amend, and --no-verify too,
because that flag skips only the pre-commit and commit-msg hooks. A refused
commit changes nothing; whatever its writer staged stays staged. gbrain's own
commits (commit-push, page writes, the helper, including its no-gbrain
fallback) pass because they name the lock they hold. A merge commit, and a
commit that finishes a merge, cherry-pick, revert or rebase, pass too:
refusing those would leave the operation half done in the shared tree.
gbrain git guard prints whether it is installed, and
gbrain git guard --uninstall removes it. It refuses to replace another
tool's prepare-commit-msg hook and needs git 2.31 or later. It is off
unless you install it.
Say to your agent: "Stop crons and other scripts from committing to my brain around gbrain."
Your agent runs gbrain git guard --install in the brain checkout.
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
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 worktree added
later with git worktree add inherits the hooks path (git copies
config.worktree); the guard lets its commits through, and
git config --worktree --unset core.hooksPath in that worktree restores its
own hooks.
A writer that turns hooks off itself (git -c core.hooksPath=/dev/null commit)
is not stopped by any hook. The commit ledger names it.
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.
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'sHEADlog). A commit created here (commit,--amend, cherry-pick, revert, rebase orpull --rebasepicks,am, or anupdate-refaftercommit-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 labelledplain,amend,rewriteorplumbing; a plain commit made while the enforce guard was installed readsplain (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. An older gbrain co-installed on the host (one without the commit ledger) also reads as a foreign writer; a foreign commit whose message carries agbrain-*:trailer is flaggedgbrain_trailerand named as possibly that, but still fails, since a trailer alone proves nothing. 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 commitand 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. Whatever the
scan could not read leaves it partial (a warning) with the reasons in
partial_reasons: a root inside a Git checkout that git cannot read, source
roots past the 50-root cap, an unreadable ledger, a git status that failed
or timed out (it gets up to 30 s within doctor's budget), or doctor's budget
running out. A brain with no Git checkout reports not_applicable; a scan
that skipped a root never does.
Limits
- Two agents editing the same file at the same time still conflict. The
lock serializes commits, not edits: if two writers change one file, the
second commit carries whatever is on disk when it commits, and edits on two
machines meet as an
integrate_conflict. When agents routinely write the same pages, use managed mode, where pages go throughput_pageand one persistence owner (topologies). - git older than 2.38 has no
merge-tree --write-tree, so any file changed on both sides is a conflict, even when the changes do not overlap. - A lagging checkout is not repaired automatically while another writer's
edit blocks it. The next commit-push or
--pullafter that edit is committed brings it current. - Writers that skip the lock (a hand-run
git commit) are not excluded unless the commit guard is installed. They cannot revert a locked writer's commit, because the checkout only fast-forwards, but a commit without paths can still sweep up staged files; with a source root recorded, gbrain refuses to publish one that reaches outside it.gbrain doctorreports 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), local versions the opt-in quarantine parked (quarantined_changes), and every commit gbrain did not make (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.