Garry's Opinionated OpenClaw/Hermes Agent Brain
Key files: Commit notifier
Subsystem index. Read only the entries relevant to your change. Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG.
src/core/commit-notifier.ts— the notifier core, pure over its seams (store, git reads, the runner). One loop per resident: claims the host lease every heartbeat (GBRAIN_NOTIFIER_HEARTBEAT_MS, default 10 s, lease two heartbeats; PGLite has no lease and the brain's holder owns), re-readssync.on_commitandsync.on_commit.sourcesevery 30 s (parseOnCommitis the one parser), lists the host's sources every 60 s, reads HEAD every poll (GBRAIN_NOTIFIER_POLL_MS, 3 s; a watch only nudges), and scans wanted markers every 15 s or on a nudge, with the flag off too. Starts on the leading edge of a quiet HEAD move (no rebase/merge/cherry-pick marker, noindex.lock), then a 400 ms trailing window (GBRAIN_NOTIFIER_QUIET_MS). Per-source single flight under a host cap, least recently started first. Keeps a source due across refused starts, failed or blocked runs and resumable stops; retries atRETRY_BACKOFF_MS(5 s, 15 s, 1 min, 5 min) and reportsnotifier_stalledpast the last tier without progress (GBRA-133 PR 3a: a run whose status sayscommittedis progress even beforelast_commitmoves, and a drain-lease holder thatdrainHeldreportsstalledis a failed attempt,drain_holder_stalled, instead of a silent defer;test/honest-stalls-gbra133.test.ts);operator_blockedwaits for HEAD to move. A source listed withsyncDisabled(config.syncEnabled=false, GST-2515) is never watched and owes no retry; a wanted marker runs once, and a failed run waits asoperator_blocked(sync_disabled) for a new request (test/notifier-sync-disabled-gst2515.test.ts). Checks the fence before each start. Every decision is recorded (decisions) for tests; state and coverage rows are written on change only. Managed sources never take pull markers. Tests:test/serve-head-watcher.test.ts(memory store,test/helpers/notifier-memory-store.ts).src/core/notifier/store.ts— the durable rows (migrationv262-commit-notifier.ts):sync_wanted_markers(source + intent freshness|pull|full,generationbumped on every upsert,first_due_atkept),sync_notifier_leases(one owner per host, fence bumped on takeover, release expires it now),sync_notifier_sources(state, retry schedule, last error and trace path, classic syncer host, coverage record). A drainer deletes onlyWHERE generation =the value it read (clearMarker,settleMarkers); freshness is due whilewanted_head IS DISTINCT FROM last_commit(no ancestry assumption).recordLocalSyncerruns wherewriteSyncAnchoradvanceslast_commit: records the syncer host and prunes satisfied markers (the CLI's re-check).missingTablelets callers on a pre-v262 brain read "nothing monitored".src/core/notifier/resident.ts+src/core/notifier/detect.ts— production seams and the one start path for every resident (startResidentNotifier: serve, serve --http throughsrc/core/serve-head-watcher.ts,gbrain jobs work, the autopilot daemon). Never awaits: the first pass runs in the background.GBRAIN_NOTIFIER=0turns it off per process. Lists managed sources whose worktree this host owns and classic sources whose recorded syncer is this host (orGBRAIN_NOTIFIER_CLASSIC_SOURCES), skipping the rest with a reason. Starts syncs through the in-process delegated runner. Trace per source at<gbrain home>/notifier/<source>.jsonl.detect.tsresolves--absolute-git-dir/--git-common-dir(linked worktrees) and the quiet predicate. Tests:test/pathological/s-notifier-classic-serve.test.ts,test/pathological/s-notifier-residents.test.ts. #7243:runnerStartstarts the delegated run withlogLines, so a background run nobody polls also writes its human lines (the pass's round phase lines and progress) to the serve log as[serve-sync] job=<id> …(test/sync-pass-phase-lines-7243.serial.test.ts).src/core/notifier/nudge.ts+src/core/notifier/handoff.ts+src/commands/sync/trigger.ts— submitters and drainers of wanted markers.recordTriggerMarkerpicks the intent (managed: freshness at the checkout HEAD; classic: pull) andrecordSyncNudgeanswers the versioned, acknowledgedsync_nudgeIPC kind (src/core/context/sync-ipc.ts,resolve-ipc.ts, bound insrc/mcp/resolve-ipc-binding.ts).handoff.tsis the post-run re-check of thesyncjob handler and the serve's delegated runner: read before the run, settle after, at most one follow-up (a queued job withmaxWaiting: 1, or a nudge); a lock-busy skip records a marker and completes.gbrain sync triggeranswers queued / coalesced (maxPending: 1) / nudged, exit 0, with theno_residentnotice when no resident watches the source; on PGLite a live serve takes it over IPC (maybeTriggerThroughServeinsrc/commands/sync-delegate.ts, which also records a busy delegated sync). The GitHub push webhook (submitGitHubPushinsrc/commands/serve-http-webhooks.ts) records the pushed sha first; a managed source answers 409refresh_required. Tests:test/pathological/s-notifier-marker-handoff.test.ts.src/core/notifier/status.ts— what users and agents see, from rows only (no git call):readSourceFreshnessfeeds thefreshnessentry of search and query responses (src/core/ops/search.tsbuildRetrievalResponseMeta; current, behind, syncing, unknown, not_monitored), andreadNotifierBlock/formatNotifierBlockthe notifier block for sync status and doctor (resident or none with thegbrain sync --source <id> --no-pullfix; remote callers get no trace path, pid or host id). An owner is live by its unexpired lease (Postgres) or a running pid on this host (PGLite). Tests:test/pathological/s-notifier-freshness-status.test.ts. #7189: with no live notifier owner,readNotifierBlockreads the drain lease holder (readDrainHolder,drain_holder, redacted bypublicDrainHolderfor remote callers) and offers no fix while it progresses, the sync-now fix only onceholderStalled;formatNotifierBlocknames it (test/sync-status-coherence-7189.test.ts). #7243: with no live owner and no drain holder, a coverage row that names a resident (owner_kind, the resident its trace rows name) givesrecorded_resident(kind, pid, host,seen_at, the lapsedlease_expired_at; no pid or host remotely), and the fix names that resident and its lapsed lease instead of "No resident … watches this source" (test/sync-status-truthful-7243.test.ts).src/core/sync-pending.ts— GBRA-133 2b.5: the oldest unsynced commit per source and the embedding backlog, read by doctormanaged_sync_latencyandsrc/core/source-health.ts. Behind = checkout HEAD differs fromsources.last_commit(HEAD only). Dated from the reflog entry that first moved HEAD offlast_commit(<git dir>/logs/HEADread as a file, last 1 MiB), else the notifier's persistedfirst_due_at(sync_notifier_sourceswhile not idle, or a due freshness marker; current incarnation only), elseunknownwithno_reflogorhistory_rewritten.git: false(a remote doctor) reads the database only; a source the notifier never recorded readsnot_observed, never current.readEmbedBacklogages live unembedded chunks fromembedding_pending_since(keyless brains readdisabled).managed_sync_latencygrades a waiting commit like a p95 sample (over the target warns, over max(1 h, target) fails, unknown age warns, only withsync.on_commitor a target), grades classic sources on a non-managed brain, and reportsdetails.freshness_by_sourcewithkeyword_visibleandembeddedper source (embedded is not graded). Tests:test/pathological/s-truthful-sync-status.test.ts+ its Postgres twin,test/sync-freshness-6858.test.ts.
Autopilot and the jobs worker
In src/commands/autopilot.ts: #7003: --status passes the daemon's sidecar verdict (readDaemonStaleAfter, src/core/autopilot-heartbeat.ts) to classifyAutopilotStatus as daemon; without a matching sidecar it keeps 6 x --interval. --status --json adds stale_after_source and next_tick_at. Tests: test/pathological/s-7003-autopilot-heartbeat.test.ts + its Postgres twin.
In src/commands/autopilot-dispatch.ts: GBRA-133 2a.4: freshness is HEAD-driven. freshnessTrigger returns head when the checkout's HEAD (src/core/checkout-head.ts) differs from sources.last_commit and from the HEAD this daemon last decided (freshnessHeads), interval for the wall-clock backstop, nothing mid-rebase or merge. HEAD jobs use the key autopilot-sync:<id>:head:<sha>. dispatchFreshnessSyncs returns a FreshnessDecision per source. sleepWatchingHeads: with sync.on_commit on, the Minions-mode sleep probes HEADs every GBRAIN_AUTOPILOT_HEAD_PROBE_MS (3 s, 1-30 s; no DB read) and dispatches for moved sources. Tests: test/pathological/s-autopilot-head-dispatch.test.ts + its Postgres twin.