Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Keep a person-needed hold's reason and skip company-brain sources when reporting commits waiting (GST-2515)

garrytan83bf877d6ff3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3a4ae138fa..9bcc76ae1a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,7 +18,7 @@ Since v0.60.677.0, every unknown-side `file_drift` hold written under the earlie
- The re-screen now reads every held path's history through one `git cat-file --batch-check` per 2,000 paths, with no file bodies, and reports progress as each path's history arrives. A Git read that hangs still reports nothing, so the no-progress check still stops it. On a generated repository with 80,000 files and 3,000 commits, 10,000 holds took 6.2 s instead of 141 s, and 80,000 holds took 66 s instead of 17 minutes. The longest silence was 36 ms instead of the whole read.
- A pass stopped partway keeps the holds it re-screened, and the next pass reads only the rest.
-- `gbrain sync status` reads `resumable` / `commits_waiting` when nothing else is pending but the checkout's HEAD is past the last synced commit, with a `next` that runs the sync. It used to read `synced` / `nothing_pending` until the next sync happened to run.
+- `gbrain sync status` reads `resumable` / `commits_waiting` when nothing else is pending (or only holds that need no person) but the checkout's HEAD is past the last synced commit, with a `next` that runs the sync. It used to read `synced` until the next sync happened to run. A hold that needs a person keeps its own reason, and a company-brain source, which syncs to its approved revision, never reads it.
- With `sync.on_commit` off, the notifier's fix now says so, instead of saying that no resident runs.
## [0.60.685.0] - 2026-11-12
diff --git a/docs/guides/sync-unblock-runbook.md b/docs/guides/sync-unblock-runbook.md
index d104c39178..bd81c5995f 100644
--- a/docs/guides/sync-unblock-runbook.md
+++ b/docs/guides/sync-unblock-runbook.md
@@ -390,6 +390,7 @@ run converges on the next plain sync with no flag.
| `deletes_withheld` | blocked | The pass's deletes crossed the mass-delete threshold (#2828) or an absolute cap (#7130: `sync.max_deletes`, default 500; `sync.max_delete_ratio`, default 0.01 above 50 deletes; per source `<key>.source.<id>`). The record's `trip` names which. It wrote one withheld record and synced everything else; no per-page hold is written. | Ask the user: restore the checkout if it is wrong; when the deletion is intended, raise the cap for that source (`gbrain config set sync.max_deletes.source.<id> <n>`) or run `GBRAIN_ALLOW_MASS_RECONCILE=1 gbrain sync --source <id>` on the brain host. `gbrain sync --source <id> --dry-run --json` lists the set and its hash. |
| `admission_paused` | resumable | `sync.admission` is `imports_only` or `classify_only`. | Ask the user to run `gbrain config set sync.admission normal` when the pause is over; it is never lifted automatically. |
| `selection_scoped` | synced | The pass converged at a selection other than the source's configured one (a CLI `--exclude`, say) and did not advance `last_commit`. | None; the next plain sync runs the configured selection. |
+| `commits_waiting` | resumable | Nothing else is pending (or only holds that need no person), but the checkout's `HEAD` is past `last_commit`: commits landed that no sync has imported yet. A company-brain source never reads it, because it syncs to its approved revision. | The plain sync, which imports them. |
The run's own JSON (`outcome`, `drain.stop_reason`) adds three stops a status
read never shows as its reason: `grant_scope` (a grant that covers only part of
diff --git a/src/core/persistence/sync-status.ts b/src/core/persistence/sync-status.ts
index c27c97342f..d22b087ce3 100644
--- a/src/core/persistence/sync-status.ts
+++ b/src/core/persistence/sync-status.ts
@@ -485,8 +485,9 @@ export async function readSyncStatus(engine: BrainEngine, sourceId: string, opts
const fenceHolds = committed?.fence_held ? await (await import('../generations/fence.ts')).fenceHoldEntries(engine, [sourceId]) : [];
const settled = statusState({ human: !!(liveError?.needs_human), heldForHuman: holds.some(hold => hold.needs_human), oldest, recovery, liveJob: liveJob !== null, unfinished, lastError: !!liveError, actionable: actionable.length > 0, holds: holds.length > 0, pass: passState });
// GST-2515: a source with nothing else pending is not synced while its checkout has commits past the last synced commit.
- // A scoped convergence keeps last_commit by design, and a writeback still integrating is the source's own commit.
- const waiting = settled[0] === 'synced' && settled[1] !== 'selection_scoped' && !gitPushHolds.length && source.last_commit
+ // A scoped convergence keeps last_commit by design, a hold that needs a person keeps its own reason, and a writeback still
+ // integrating is the source's own commit.
+ const waiting = (settled[1] === 'nothing_pending' || settled[1] === 'held_by_design') && !gitPushHolds.length && source.last_commit
? await commitsPastLastSync(engine, sourceId, source.last_commit) : null;
const [state, stateReason]: [SyncStatusState, SyncStatusReason] = waiting ? ['resumable', 'commits_waiting'] : settled;
const admission = await syncAdmissionStatus(engine, sourceId, source.incarnation,
@@ -541,8 +542,13 @@ function statusState(s: { human: boolean; heldForHuman: boolean; oldest: SyncSta
return ['synced', s.heldForHuman ? 'held_needs_human' : s.holds ? 'held_by_design' : 'nothing_pending'];
}
-/** GST-2515: how many commits the source's checkout on this host has past `lastCommit`; null when none, or when Git cannot say. */
+/**
+ * GST-2515: how many commits the source's checkout on this host has past `lastCommit`; null when none, or when Git cannot say.
+ * A company-brain source syncs to its approved revision, never to HEAD, so commits past it are not waiting.
+ */
async function commitsPastLastSync(engine: BrainEngine, sourceId: string, lastCommit: string): Promise<number | null> {
+ const [company] = await engine.executeRaw<{ id: string }>("SELECT id FROM sources WHERE id=$1 AND config->'company_brain' IS NOT NULL", [sourceId]);
+ if (company) return null;
const root = (await readCheckoutRoot(engine, sourceId).catch(() => undefined))?.root;
const lag = root ? await readGitBehind(root, lastCommit).catch(() => null) : null;
return lag?.commits ? lag.commits : null;
diff --git a/test/sync-status-commits-waiting-gst2515.test.ts b/test/sync-status-commits-waiting-gst2515.test.ts
index df3be3a1fe..bebca6e304 100644
--- a/test/sync-status-commits-waiting-gst2515.test.ts
+++ b/test/sync-status-commits-waiting-gst2515.test.ts
@@ -30,10 +30,17 @@ for (const backend of testBackends()) {
git(root, 'add', '-A'); git(root, 'commit', '-qm', 'two');
const waiting = await readSyncStatus(engine, 'default');
expect(waiting).toMatchObject({ state: 'resumable', reason: 'commits_waiting' });
- expect(waiting.next?.argv.slice(0, 2)).toEqual(['gbrain', 'sync']);
+ expect(waiting.next?.argv?.slice(0, 2)).toEqual(['gbrain', 'sync']);
expect(waiting.next?.argv).toContain('default');
expect(waiting.next?.why).toContain('1 commit(s) past the last synced commit');
await performManagedSync(engine, OPTS);
expect(await readSyncStatus(engine, 'default')).toMatchObject({ state: 'synced', reason: 'nothing_pending', last_commit: git(root, 'rev-parse', 'HEAD') });
}, { databaseUrl, setup }), 120_000);
+ test('[' + backend + '] a company-brain source, which syncs to its approved revision, never reads commits_waiting', () => managedBrain(async ({ engine, root }) => {
+ await performManagedSync(engine, OPTS);
+ await engine.executeRaw(`UPDATE sources SET config = config || '{"company_brain":{}}'::jsonb WHERE id='default'`);
+ writeFileSync(join(root, 'notes/two.md'), '---\ntitle: Two\n---\n\nThe second note.\n');
+ git(root, 'add', '-A'); git(root, 'commit', '-qm', 'two');
+ expect((await readSyncStatus(engine, 'default')).reason).not.toBe('commits_waiting');
+ }, { databaseUrl, setup }), 120_000);
}