Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.8 KB
Raw Blame

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-reads sync.on_commit and sync.on_commit.sources every 30 s (parseOnCommit is 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, no index.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 at RETRY_BACKOFF_MS (5 s, 15 s, 1 min, 5 min) and reports notifier_stalled past the last tier without progress (GBRA-133 PR 3a: a run whose status says committed is progress even before last_commit moves, and a drain-lease holder that drainHeld reports stalled is a failed attempt, drain_holder_stalled, instead of a silent defer; test/honest-stalls-gbra133.test.ts); operator_blocked waits for HEAD to move. A source listed with syncDisabled (config.syncEnabled=false, GST-2515) is never watched and owes no retry; a wanted marker runs once, and a failed run waits as operator_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 (migration v262-commit-notifier.ts): sync_wanted_markers (source + intent freshness|pull|full, generation bumped on every upsert, first_due_at kept), 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 only WHERE generation = the value it read (clearMarker, settleMarkers); freshness is due while wanted_head IS DISTINCT FROM last_commit (no ancestry assumption). recordLocalSyncer runs where writeSyncAnchor advances last_commit: records the syncer host and prunes satisfied markers (the CLI's re-check). missingTable lets 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 through src/core/serve-head-watcher.ts, gbrain jobs work, the autopilot daemon). Never awaits: the first pass runs in the background. GBRAIN_NOTIFIER=0 turns it off per process. Lists managed sources whose worktree this host owns and classic sources whose recorded syncer is this host (or GBRAIN_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.ts resolves --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: runnerStart starts the delegated run with logLines, 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. recordTriggerMarker picks the intent (managed: freshness at the checkout HEAD; classic: pull) and recordSyncNudge answers the versioned, acknowledged sync_nudge IPC kind (src/core/context/sync-ipc.ts, resolve-ipc.ts, bound in src/mcp/resolve-ipc-binding.ts). handoff.ts is the post-run re-check of the sync job handler and the serve's delegated runner: read before the run, settle after, at most one follow-up (a queued job with maxWaiting: 1, or a nudge); a lock-busy skip records a marker and completes. gbrain sync trigger answers queued / coalesced (maxPending: 1) / nudged, exit 0, with the no_resident notice when no resident watches the source; on PGLite a live serve takes it over IPC (maybeTriggerThroughServe in src/commands/sync-delegate.ts, which also records a busy delegated sync). The GitHub push webhook (submitGitHubPush in src/commands/serve-http-webhooks.ts) records the pushed sha first; a managed source answers 409 refresh_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): readSourceFreshness feeds the freshness entry of search and query responses (src/core/ops/search.ts buildRetrievalResponseMeta; current, behind, syncing, unknown, not_monitored), and readNotifierBlock / formatNotifierBlock the notifier block for sync status and doctor (resident or none with the gbrain sync --source <id> --no-pull fix; 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, readNotifierBlock reads the drain lease holder (readDrainHolder, drain_holder, redacted by publicDrainHolder for remote callers) and offers no fix while it progresses, the sync-now fix only once holderStalled; formatNotifierBlock names 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) gives recorded_resident (kind, pid, host, seen_at, the lapsed lease_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 doctor managed_sync_latency and src/core/source-health.ts. Behind = checkout HEAD differs from sources.last_commit (HEAD only). Dated from the reflog entry that first moved HEAD off last_commit (<git dir>/logs/HEAD read as a file, last 1 MiB), else the notifier's persisted first_due_at (sync_notifier_sources while not idle, or a due freshness marker; current incarnation only), else unknown with no_reflog or history_rewritten. git: false (a remote doctor) reads the database only; a source the notifier never recorded reads not_observed, never current. readEmbedBacklog ages live unembedded chunks from embedding_pending_since (keyless brains read disabled). managed_sync_latency grades a waiting commit like a p95 sample (over the target warns, over max(1 h, target) fails, unknown age warns, only with sync.on_commit or a target), grades classic sources on a non-managed brain, and reports details.freshness_by_source with keyword_visible and embedded per 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.