Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs(designs): refresh write barrier, commit ledger and foreign-writer alarm (PR B design note)

garrytanc8f0c8366040
diff --git a/docs/designs/REFRESH_WRITE_BARRIER.md b/docs/designs/REFRESH_WRITE_BARRIER.md
new file mode 100644
index 0000000000..ab55030b52
--- /dev/null
+++ b/docs/designs/REFRESH_WRITE_BARRIER.md
@@ -0,0 +1,470 @@
+# Refresh write barrier, commit ledger and foreign-writer alarm (PR B)
+
+Status: reviewed (one eng-review round, two voices, fixes applied; see the review record at the end).
+Lane L4 of the convergence program.
+Placeholders only: "source D", "the main source", "a busy agent". Counts are synthetic.
+
+## Why
+
+Two problems keep a shared brain checkout from converging:
+
+1. **Writes that meet a refresh are refused.** `gbrain sources refresh` fast-forwards a managed
+ worktree. While its row is active, every page write to that worktree is refused
+ `worktree_refreshing` before it is journaled (journal.ts `assertWorktreeNotRefreshing`). A tick
+ runs minutes, so a producer that does not read the JSON code loses the write. Production saw
+ several such refusals reported as exit 0 by the harness that launched them.
+2. **Nobody can see who else commits.** Crons and scripts commit to brain checkouts with plain git.
+ Their commits bypass the writer lock and leave files with no import record, which later become
+ drift holds. doctor's writer checks skip managed worktrees ("their owner is the only writer"),
+ which is the assumption that failed.
+
+PR B turns (1) into a deferred write that commits after the refresh, and makes (2) visible with an
+append-only ledger of every commit gbrain makes plus a doctor check that names every other commit.
+It also lets the owner install the commit guard on a managed worktree, adds a per-path base check
+to `gbrain git commit-push`, and folds four small bugs (#8615, #8616, #8617, #8662).
+
+Out of scope: who routes the box's writers (lane L2), when the flag is turned on (an operations
+decision with stated preconditions, below), and the soak cell (lane L5).
+
+## Part 1: the refresh write barrier
+
+### Today
+
+- `fenceDraining` inserts the refresh row `draining` while holding the worktree row FOR UPDATE.
+- Admission (`assertWorktreeAdmission`) holds the worktree row FOR SHARE and reads the active
+ refresh in the same pipelined statement pair, so an admission either commits before the fence
+ (and is drained) or sees it and is refused. During `syncing` any
+ `managed_sync_*` job is admitted.
+- Claims skip a worktree whose refresh is `fenced`, `merged` or `recovery_required`
+ (`refreshFenceClear`); `draining` and `syncing` keep claiming so queued work drains.
+- `fenceAndMerge` refuses `refresh_source_changed` when any request, checkout effect or recovery
+ record reached the worktree after the drain check.
+
+### The barrier sequence
+
+When the flag is on and an admission sees an active refresh in `draining`, `fenced`, `merged` or
+`syncing`, a **page write** (target `page`, one of the page write operations) that is not a
+`managed_sync_*` job is **admitted as a deferred request** instead of refused:
+
+1. It is journaled with **state `deferred`** (a new request state) and
+ `deferred_refresh_id = <refresh id>`. Its counters are reserved exactly as for a queued row.
+2. The caller gets a pending receipt at once (no wait on the owner): CLI exit 10
+ (`write_pending`, unchanged registry entry); MCP `isError: false` with
+ `{ status: "pending", request_id, receipt, deferred: { refresh_id, refresh_state }, next }`.
+ `next` is `get_write_request` / `gbrain write-request <id>` after `retry_after_ms`.
+3. A deferred row is **unclaimable until its refresh is released.** A refresh is released when its
+ row reaches `completed` or `aborted` (`released_at` is set in the same statement).
+4. After release, the new claim moves deferred rows **straight from `deferred` to `running`** in
+ sequence order (they never pass through `queued`), and each one gets the refresh-change check
+ (below) before it publishes.
+
+Not deferred, refused as today: `recovery_required` (`refresh_recovery_required`: HEAD is
+unverified and may stay so until a person runs `--resume`), `submit_job` writes, and
+`skill_bundle` targets (protocol 2, whose own activation contract this PR does not touch).
+
+Repo-less brains and unmanaged sources have no worktree, no refresh row and no fence; admission never
+reaches the deferred branch there, and a test pins it.
+
+**Why a state and not a flag on a queued row.** Every selector in the write path names its states
+explicitly: claims (`r.state='queued'`), `EARLIER_HEAD`, `FOREGROUND_WAITING_ON`, the lane-head
+claim's earlier-row check, follower claims, `drainCounts` and the protocol-activation guard. A row
+in `deferred` is invisible to all of them in every binary, old or new. So:
+
+- the refresh's own managed-sync rows are never held behind deferred foreground rows (otherwise the
+ refresh could not complete, every deferred row would wait for it, and it would wait for them);
+- the refresh's drain never counts them, so the set it waits for is closed when the fence row is
+ inserted;
+- an older consumer never selects, waits on or claims them, so it cannot apply one without the
+ refresh-change check, and cannot wedge on one either.
+
+A build-time audit test lists every SQL fragment that filters `persistence_requests.state` and fails
+when a new one appears without a decision about `deferred`.
+
+### Migration (both engines, one migration)
+
+```sql
+ALTER TABLE persistence_worktree_refreshes
+ ADD COLUMN IF NOT EXISTS barrier_sequence bigint, -- requests' sequence high-water when the fence row was inserted (diagnostic)
+ ADD COLUMN IF NOT EXISTS released_at timestamptz; -- set exactly once, on completed/aborted
+ALTER TABLE persistence_requests
+ ADD COLUMN IF NOT EXISTS deferred_refresh_id uuid REFERENCES persistence_worktree_refreshes(id);
+-- the state CHECK gains 'deferred': drop the old constraint, ADD the new one NOT VALID, then VALIDATE
+-- in a separate statement (no long ACCESS EXCLUSIVE scan; #7636's no-table-lock rule)
+CREATE INDEX IF NOT EXISTS persistence_requests_deferred
+ ON persistence_requests(deferred_refresh_id, sequence) WHERE state='deferred';
+ALTER TABLE persistence_consumers ADD COLUMN IF NOT EXISTS capabilities text[] NOT NULL DEFAULT '{}';
+```
+
+plus two triggers:
+
+- **Release trigger** (BEFORE UPDATE on persistence_worktree_refreshes): when `NEW.state` enters
+ `completed` or `aborted` from an active state, `NEW.released_at := now()`. This covers every
+ writer of that column: `transition()`, admission's direct syncing-completion update (journal.ts),
+ orphan adoption, `--resume`/`--abandon`, and an older binary's transitions in a mixed-version
+ window.
+- **Deferred-row guard** (BEFORE UPDATE on persistence_requests, a new function and trigger; the
+ shipped request protocol guard bodies are untouched): a row may leave `deferred` only to
+ `running` (and only when its refresh is released and the session declares
+ `gbrain.refresh_barrier = '1'`, which only a new claim statement sets), or to `failed` /
+ `cancelled` (expiry, cancel). Nothing moves a row into `deferred` except its insert. This is a
+ backstop; no older code path selects the state.
+
+No request protocol version changes. Deferred rows keep `protocol_version = 1`, so replay identity
+(`prior.protocol_version` versus the replay's) and every renewal, finish and charge that declares
+protocol 2 work unchanged.
+
+### Admission and lock order
+
+The global lock order (protocol.ts) gains the refresh row **right after the worktree row**: brain,
+worktrees, the worktree's active refresh row, sources, counters, requests, page keys.
+`bookkeeping` already updates the refresh row before `sources`, and `fenceDraining` inserts it
+while holding the worktree FOR UPDATE, so the refresh side already follows this order.
+
+With the flag on, admission's first pipelined round becomes: the worktree row FOR SHARE, then
+`SELECT id, state FROM persistence_worktree_refreshes WHERE worktree_id=$1 AND state IN
+('draining','fenced','merged','syncing','recovery_required') FOR NO KEY UPDATE`. Then it branches:
+no row (none active, or it already went terminal and so is released) → normal admission;
+`recovery_required` → refuse; `syncing` whose members all reached the target → complete it (the
+existing update, now without a share-to-update upgrade, so two admissions cannot deadlock on it) and
+admit normally; any other active state → deferred admission. Taking the refresh row exclusively costs
+nothing extra: admissions already serialize on the `brain` counter row. With the flag off,
+admission's statements are unchanged.
+
+Every refresh state change updates that row, so an admission and a transition serialize on it:
+either the terminal transition commits first (the admission sees no active row and is normal), or the
+deferred admission commits first (its refresh is not yet released, and the release that follows makes
+it claimable). No row can be deferred to an already released refresh, and no row can slip in as a
+normal admission while a refresh is in `recovery_required`.
+
+The capability check and the capacity checks run in the same transaction after these locks.
+
+### Release, the refresh-change check, and the drain bound
+
+**Release** is the terminal transition (trigger above). The new claim selects
+`state='deferred' AND <its refresh is released>` together with the ordinary queued candidates, in
+sequence order, honouring the usual per-worktree head rules, so FIFO order per worktree holds after
+release.
+
+**The refresh-change check** replaces a database revision base, because `completed` does not mean
+imported: a refresh completes even when a member's sync is blocked or deferred, so git can hold the
+refreshed bytes while the page's revision has not moved. The check uses git, which the refresh knows
+exactly. After preparation, when the publication's target paths are known (a rename's two paths, a
+forget's companion pages, a fence row another page retires, every file of a multi-file publication),
+and before publication, the consumer asks whether refresh R changed any of them:
+`git diff --name-only -z <old_head> <target_head> -- <paths>` on the owner's checkout (the refresh
+row stores both heads). An aborted refresh moved nothing and skips the check.
+
+- No target path changed in R: the write publishes normally. Its own `expected_revision` and the
+ existing file guards still apply, so two deferred writes to one page, or a pre-fence write and a
+ deferred write, behave exactly as two ordinary queued writes do (no false conflict).
+- Any target path changed in R: the row finishes with receipt state `conflict`, code
+ `revision_conflict`, detail naming the refresh and the changed paths. Nothing is applied, so a page
+ the refresh changed is never overwritten. This applies to every page operation, appends included;
+ the producer re-reads and recomputes (lane L2's revision-bound read-modify-write). The diff is
+ computed once per refresh and cached for the drain.
+
+**Livelock bound.** A refresh only waits for rows admitted before its fence; writes admitted during
+it are deferred to it, so a steady stream cannot keep a drain from reaching zero. A previous refresh's
+released rows are claimed normally during the next refresh's `draining` and counted by its drain
+(the claim moves them to `running`), within the existing `--wait-drain` budget.
+
+**Capacity.** Deferred rows reserve the existing outstanding and intent-byte counters. A per-worktree
+cap `persistence.refresh_barrier_max_deferred` (default 1000) bounds one refresh; past it, admission
+refuses `worktree_refreshing` as today (retryable, `fix.next: wait`).
+
+**Age bound.** A deferred row whose refresh is still unreleased after
+`persistence.refresh_barrier_max_wait_ms` (default 15 minutes; a tick runs a few minutes) is finished
+`failed` with `refresh_barrier_expired` by the owner consumer's housekeeping turn, in one statement
+that rechecks `released_at IS NULL` and releases its counters. Nothing is applied; the producer
+resubmits with a new request id. If the owner host is down, nothing claims or expires rows; receipts
+stay pending and readable, as for any queued row on that host.
+
+### Idempotency
+
+The request id is the idempotency key. A replay of a deferred request id finds the prior row (same
+target, same protocol 1) and returns its receipt: pending while `deferred`, then whatever it
+became. A request id first refused `worktree_refreshing` (nothing recorded) is admitted on retry,
+deferred or not. A replay whose intent digest differs is `idempotency_conflict`, unchanged.
+Tests cover replay during the refresh, after release, after the flag is turned off, and two
+concurrent admissions of one request id.
+
+### Authorization re-check at commit
+
+A deferred row can wait minutes. At claim, a deferred row re-runs
+`authorizeWrite(authority, operation, slug)` against current grants (scope, member binding,
+readable_by of the target). A revoked or narrowed credential finishes the row `permission_denied`
+(terminal, nothing applied). The source binding and incarnation are rechecked by the existing claim
+path (`source_changed`).
+
+### Crash recovery
+
+Deferred rows are durable rows; nothing about them lives in process memory.
+
+- Admitting process dies after commit: the receipt exists; the caller replays the request id.
+- Refresh process dies: its row stays active; orphan adoption or `sources refresh --resume`
+ completes or aborts it, and the trigger releases it. `--abandon` aborts, which also releases.
+- Consumer dies after claiming: the row is `running` with a lease; ordinary expiry and reclaim.
+- Release and the deferred-to-running claim are single statements.
+
+### Mixed-version contract
+
+- **What an older consumer cannot claim:** rows in state `deferred`. No older selector names the
+ state, and the deferred-row guard refuses the transition without the new session declaration.
+- **What an older admitter does:** it never defers (it refuses `worktree_refreshing` as today),
+ which is safe.
+- **When a new admitter defers:** only when the flag is on and every live consumer of the worktree's
+ owner host (`persistence_consumers`, renewed within `CONSUMER_LIVE_MS`) advertises
+ `refresh_barrier_1` in `capabilities`; otherwise it refuses as today. A consumer started later by
+ an older binary still cannot claim a deferred row; what it could do is claim a queued row of the
+ same worktree ahead of a released deferred one, which is why the upgrade order below requires
+ quiescence of older binaries before the flag goes on, and doctor reports a live consumer without
+ the capability on a brain with the flag on.
+- **Upgrade order:** apply the migration (harmless with the flag off) → upgrade every binary on the
+ owner host → restart resident consumers so their heartbeats carry the capability (quiescence) →
+ watch a clean deploy → turn the flag on per brain.
+- **Turning the flag on** (`gbrain config set persistence.refresh_barrier true`, env
+ `GBRAIN_REFRESH_BARRIER`, a `WRITE_SWITCHES` entry with `defaultOn: false`) is gated
+ operationally on a clean deploy watch and on every routed producer of that brain having its three
+ proofs (pending to committed, pending to conflict, restart), reported by the box lane. Turning it
+ off stops new deferrals; existing deferred rows still drain.
+- **Downgrade order:** turn the flag off → wait until no row is `deferred` → downgrade.
+ `gbrain upgrade --check-downgrade` (read-only, new) exits 0 when no deferred row remains and exits
+ 3 with `downgrade_blocked_deferred_writes` (count, oldest age) otherwise; the box's automatic
+ binary restore calls it and refuses to restore an older binary on exit 3. Safety does not rest on
+ that gate (an older binary cannot claim the rows); liveness does: after a downgrade they would wait
+ for the next upgrade.
+
+### Surfaces
+
+- CLI write verbs: deferred → exit 10 with the receipt (`state: deferred`, `deferred`), `--json`
+ carries `outcome: pending`. `gbrain write-request <id>` shows the deferral until it drains.
+- MCP: deferred → `isError: false`, `status: "pending"`; `requestLogStatusForResult` classifies a
+ pending non-error result as `accepted_pending` (today it only reads pending from error results).
+ Other `write_pending` results (an acknowledgement lost to the owner) are unchanged.
+- With the flag off nothing changes, and two refusals are pinned non-zero on both surfaces by tests:
+ `worktree_refreshing` and the held-file refusal (`source_changed` with the held-file diagnostic,
+ verb-errors.ts). CLI exit is non-zero; MCP is `isError: true`.
+- `gbrain sources writer status --json` gains `deferred: { count, oldest_age_ms, refresh_id }`, and
+ receipts render state `deferred` as pending.
+
+## Part 2: per-path base check on commit-push
+
+`gbrain git commit-push --base <path>=<blob> [--base ...] -m <msg> -- <paths>`: after taking the
+commit lock and before staging, each named path's blob at HEAD (`git rev-parse --verify -q
+HEAD:<path>`) must equal `<blob>` (full object id), or be absent when `<blob>` is `absent`. Any
+mismatch refuses `commit_base_moved` naming the path, the base and HEAD's blob; nothing is staged
+or committed and the index is unchanged. The fix tells the writer to re-read the file at HEAD,
+recompute and retry with the new base. A `--base` path must also be one of the committed paths.
+This is the commit-push half of soak mode (m).
+
+## Part 3: commit ledger
+
+### Where and what
+
+One file per repository: `<git common dir>/gbrain/commit-ledger.jsonl` (inside `.git`, so never
+tracked, shared by every worktree of the repository, readable without a database). Appended with
+`O_APPEND`, one JSON line under 1 KiB per record, so concurrent appends never interleave.
+
+```json
+{"v":1,"e":"commit","t":"<iso>","sha":"<full>","writer":"door","request_id":"<uuid|null>",
+ "worktree":"<abs root>","worktree_id":"<uuid|null>","ref":"refs/heads/main","pid":123,"host":"<host id|null>"}
+```
+
+Writer kinds: `commit_push` (commitPaths), `door` (commitThroughDoor), `merge` (in-memory merge
+commit), `replay` (integrate's commit-tree replay), `effect` (effect worker), `sync_init`
+(sync-git auto-init), `workspace_push`, `bootstrap`, `hosted_repo`.
+
+### Sites
+
+One helper, `src/core/git/commit-ledger.ts` (`recordCommit(root, entry)` sync and async). Plumbing sites
+ledger the sha right after `commit-tree` returns and before the ref moves, so a commit can never be
+reachable without its line. Porcelain sites (`git commit`) write an intent line first and the commit
+line after:
+
+| Site | How the sha is known |
+|---|---|
+| commit-push.ts commitPaths (`git commit --only`) | `rev-parse HEAD` under the commit lock |
+| commit-push.ts integrate replay (`commit-tree`, ~711) | commit-tree output |
+| commit-push.ts buildMerge (`commit-tree`, ~817) | commit-tree output |
+| git-door.ts commitThroughDoor (`commit-tree` + `update-ref`) | commit-tree output, ledgered before update-ref |
+| effect-git.ts commitGitTargets (~372) | `rev-parse HEAD` in the same session; request ids of the group |
+| sync-git.ts auto-init commit (~611) | `rev-parse HEAD` |
+| workspace-push.ts (~1077) | `rev-parse HEAD` |
+| bootstrap/repo.ts (~481) | `rev-parse HEAD` |
+| persistence/hosted-repo.ts (~199) | commit-tree output |
+
+A shared git runner was considered and rejected: the sites use four different runners (commit-push's
+sync `git`, effect-git's session, git-door's session, bootstrap's injected runner), and two of the
+commits are plumbing whose ref move happens later, so the line belongs where the sha is known.
+
+### Boundaries, retention, crash reconciliation
+
+- **One ledger lock.** Ledger files live in the common dir, while commit locks are per checkout and
+ the door and effect worker hold the native writer lock instead. So the ledger has its own flock,
+ `<git common dir>/gbrain/commit-ledger.lock`, taken for the start line, every append and rotation.
+ It is held for microseconds and never while git runs.
+- **Start boundary.** The first append writes `{"e":"start","t":...}`. Reflog entries older than the
+ ledger's start are reported as uncovered, never as foreign.
+- **Retention.** At 4 MiB the file rotates to `commit-ledger.1.jsonl` (one previous file kept), under
+ the ledger lock. doctor reads both. The covered window is
+ `max(ledger start or oldest retained line, oldest reflog entry)` to now, and doctor prints it.
+- **Crash reconciliation (porcelain sites only).** The intent line records `head_before`, the commit
+ message's sha256 and the writer. A crash between `git commit` and the commit line leaves an open
+ intent. doctor lists an unledgered commit as `gbrain_unconfirmed` only when its parent is the
+ intent's `head_before`, its message digest matches and it was created within 60 s of the intent;
+ that is a `warn`, never a `fail`, and it is **never written back into the ledger** automatically,
+ so an ambiguous outcome cannot certify a foreign commit. A failed ledger append never fails the
+ commit (logged once); doctor then reports that commit as foreign, the safe direction for an alarm.
+
+## Part 4: doctor `foreign_writers`
+
+Scope: every registered source checkout on this host, **managed worktrees included**, deduplicated by
+git common dir. A brain with no checkout (repo-less) reports `not_applicable`.
+
+**Locally created commits.** It reads the reflogs that record local ref moves: `logs/HEAD` and
+`logs/refs/heads/*` in the common dir and `worktrees/*/logs/HEAD` (per-worktree HEAD logs), parsing
+commit metadata with `git log --no-walk --format='%H %P %ct'` (not `cat-file --batch-check`, whose
+format has no parent atom).
+
+- **Porcelain creations**, whose new sha was created locally by definition: `commit:`,
+ `commit (amend):`, `commit (initial):`, `cherry-pick:`, `revert:`, `rebase (pick|reword|edit|squash|fixup)`,
+ `pull --rebase (pick)` and `am:`. Each new sha is looked up in the ledger.
+- **Other ref moves** (a custom or empty message, i.e. `update-ref` after `commit-tree`): every
+ commit in `old..new` (the whole history of `new` for a root move) whose committer time falls
+ within 10 minutes of the entry is a candidate; older commits were fetched, not made here.
+ Candidates not in the ledger are flagged `plumbing`; a move whose range cannot be read is
+ reported `unknown` (warn), never silently dropped.
+- **Excluded:** `commit (merge)` and any multi-parent commit, `merge ...` (fast-forwards and
+ merges), `pull:` fast-forwards and merges, `reset:`, `checkout:`, `branch:`, `clone:`, and
+ push/fetch tracking-ref updates.
+
+Each flagged sha is classified `plain`, `amend`, `rewrite` (cherry-pick, revert, rebase, am) or
+`plumbing`; a plain commit made while the enforce guard is installed is labelled
+`plain (guard bypassed)`. Reads are bounded: the newest 5,000 entries per log, every git call
+time-bounded, and the check stops at doctor's budget and labels its result partial.
+
+**Dirty page files.** `git status --porcelain=v2 -z --untracked-files=all` scoped to the checkout's
+source roots lists untracked and unstaged page files. Paths with a pending git effect
+(`persistence_effects`, kind `git`, state `queued` or `running`, whose targets name the path) and
+paths in the write-through pending ledger are left out: gbrain is about to commit them. Each listed
+file carries its age since first seen, read as its mtime (no new state file; a file touched again
+reads younger, which errs toward under-alarming, never toward a false alarm). At most 20 are listed
+with the total count.
+
+**Verdict.** Any foreign commit in the window: status `fail` with `act`, and a one-line fix naming
+the newest foreign commit (`Commit <sha12> (<kind>, "<subject>", <time>) in <checkout> was not made
+by gbrain; route that writer through gbrain git commit-push or a page write`). Dirty files older than
+30 minutes with no foreign commit: `warn`. The JSON carries the window, every foreign commit (sha,
+kind, ref, time, subject, committer identity as recorded), the unconfirmed ones and the dirty list.
+The check is read-only.
+
+## Part 5: owner-path guard install
+
+`gbrain git guard --install` refuses a managed worktree today (`assertManagedFilesystemWrite`). New:
+`gbrain sources guard <source> --install|--uninstall|--status [--mode enforce]`, CLI-only and
+trusted-local. It installs the `prepare-commit-msg` guard on the source's managed worktree only from
+its owner host, under the worktree's native writer lock (the owner check `sources refresh` uses).
+
+- **Worktree-local only.** The existing installer resolves the repository's shared hooks directory
+ (and honours a global `core.hooksPath`), so installing there would also guard a person's own
+ linked checkout. The owner path installs into a hooks directory private to that worktree
+ (`<worktree git dir>/gbrain-hooks`) and points that worktree's `core.hooksPath` at it with
+ `git config --worktree` (enabling `extensions.worktreeConfig` only when the repository has linked
+ worktrees). It refuses, changing nothing, when another tool's hook already lives at the effective
+ path, and `--status` reports the effective hooks path.
+- **Enforce mode** refuses plain commits, `--amend`, `--no-verify` commits, and, unlike the opt-in
+ guard, also cherry-pick, revert, rebase and sequencer commits: in a managed worktree only the owner
+ commits.
+- **Owner commits pass** without changes: the effect worker commits with an empty hooks directory,
+ the door and the in-memory merge and replay are plumbing (no commit hooks), sync's auto-init runs
+ with `core.hooksPath=/dev/null`, `commit-push` sets `GBRAIN_COMMIT_VIA` under the commit lock, and
+ a refresh fast-forward (`merge --ff-only`) runs no commit hook. workspace-push and bootstrap commit
+ plainly with hooks on, so the build confirms neither runs in a managed worktree; if either can, it
+ takes the commit lock and sets `GBRAIN_COMMIT_VIA` like commit-push.
+- A writer that disables hooks itself is not stopped by any hook; the ledger names it. No audit hook
+ is added.
+
+## Part 6: bug folds
+
+- **#8615** (repair file-drift `--held`/`--side` without `--prefer` silently surveyed a different
+ set): any `--held`, `--side`, `--state`, `--cursor` or `--provenance` call goes through option
+ validation. Rewritten on master from contributor PR #8626 with credit and a `Supersedes #8626`
+ line; the outside branch is read as text only. The file belongs to PR A's planned set, so the hunk
+ is agreed with that lane first.
+- **#8616** (an impossible calendar date such as 2026-09-31 aborted a whole preview window with
+ `internal_error` from a `::date` cast): the timeline parser rejects dates that are not real
+ calendar dates, so sync and repair agree, and the projection guards its cast so a residual bad
+ row refuses its own page (`invalid_timeline_date`, naming the line) while the window continues.
+- **#8617** (`refresh_source_changed` lost a whole tick): exactly one same-tick retry when the cause
+ is HEAD moving or work arriving after the drain check, after waiting (bounded by the commit-lock
+ wait) for the committing writer to finish. Ownership or membership changes are not retried. A
+ second refusal is returned as today.
+- **#8662** (commit-push resolved a wrapper's cwd to another repository): when a brain is configured
+ and has registered source checkouts on this host, a resolved root that is none of them and carries
+ no `gbrain.sourceRoot` marker is refused `checkout_not_a_source`, naming the resolved path and
+ the registered checkouts, with `--path <brain checkout>` as the fix. With no brain configured,
+ commit-push stays DB-free and behaves as today.
+
+## Tests (red first; PGLite and Postgres where a database is involved)
+
+- **Ledger and foreign_writers fixture**, one repository with seven commit kinds: door, commit-push,
+ in-memory merge, plain `git commit`, `--amend`, plumbing `commit-tree` + `update-ref`, and a
+ bypass (`git -c core.hooksPath=/dev/null commit` under the enforce guard; plain `--no-verify` is
+ refused by the guard and asserted so). Must-not-flag: effect-worker, replay, bootstrap and
+ sync auto-init commits, an upstream fast-forward and an in-memory merge. Only plain, amend/bypass
+ and plumbing are flagged. Plus: the start boundary, rotation, an open intent reconciled as
+ unconfirmed, per-worktree HEAD logs.
+- **Dirty files:** untracked and unstaged page files listed by age; a path with a pending git effect
+ and a write-through pending path are left out; repo-less `not_applicable`.
+- **Owner guard:** non-owner host refused; enforce refuses a plain commit; effect, door and
+ commit-push commits and a refresh fast-forward pass.
+- **Barrier:** pending to committed across a real refresh, with lanes on and off (the managed sync
+ is never held behind deferred rows); a refresh that completes with a blocked member sync (the git
+ check still conflicts a changed page); the livelock bound (a write stream during
+ draining does not stop the drain); `revision_conflict` when the refresh changed the page;
+ kill-and-resume of the refresh process with deferred rows; idempotent retry of a deferred request
+ id; an older consumer never selects a deferred row and keeps serving another worktree's queued work, and
+ its forced transition is refused by the guard; admission against `recovery_required` refuses and
+ admission racing each terminal transition is either normal or deferred, never stranded;
+ multi-target operations (rename, forget companions);
+ capacity and age bounds; flag off unchanged; repo-less never defers; MCP `isError: false` pending;
+ the two refusals non-zero on both surfaces; `--check-downgrade` exit 3 while rows remain.
+- **Base check:** a moved blob refuses `commit_base_moved` and leaves the index untouched; `absent`.
+- **Bug folds:** one red-first test each.
+
+## Docs and skills
+
+docs/guides/shared-checkout-git.md (ledger, foreign_writers, owner-path guard, `--base`),
+docs/guides/sync-unblock-runbook.md (deferred writes in status, `refresh_barrier_expired`),
+docs/guides/write-refusals.md (`commit_base_moved`, `checkout_not_a_source`,
+`refresh_barrier_expired`, the deferred pending receipt), the error registry entries, and any skill
+that names the guard or `worktree_refreshing`. Behaviour-change rows for each user-visible change.
+
+## Review record
+
+One eng-review round (gstack /plan-eng-review method), two voices: Opus 5.5 and GPT-6.1 Sol. Both
+verdicts: approve with the listed fixes. Every finding was applied above:
+
+- The barrier is a request **state** (`deferred`), not protocol 3. This fixes the refresh's own sync
+ being held behind deferred rows (`FOREGROUND_WAITING_ON`, lane-head and follower checks), an older
+ consumer wedging on one row across all worktrees, protocol-2 renewals and finishes failing on
+ protocol-3 rows, replay identity conflicts, and the table-locking CHECK widening on
+ `protocol_version`.
+- Admission locks the refresh row by worktree, with `recovery_required` in the filter, FOR NO KEY
+ UPDATE right after the worktree row (new rank in the lock order). This fixes a deadlock with
+ `bookkeeping`, a lock-upgrade deadlock in the syncing-completion update, and a normal admission
+ slipping in during `recovery_required`.
+- The base check is "did refresh R change any of this publication's target paths" from git, after
+ preparation. This fixes false conflicts between two deferred writes, a `completed` refresh whose
+ member sync was blocked, and multi-target operations. `submit_job` and `skill_bundle` keep
+ today's refusal.
+- The ledger has its own lock; plumbing sites ledger before the ref moves; reconciliation never
+ writes back and needs a message-digest match; rewrite kinds and empty-message ref moves are
+ detected; plumbing detection works on ranges; metadata comes from `git log`, not `cat-file`.
+- The guard installs worktree-locally, enforce mode drops the rewrite exemptions, and the bypass
+ fixture uses a hooks-path override.
+- MCP request-log classification reads pending from non-error results; expiry rechecks
+ `released_at` and releases counters.
+
+Defaults kept: mtime as the dirty file's first-seen age (no new state file written by doctor), 1000
+deferred rows per refresh, and 15 minutes maximum wait.