Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: canonical-writers row and Q1 comment follow the child publish

garrytan51f42038e0f4
diff --git a/docs/architecture/canonical-writers.tsv b/docs/architecture/canonical-writers.tsv
index e3c2af5def..45308088eb 100644
--- a/docs/architecture/canonical-writers.tsv
+++ b/docs/architecture/canonical-writers.tsv
@@ -253,7 +253,7 @@ src/core/repair/frontmatter.ts 2 coordinator `gbrain repair frontmatter --apply`
src/commands/sources-mirror.ts 1 engine_guard `gbrain sources mirror-readonly|mirror-writable` (#5409) updates only sources.config.mirror_read_only, exactly as `sources federate` updates sources.config.federated; the sources managed_writer_guard trigger governs the row and no page, fact or file is written.
src/core/sync-upstream.ts 1 engine_guard `recordUpstreamObservation` (#5255/#5176) updates only sources.upstream_checked_at, upstream_commit and upstream_behind, observations of the checkout's Git upstream outside managed_writer_guard's protected topology and checkpoint tuples; no page, fact or file is written, and a failure never fails the sync.
src/core/persistence/mirror-read-only.ts 1 coordinator classifyMirrorPage stamps pages.database_only_reason=mirror_read_only only inside the coordinator publication transaction of a page write that published no file into a read-only mirror source (#5409), as classifyUnboundPage does for unbound sources.
-src/core/persistence/worktree-refresh.ts 1 coordinator `gbrain sources refresh` (F0) is the one sanctioned managed Git writer: it fast-forwards the checkout only under the worktree native lock after admission refused and claims stopped every checkout write (`fenced`), then updates only sources.upstream_checked_at/upstream_commit/upstream_behind in the merged bookkeeping transaction; pages and the checkpoint advance through the ordinary managed --no-pull sync. #7686: with sources.refresh_publish_diverged on (standing consent, default off) it first runs the keep-checkout publish (commitAndPush pushOnly+keepCheckout), which pushes HEAD merged with the upstream in memory and never moves the checkout or the database.
+src/core/persistence/worktree-refresh.ts 1 coordinator `gbrain sources refresh` (F0) is the one sanctioned managed Git writer: it fast-forwards the checkout only under the worktree native lock after admission refused and claims stopped every checkout write (`fenced`), then updates only sources.upstream_checked_at/upstream_commit/upstream_behind in the merged bookkeeping transaction; pages and the checkpoint advance through the ordinary managed --no-pull sync. #7686: with sources.refresh_publish_diverged on (standing consent, default off) it first runs the keep-checkout publish (a bounded child gbrain git commit-push --push-only --keep-checkout, never on the owner's event loop), which pushes HEAD merged with the upstream in memory and never moves the checkout or the database.
src/core/facts/unfenced-facts.ts 3 coordinator The extract_facts cycle phase and the v0.32.2 migration fence row_num-NULL facts onto their entity pages. On a managed brain the fence publishes through a coordinated maintenance request; an unmanaged brain writes the page file under the source filesystem and page locks, then mirrors the body and stamps row numbers in one maintenanceTransaction.
src/core/repair/take-supersession.ts 1 coordinator gbrain repair take-supersession reprojects superseded_by for a page whose fence is already right: inside withCoordinatedWrite under the page key on a managed brain (revision-checked), maintenanceTransaction on an unmanaged one. Fence edits go through a revision-bound put_page request.
src/core/repair/timeline-comments.ts 2 coordinator `gbrain repair timeline-comments` (#6184) deletes or rewrites timeline rows carrying HTML comment markup under the page lock: `withCoordinatedWrite` with maintenance attribution on managed brains, `maintenanceTransaction` otherwise; the page body changes go through a revision-bound put_page first.
diff --git a/src/core/persistence/worktree-refresh.ts b/src/core/persistence/worktree-refresh.ts
index 4ccd9a234e..de4c0da6b8 100644
--- a/src/core/persistence/worktree-refresh.ts
+++ b/src/core/persistence/worktree-refresh.ts
@@ -297,11 +297,6 @@ async function precheck(engine: BrainEngine, git: Git, sourceId: string, fetchTi
if (dirt.overlap.length) throw dirtyRefusal(sourceId, dirt.overlap);
return { binding, root, members, upstreamRef, oldHead, targetHead, ...dirt };
}
-/**
- * Q1: a diverged checkout is reconciled without moving it: `gbrain git commit-push --push-only --keep-checkout` merges the
- * upstream into HEAD in memory and pushes the merge (refusing on a conflict, never touching the checkout), after which HEAD
- * is an ancestor of the upstream and the refresh fast-forwards. It publishes the local commits, so the user decides.
- */
/** #7686: the bound on the keep-checkout publish child (a fetch, an in-memory merge and a push, repeated while the remote keeps moving). */
const PUBLISH_TIMEOUT_MS = 600_000;
@@ -329,6 +324,11 @@ async function publishInChild(root: string, sourceId: string): Promise<{ sha: st
throw opError('push_unconfirmed', `The publish of the diverged checkout ${root} did not report a push (${child.error ? `exit ${String(child.error.code ?? child.error.signal ?? 'unknown')}` : `outcome ${String(doc?.outcome ?? 'unreadable')}`}: ${child.stderr.trim().slice(0, 300) || 'no detail'}); the refresh stopped before fencing anything, and the remote may already hold the merge.`,
`Check gbrain sources writer status --source ${sourceId} --json, then retry gbrain sources refresh ${sourceId}.`, { retryable: true });
}
+/**
+ * Q1: a diverged checkout is reconciled without moving it: `gbrain git commit-push --push-only --keep-checkout` merges the
+ * upstream into HEAD in memory and pushes the merge (refusing on a conflict, never touching the checkout), after which HEAD
+ * is an ancestor of the upstream and the refresh fast-forwards. It publishes the local commits, so the user decides.
+ */
async function divergedRefusal(git: Git, root: string, sourceId: string, upstreamRef: string, oldHead: string, targetHead: string): Promise<OperationError> {
const count = Number((await git(['-C', root, 'rev-list', '--count', `${targetHead}..${oldHead}`])).stdout.trim()) || 0;
const local = count ? `${count} local commit(s)` : 'the local commits';