Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: sync-receipt-wait key-files entry; #7885 refusal in the conversion design

garrytan4c7b31bc4d89
diff --git a/docs/architecture/key-files/core-persistence-request-indexes.md b/docs/architecture/key-files/core-persistence-request-indexes.md
index 697e455eda..64a233b047 100644
--- a/docs/architecture/key-files/core-persistence-request-indexes.md
+++ b/docs/architecture/key-files/core-persistence-request-indexes.md
@@ -16,3 +16,4 @@ The online-built request-table indexes (the managed sync checkpoint pair, the pa
- `src/core/persistence/pending-import.ts` `landedCommit` with `recoverPublication` (`coordinator.ts`) and `completeWrite` (`journal.ts`) — G7b: on a strict source, a request whose door commit landed before its row is requeued with `outcome.persistence = {git_state: committed, git_commit, landed_before_row: true}` (the newest commit in the record's `door.head..HEAD` that touched its path; none in that range stamps nothing). `completeWrite` keeps it on a receipt that ends without committing (a grant revoked before the replay, a charged interruption), so the caller sees the bytes are in Git and will be indexed; a committed replay writes the ordinary door receipt. Tests: `test/git-door-remote-g7b.test.ts` (both engines; remote OAuth and legacy-token callers, owner down, revoked grant, group commit).
- `src/core/persistence/hosted-repo.ts` with `src/commands/sources-host-repo.ts` — G7b-2, `gbrain sources host-repo <id> --dir <path> [--push-remote <url>] [--dry-run | --expect <plan_hash>]`: a hosted brain gives an empty, unbound source a bare repository (`<dir>/repo.git`, branch `main`, one commit holding an empty `.gitignore`, repository-local identity `gbrain`) and checks it out as a linked worktree (`<dir>/worktree`) claimed through `runManagedSourceLifecycle` (`add` or `claim`, every physical-root and manifest check), with `config.canonical = "git"` and `config.hosted_repo` set in the claim's own transaction. The door then commits there unchanged. A pre-receive hook (`core.hooksPath` pinned to the repository's `hooks/`) refuses every push, since Git's checked-out-branch refusal ends once the worktree is pruned. The preview (the default without `--expect`) prints the plan in words and a `plan_hash` over the source incarnation, canonical setting, directory state, push remote and hook; the apply refuses `preview_changed` when it moved. Refuses `strict_requires_managed` on an unmanaged brain, `hosted_repo_refused` (`source_bound`, `source_has_path`, `source_has_pages`, `source_archived`, `dir_not_empty`) and `overlapping_path` (a directory in a checkout or a source's directory). On a hosted source the preview reports the hook (`ok`/`missing`/`changed`) and the worktree link, and the apply reinstalls the hook. Trusted local CLI only; no operation. Tests: `test/hosted-repo-g7b2.test.ts` (both engines).
- `src/core/persistence/worktree-link.ts` `linkedWorktreeProblem` / `assertLinkedWorktreeIntact` — a claim (`localRoot` in `source-lifecycle.ts`) refuses `git_worktree_link_broken` for a linked worktree whose `.git` file names a repository entry that is gone (pruned) or whose entry names another path (the checkout moved); a submodule's `.git` file is checked for existence only. Tests: `test/hosted-repo-g7b2.test.ts`.
+- `src/core/persistence/sync-receipt-wait.ts` — how long a managed sync pass waits on its own admitted write, in one place: `syncReceiptWait()` returns `pass` (5 s), `checkpoint` (8 s), `held` (30 s, while this process's consumer still holds the write) and `drain` (30 s, a drain's re-entry). `sync-run.ts` reads every wait from it. `__setSyncReceiptWaitForTests(partial | null)` is the test seam (returns a restore function), so a test outlasts a wait in milliseconds instead of sleeping past 30 s.
diff --git a/docs/designs/GIT_CANONICAL_MEMORY.md b/docs/designs/GIT_CANONICAL_MEMORY.md
index 4a9e224450..8c384abaf2 100644
--- a/docs/designs/GIT_CANONICAL_MEMORY.md
+++ b/docs/designs/GIT_CANONICAL_MEMORY.md
@@ -90,7 +90,7 @@ G8a ships it as `gbrain sources canonical <source-id> --to git|mixed [--dry-run
| parked effects | Retried once, or, for targets Git ignores, the page is stamped `git_ignored` (declared) in the same transaction that marks each parked target `declared: git_ignored`; the target stays as a record and the next preview no longer lists it. |
| discard | Refused: `git_conversion_blocked` names each category (both sides moved, a both-sides drift hold, an unknown-side drift hold whose row differs from the committed file, a database edit Git deleted, an uncommitted working-tree edit that differs from HEAD and the export, an ignored target, a target whose ignore status Git cannot read (`ignore_status_unknown`: beyond a symlink, outside the checkout, a failed check; only that path is refused), unparseable, unsafe path, segmented page, export mismatch, or a row a strict pass would overwrite unplanned). There is no override. |
-`--apply --expect <hash>` re-plans and refuses `preview_changed` on any difference, adopts group by group (a crash leaves the source mixed and the rerun preview lists only what is left), withholds group by group, settles the parked effects, rechecks what a strict pass would overwrite, clears the holds only after that recheck passes, runs the full strict-equivalent pass, then sets `canonical: git` in the transaction that records the conversion. Writes can land between that pass and the flag, so it runs one genuine strict pass and previews again. A live writer's door commits (`gbrain git commit-push`) that land after that pass read its level leave Git ahead of the database at their paths and nothing else; the source is git-canonical by then, so the apply runs up to three closing strict passes (phase `strict_pass_closing`, incremental), previewing again after each, and reports `closing_passes`. The conversion is complete only when nothing is left; otherwise it reports `git_conversion_incomplete` with what remains and the source stays strict, because Git wins. Where durability applies the apply pushes its door commits itself, after the groups and once at the end; a push that does not land leaves them local, the receipt says so, and the next page write's push-only effect sends them. The apply prints a progress line per phase and every 10 seconds on stderr, and SIGTERM, SIGINT or SIGHUP prints a partial report (phase, groups committed, items scanned, canonical state); `GBRAIN_MEMORY_TRACE=<seconds>` (1 to 3600) adds a memory line on stderr every that many seconds, and `gbrain sync` honors it too. `--to mixed` removes the flag and changes nothing else; Git keeps every door commit. Both strict passes read the whole level (a full round) without opening a `--full` re-import episode, so a page already equal to its blob is not re-imported, and a re-import that changes nothing queues no embedding effect when every chunk already holds a vector for its text (#7866). Each pass drains under the source's drain lease as `gbrain sync` does, so a write of its own that outlives one receipt wait does not stop it; an unrelated write that never settles, or another drainer, still stops it with `git_conversion_incomplete` before the flag. Every `git_conversion_incomplete` carries `fix` (preview again; verify with `gbrain sync status --source <id> --json`), and with `--json` the refusal carries `progress`. In a strict pass, progress `total` is the planned paths for the whole pass; `round`, `candidates`, `batch` of `batches` and `scanned` say where the round stands.
+`--apply --expect <hash>` re-plans and refuses `preview_changed` on any difference, adopts group by group (a crash leaves the source mixed and the rerun preview lists only what is left), withholds group by group, settles the parked effects, rechecks what a strict pass would overwrite, clears the holds only after that recheck passes, runs the full strict-equivalent pass, then sets `canonical: git` in the transaction that records the conversion. Writes can land between that pass and the flag, so it runs one genuine strict pass and previews again. A live writer's door commits (`gbrain git commit-push`) that land after that pass read its level leave Git ahead of the database at their paths and nothing else; the source is git-canonical by then, so the apply runs up to three closing strict passes (phase `strict_pass_closing`, incremental), previewing again after each, and reports `closing_passes`. The conversion is complete only when nothing is left; otherwise it reports `git_conversion_incomplete` with what remains and the source stays strict, because Git wins. Where durability applies the apply pushes its door commits itself, after the groups and once at the end; a push that does not land leaves them local, the receipt says so, and the next page write's push-only effect sends them. The apply prints a progress line per phase and every 10 seconds on stderr, and SIGTERM, SIGINT or SIGHUP prints a partial report (phase, groups committed, items scanned, canonical state); `GBRAIN_MEMORY_TRACE=<seconds>` (1 to 3600) adds a memory line on stderr every that many seconds, and `gbrain sync` honors it too. `--to mixed` removes the flag and changes nothing else; Git keeps every door commit. Both strict passes read the whole level (a full round) without opening a `--full` re-import episode, so a page already equal to its blob is not re-imported, and a re-import that changes nothing queues no embedding effect when every chunk already holds a vector for its text (#7866). Each pass drains under the source's drain lease as `gbrain sync` does, so a write of its own that outlives one receipt wait does not stop it; an unrelated write that never settles, or another drainer, still stops it with `git_conversion_incomplete` before the flag. Every `git_conversion_incomplete` carries `fix` (preview again; verify with `gbrain sync status --source <id> --json`), and with `--json` the refusal carries `progress`. In a strict pass, progress `total` is the planned paths for the whole pass; `round`, `candidates`, `batch` of `batches` and `scanned` say where the round stands. On a source whose managed root is not inside a Git checkout, or is a checkout with no commit yet, the preview and the apply refuse with `git_checkout_required` or `git_branch_unborn` before they read or write anything (#7885); the source stays usable as it is, and the fix asks the user before the folder becomes a Git repository (then `gbrain sources canonical <id> --to git --dry-run --json` previews again).
## The git-gap census