Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: name the managed source in the put_page fix and the gitlink exclusion (GST-2116)

garrytan006dcad4f18c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 37e1e2fd41..9f0f01c447 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,20 +18,22 @@ identifiers and attribution are available in the pre-removal Git revision
| --- | --- | --- |
| A named file is flagged assume-unchanged (or skip-worktree under a named directory) and modified | `nothing to commit`, exit 0; the edit stays uncommitted | `commit_paths_skipped` (reason `assume_unchanged` / `skip_worktree`), exit 1; fix (ask the user): `git update-index --no-assume-unchanged -- <paths>`, and a separate `git update-index --no-skip-worktree -- <paths>` (given both flags, git clears only the first) |
| A named file sits inside an untracked nested repository | exit 0 with nothing committed; beside other paths, `git_unavailable` and nothing committed | the other paths are committed, then `commit_paths_skipped` (reason `not_staged`), exit 1 |
-| The same on a managed canonical worktree, for a page | `nothing to commit; not pushed`, exit 0 | `writer_coordinator_required`, exit 1, naming each page; fix (ask the user): save it through `put_page` |
+| The same on a managed canonical worktree, for a page | `nothing to commit; not pushed`, exit 0 | `writer_coordinator_required`, exit 1, naming each page; fix (ask the user): save it through `put_page` with the managed source (`gbrain put --source-id <source> <slug>`, `source_id` over MCP) |
+| The push fails after a path was skipped | the push error alone | `commit_paths_skipped` still names each skipped path, with the push error beside it, exit 1 (the CLI and the helper) |
+| A gbrain write-through commit (`commitPathsLocked`) that git leaves a named path out of | the commit returned as saved | `commit_paths_skipped` after the rest is committed |
| `scripts/brain-commit-push.sh` without gbrain on the machine | `nothing to commit`, push, exit 0 | the push still runs, then `Error [commit_paths_skipped]` with each path, exit 1 |
| `scripts/brain-commit-push.sh` on a checkout marked managed | one line, `writer_coordinator_required: submit managed changes through persistence`, exit 1 | `Error [writer_coordinator_required]` with `Why:`, `Fix:` (put_page; `gbrain git commit-push` for files that are not pages) and `Next: ask_user`, exit 1 |
-A skip-worktree file absent from disk (a sparse checkout) and ignored files under a named directory are not reported; a named ignored file was already refused by `git add` (`commit_paths_invalid`). Existing brains get the new helper on the next `gbrain sources harden`.
+A skip-worktree file absent from disk (a sparse checkout), a flagged gitlink (its commit lives in the nested repository) and ignored files under a named directory are not reported; a named ignored file was already refused by `git add` (`commit_paths_invalid`). Existing brains get the new helper on the next `gbrain sources harden`.
### Itemized changes
-- `src/core/git/commit-push.ts`: after the commit step, `commitPaths` reads which named paths HEAD still lacks (flagged entries whose bytes on disk differ from HEAD, named files git did not index, and status entries with unstaged changes) and leaves an unindexed file out of `commit --only`, so it no longer fails the other paths. `commitAndPush` (classic, managed and remoteless) throws `commit_paths_skipped` or, for a page in a managed worktree, `writer_coordinator_required`, after committing and publishing the rest; `detail` carries the skipped paths, the commit and the pushed head.
+- `src/core/git/commit-push.ts`: after the commit step, `commitPaths` reads which named paths HEAD still lacks (flagged entries whose bytes on disk differ from HEAD, named files git did not index, and status entries with unstaged changes) and leaves an unindexed file out of `commit --only`, so it no longer fails the other paths. The check runs after the commit's index-restore block, so a failure there never stages a reversal of a commit that already landed. The managed `put_page` fix carries the managed source in its CLI argv and MCP arguments, so following it cannot write a same-slug page in another source. `commitAndPush` (classic, managed and remoteless) throws `commit_paths_skipped` or, for a page in a managed worktree, `writer_coordinator_required`, after committing and publishing the rest; `detail` carries the skipped paths, the commit and the pushed head.
- `src/core/brain-repo-durability.ts`: the rendered `scripts/brain-commit-push.sh` prints the operator contract on its managed refusal, and its fallback (no gbrain) runs the same check after its commit (NUL-separated listings, so a non-ASCII or quoted name is read exactly; a symlink is compared by its link text), leaves a file git did not index out of `commit --only`, and exits 1 with `commit_paths_skipped` after the push.
- `src/commands/git.ts`: when the run fails after the other paths were pushed, the push log still records that push.
- `src/core/error-registry.ts`: new code `commit_paths_skipped` (reasons `assume_unchanged`, `skip_worktree`, `not_staged`).
- Docs: `docs/guides/shared-checkout-git.md` (the `commit_paths_skipped` row, the `writer_coordinator_required` row, the fallback paragraph), `docs/guides/error-codes.md` (regenerated).
-- Tests: `test/git-commit-push-skipped-paths-gst2116.test.ts` (the real CLI and the rendered helper against temp repositories, a bare remote and a managed-root registry: an assume-unchanged page, a nested-repository page beside a committable one, a skip-worktree entry under a named directory, a managed page and a managed non-page file, a remoteless checkout, a named directory inside a nested repository, a run with both flags, the helper's fallback (a non-ASCII path, a nested-repository file beside a committable page, a clean flagged symlink), the helper handing over to gbrain on a managed root, its managed refusal; a named directory beside a sparse entry and an ignored draft still commits with exit 0). Twelve of its thirteen cases fail on master; the one that passes there is the control.
+- Tests: `test/git-commit-push-skipped-paths-gst2116.test.ts` (the real CLI and the rendered helper against temp repositories, a bare remote and a managed-root registry: an assume-unchanged page, a nested-repository page beside a committable one, a skip-worktree entry under a named directory, a managed page and a managed non-page file, a remoteless checkout, a named directory inside a nested repository, a run with both flags, the helper's fallback (a non-ASCII path, a nested-repository file beside a committable page, a clean flagged symlink), the helper handing over to gbrain on a managed root, its managed refusal; a named directory beside a sparse entry and an ignored draft still commits with exit 0). Also: the write-through door, a push that fails after a skipped path (CLI and helper), a named assume-unchanged gitlink beside a committed page (the commit stands and no reversal is staged), and the managed fix's source. Sixteen of its eighteen cases fail on master; the two that pass there are the sparse-entry control and the gitlink case, which guards this change's own post-commit path.
## [0.60.629.0] - 2026-11-09
diff --git a/docs/guides/shared-checkout-git.md b/docs/guides/shared-checkout-git.md
index d56f8b9fc7..4390e269e9 100644
--- a/docs/guides/shared-checkout-git.md
+++ b/docs/guides/shared-checkout-git.md
@@ -181,7 +181,7 @@ Follow the error's `fix.next` as the
| `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. |
| <a id="checkout_not_a_source"></a>`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. Name the explicit files you wrote and rerun. |
-| <a id="commit_paths_skipped"></a>`commit_paths_skipped` | 1 | Git left a named path out of the commit although `git add` exited 0: a modified file flagged assume-unchanged or skip-worktree (`reason` `assume_unchanged`, `skip_worktree`) or a file inside a nested Git repository (`not_staged`). The other named paths were committed (and, on a classic checkout, pushed); `detail` lists each skipped path, the commit and the pushed head. 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) and ignored files under a named directory are not reported. |
+| <a id="commit_paths_skipped"></a>`commit_paths_skipped` | 1 | Git left a named path out of the commit although `git add` exited 0: a modified file flagged assume-unchanged or skip-worktree (`reason` `assume_unchanged`, `skip_worktree`) or a file inside a nested Git repository (`not_staged`). The other named paths were committed (and, on a classic checkout, pushed); `detail` lists each skipped path, the commit and the pushed head. 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_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](#source-roots); 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. |
@@ -192,7 +192,7 @@ Follow the error's `fix.next` as the
| <a id="publish_scan_unreadable"></a>`publish_scan_unreadable` | 1 | Only with `--scan-secrets`: 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 300 s budget), so it reported no secret and nothing was pushed. Run `git fsck` in the checkout, fix what it names, then retry. Never publish with a command that skips the scan. |
| `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](#conflicts). |
| `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`: it replaces the stored page with the file's content. |
+| `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`). |
`--pull` reports `up_to_date`, `advanced`, `ahead` (local commits not yet