Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes (shared owner read per worktree with a self-cancelling budget, owner facts on blocked receipts, database clock for staleness, unconfirmed identity keeps the old disable)

garrytan0efe179f27e7
diff --git a/docs/architecture/key-files/core-persistence-capacity.md b/docs/architecture/key-files/core-persistence-capacity.md
index b09591a8f4..17a275a5f2 100644
--- a/docs/architecture/key-files/core-persistence-capacity.md
+++ b/docs/architecture/key-files/core-persistence-capacity.md
@@ -23,4 +23,4 @@ What a managed publish costs in statements and round trips, and how it is measur
- `src/core/postgres-engine/pool-stats.ts` — #6317 (C1, G1): `driverPoolStats(sql)` reads the vendored postgres.js driver's `sql.pool` getter (`vendor/postgres`, patch regenerated) for real `{checked_out, max, waiters}`; `enginePoolStats(engine)` labels the source (`driver` or `tracked_subset` from `pool-gauge.ts`). Filled into the heartbeat row, `writer status` running claims and `getPoolDiagnostics()`.
- `src/core/persistence/maintenance-wait.ts` — how long a maintenance publisher waits for its accepted write to commit before the receipt reports `write_pending` (#5854). `MAINTENANCE_WRITE_WAIT_MS` is 30 s; `MaintenanceWriteWait` is one budget per job: each wait is capped by the job's remaining deadline (zero at or past it), and once one publish is still pending after its wait (`observe`) every later publish in that job waits zero and is deferred like it. A pending write keeps its request identity and commits later; it is never reported as committed. A `MaintenanceWriteWait` with no deadline also sets the replay window of a subagent tool write whose job has none (`minions/tool-write-identity.ts`). `__setMaintenanceWriteWaitForTests` replaces the base wait, those tool writes included. Tests: `test/maintenance-write-wait.test.ts`, `test/e2e/maintenance-write-wait.test.ts`.
- `src/core/persistence/effect-settle.ts` — `gbrain sources writer settle-effects <source> (--request-id|--parked-code) [--unsettle] [--dry-run|--apply --expect <plan_hash>]` (`writer_settle_effects`, an administration extension) (#7423, #7378): records `data.settled` (and appends to `data.settlements`) on a failed Git effect no retry can move, never touching its failure, parked targets, request or bytes. It settles only on an exact-target proof re-checked under row locks at apply: each target declared `db_only` in the current binding's gbrain.yml (`sourceDbOnlyDir`), or, for an effect `guardEffectSource` refuses `source_changed` because the source moved to a new worktree (same incarnation, this host owning the active binding), a later committed and pushed Git effect of the current worktree whose `expected_hash` equals the canonical file now and a blob at the already-fetched `@{upstream}` equal to it (no fetch). Withdrawal effects, claims, open recovery records, revoked writers, replaced sources and unknown targets refuse; an effect of the current binding that is not db_only refuses `retry_instead`. The plan hash is doctor --remediate's `computePlanHash` over the brain, source, selector, owner epoch and each proof (`preview_changed` otherwise). Readers that skip settled rows: doctor `parked_effects`, `rearmWithheldTargets`, `readParkedGroups`, `readGitPushHolds`, `retryParkedPushes`/`--parked-code`, `retryIndexLockParks`, `sync status`, `failedEffectHistory`; `retryParkedEffects` reports a settled effect as `action: settled`. `retryParkedPushes` also reaches a push that failed without parked targets (#7378, `failedCodes`). Tests: `test/persistence-effect-settle.test.ts` (scenarios in `test/helpers/effect-settle-scenarios.ts`) + the Postgres arm in `test/e2e/w5-persistence-postgres.test.ts`.
-- `src/core/persistence/owner-activity.ts` — GBRA-248: `ownerActivity(engine, worktreeIds)` reads each worktree owner's liveness (a `persistence_consumers` row renewed within the lapse window) and last activity (the greatest of the worktree heartbeat, which a consumer's clean stop stamps, its newest consumer renewal and the newest committed receipt, read through the foreground-committed and sync-watermark indexes). `stale` is true when the owner is not this host and not live, and either this process holds a PGLite file under another identity or the owner has been quiet past `OWNER_STALE_MS` (24 h; with no activity recorded, the oldest open request's age decides). `startOwnerRead` runs it inside a budget the caller already has (the journal's 500 ms receipt read, the last 500 ms of `awaitWrite`'s wait) and cancels it past that; `writeHealth` maps a stale owner to `owner_unavailable` (unless recovery outranks it) with a `diagnostic.owner` block carrying only `last_active`, present whenever the owner is stale, and `acceptPendingCovers` in write-wait.ts keeps such a write at exit 10 under `--accept-pending`. Read-only; null activity authorizes nothing.
+- `src/core/persistence/owner-activity.ts` — GBRA-248: `ownerActivity(engine, worktreeIds)` reads each worktree owner's liveness (a `persistence_consumers` row renewed within the lapse window) and last activity (the greatest of the worktree heartbeat, which a consumer's clean stop stamps, its newest consumer renewal and the newest committed receipt, read through the foreground-committed and sync-watermark indexes). `stale` is true when the owner is not this host and not live, and either this process holds a PGLite file under another identity or the owner has been quiet past `OWNER_STALE_MS` (24 h; with no activity recorded, the oldest open request's age decides). `startOwnerRead` runs it inside a budget the caller already has (the journal's 500 ms receipt read; `awaitWrite`'s last 500 ms, which a shorter wait is extended to, with each worktree's answer reused for 10 s so a batch pays one read) and cancels it past that; staleness uses the database clock; `writeHealth` maps a stale owner to `owner_unavailable` (unless recovery outranks it) with a `diagnostic.owner` block carrying only `last_active`, present whenever the owner is stale, and `acceptPendingCovers` in write-wait.ts keeps such a write at exit 10 under `--accept-pending`. Read-only; null activity authorizes nothing.
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
index 686e672cf3..1638111290 100644
--- a/docs/guides/troubleshooting.md
+++ b/docs/guides/troubleshooting.md
@@ -189,7 +189,7 @@ A `drain_stalled` stop with `cause: owner_wedged_here` is the same situation see
<a id="host-identity-mismatch"></a>**Doctor warns `host_identity_mismatch`, or fence repair, chronicle and other maintenance jobs have reported `owner_unavailable` with reason `host_mismatch` for days?** Host identity is a file, `host.json` under the persistence home (`GBRAIN_HOME`, else `$HOME/.gbrain`). A job worker or container launched with a different `HOME` or without `GBRAIN_HOME` mints a new identity after every restart and sees the binding as another host's, so its writes never reach the owner while every health signal stays green. Doctor flags it when this process's identity differs from the binding owner's and the owner's checkout resolves on this filesystem (same machine id or volume), or, for a container without a stable machine id, when the checkout is present at the binding's path and this `host.json` was minted after the binding under a different `HOME`/`GBRAIN_HOME`. The check names both files, the environment each was minted under (`minted_under: {home, gbrain_home, hostname, machine_id}`; `unknown` for a file minted before it was recorded) and the one-line fix: set `GBRAIN_HOME` on that process's supervisor to the owner's home (the printed value; config appends `.gbrain` itself) and restart it. Nothing re-derives or rewrites an existing `host.json`: re-owning the binding would break every other host sharing the brain. Verify with `gbrain doctor --only host_identity_mismatch --json`.
-<a id="owner-host-stale"></a>**A pending write names a stale owner in `diagnostic.owner`, `--accept-pending` still exits 10, or doctor warns `owner_host_stale`?** A managed source publishes only through the host that owns its checkout, named by its `host.json` identity. When a brain is moved or restored onto another machine, or a container restarts with a new `GBRAIN_HOME`, the new process gets a new identity and its writes queue for the old owner, which may never return. The receipt names that case: `diagnostic.reason` is `owner_unavailable` and a `diagnostic.owner` block, present whenever the owner is stale, carries its last recorded activity (doctor names the owner host; receipts leave the host id out because they reach remote callers) (its newest consumer heartbeat, its newest publication, or the time its consumer last stopped cleanly). It applies when the owner runs no live consumer and has been quiet for more than 24 hours, or at once on PGLite when this process holds the database file under a different identity; the owner host itself never sees it. `--accept-pending` and `GBRAIN_ACCEPT_PENDING=1` cover a write that will commit on its own, so a write with a `diagnostic.owner` block exits 10 with them, and the CLI says so. Nothing is lost: the writes stay queued with their request ids. Run `gbrain sources writer status --json` (read-only) to see the binding owner. Bring the owner host back, or run this process with the owner's `GBRAIN_HOME` (the parent of its `.gbrain` directory) and restart it. For servers and containers, keep `GBRAIN_HOME` on a persistent volume that is stable across restarts, or use sources with no checkout root, whose writes any consumer publishes. Never edit, copy or delete a `host.json`, and nothing claims or transfers ownership automatically. Verify with `gbrain doctor --only owner_host_stale --json`; [`host_identity_mismatch`](#host-identity-mismatch) covers an owner whose checkout this filesystem holds.
+<a id="owner-host-stale"></a>**A pending write names a stale owner in `diagnostic.owner`, `--accept-pending` still exits 10, or doctor warns `owner_host_stale`?** A managed source publishes only through the host that owns its checkout, named by its `host.json` identity. When a brain is moved or restored onto another machine, or a container restarts with a new `GBRAIN_HOME`, the new process gets a new identity and its writes queue for the old owner, which may never return. The receipt names that case: `diagnostic.reason` is `owner_unavailable` and a `diagnostic.owner` block, present whenever the owner is stale, carries its last recorded activity: its newest consumer heartbeat, its newest publication, or the time its consumer last stopped cleanly. Doctor names the owner host; receipts leave the host id out because they reach remote callers. It applies when the owner runs no live consumer and has been quiet for more than 24 hours, or at once on PGLite when this process holds the database file under a different identity; the owner host itself never sees it. `--accept-pending` and `GBRAIN_ACCEPT_PENDING=1` cover a write that will commit on its own, so a write with a `diagnostic.owner` block exits 10 with them, and the CLI says so. Nothing is lost: the writes stay queued with their request ids. Run `gbrain sources writer status --json` (read-only) to see the binding owner. Bring the owner host back, or run this process with the owner's `GBRAIN_HOME` (the parent of its `.gbrain` directory) and restart it. For servers and containers, keep `GBRAIN_HOME` on a persistent volume that is stable across restarts, or use sources with no checkout root, whose writes any consumer publishes. Never edit, copy or delete a `host.json`, and nothing claims or transfers ownership automatically. Verify with `gbrain doctor --only owner_host_stale --json`; [`host_identity_mismatch`](#host-identity-mismatch) covers an owner whose checkout this filesystem holds.
<a id="managed-sync-wedge-transcript"></a>**What the agent sees while a catch-up is wedged, step by step.** The brain is `default`, the owner is a `gbrain serve` with pid 4121, the sync CLI runs beside it, and the head write of a 16-member bulk group has been `preparing` with nothing in flight at the database. Output is abbreviated to the fields that decide the next step.
diff --git a/llms-full.txt b/llms-full.txt
index 825700deae..694d8a1068 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -10080,7 +10080,7 @@ A `drain_stalled` stop with `cause: owner_wedged_here` is the same situation see
<a id="host-identity-mismatch"></a>**Doctor warns `host_identity_mismatch`, or fence repair, chronicle and other maintenance jobs have reported `owner_unavailable` with reason `host_mismatch` for days?** Host identity is a file, `host.json` under the persistence home (`GBRAIN_HOME`, else `$HOME/.gbrain`). A job worker or container launched with a different `HOME` or without `GBRAIN_HOME` mints a new identity after every restart and sees the binding as another host's, so its writes never reach the owner while every health signal stays green. Doctor flags it when this process's identity differs from the binding owner's and the owner's checkout resolves on this filesystem (same machine id or volume), or, for a container without a stable machine id, when the checkout is present at the binding's path and this `host.json` was minted after the binding under a different `HOME`/`GBRAIN_HOME`. The check names both files, the environment each was minted under (`minted_under: {home, gbrain_home, hostname, machine_id}`; `unknown` for a file minted before it was recorded) and the one-line fix: set `GBRAIN_HOME` on that process's supervisor to the owner's home (the printed value; config appends `.gbrain` itself) and restart it. Nothing re-derives or rewrites an existing `host.json`: re-owning the binding would break every other host sharing the brain. Verify with `gbrain doctor --only host_identity_mismatch --json`.
-<a id="owner-host-stale"></a>**A pending write names a stale owner in `diagnostic.owner`, `--accept-pending` still exits 10, or doctor warns `owner_host_stale`?** A managed source publishes only through the host that owns its checkout, named by its `host.json` identity. When a brain is moved or restored onto another machine, or a container restarts with a new `GBRAIN_HOME`, the new process gets a new identity and its writes queue for the old owner, which may never return. The receipt names that case: `diagnostic.reason` is `owner_unavailable` and a `diagnostic.owner` block, present whenever the owner is stale, carries its last recorded activity (doctor names the owner host; receipts leave the host id out because they reach remote callers) (its newest consumer heartbeat, its newest publication, or the time its consumer last stopped cleanly). It applies when the owner runs no live consumer and has been quiet for more than 24 hours, or at once on PGLite when this process holds the database file under a different identity; the owner host itself never sees it. `--accept-pending` and `GBRAIN_ACCEPT_PENDING=1` cover a write that will commit on its own, so a write with a `diagnostic.owner` block exits 10 with them, and the CLI says so. Nothing is lost: the writes stay queued with their request ids. Run `gbrain sources writer status --json` (read-only) to see the binding owner. Bring the owner host back, or run this process with the owner's `GBRAIN_HOME` (the parent of its `.gbrain` directory) and restart it. For servers and containers, keep `GBRAIN_HOME` on a persistent volume that is stable across restarts, or use sources with no checkout root, whose writes any consumer publishes. Never edit, copy or delete a `host.json`, and nothing claims or transfers ownership automatically. Verify with `gbrain doctor --only owner_host_stale --json`; [`host_identity_mismatch`](#host-identity-mismatch) covers an owner whose checkout this filesystem holds.
+<a id="owner-host-stale"></a>**A pending write names a stale owner in `diagnostic.owner`, `--accept-pending` still exits 10, or doctor warns `owner_host_stale`?** A managed source publishes only through the host that owns its checkout, named by its `host.json` identity. When a brain is moved or restored onto another machine, or a container restarts with a new `GBRAIN_HOME`, the new process gets a new identity and its writes queue for the old owner, which may never return. The receipt names that case: `diagnostic.reason` is `owner_unavailable` and a `diagnostic.owner` block, present whenever the owner is stale, carries its last recorded activity: its newest consumer heartbeat, its newest publication, or the time its consumer last stopped cleanly. Doctor names the owner host; receipts leave the host id out because they reach remote callers. It applies when the owner runs no live consumer and has been quiet for more than 24 hours, or at once on PGLite when this process holds the database file under a different identity; the owner host itself never sees it. `--accept-pending` and `GBRAIN_ACCEPT_PENDING=1` cover a write that will commit on its own, so a write with a `diagnostic.owner` block exits 10 with them, and the CLI says so. Nothing is lost: the writes stay queued with their request ids. Run `gbrain sources writer status --json` (read-only) to see the binding owner. Bring the owner host back, or run this process with the owner's `GBRAIN_HOME` (the parent of its `.gbrain` directory) and restart it. For servers and containers, keep `GBRAIN_HOME` on a persistent volume that is stable across restarts, or use sources with no checkout root, whose writes any consumer publishes. Never edit, copy or delete a `host.json`, and nothing claims or transfers ownership automatically. Verify with `gbrain doctor --only owner_host_stale --json`; [`host_identity_mismatch`](#host-identity-mismatch) covers an owner whose checkout this filesystem holds.
<a id="managed-sync-wedge-transcript"></a>**What the agent sees while a catch-up is wedged, step by step.** The brain is `default`, the owner is a `gbrain serve` with pid 4121, the sync CLI runs beside it, and the head write of a 16-member bulk group has been `preparing` with nothing in flight at the database. Output is abbreviated to the fields that decide the next step.
diff --git a/src/commands/init-embedding-plane.ts b/src/commands/init-embedding-plane.ts
index cbe2834c78..eb377e751e 100644
--- a/src/commands/init-embedding-plane.ts
+++ b/src/commands/init-embedding-plane.ts
@@ -13,8 +13,8 @@ import { readPrimaryEmbeddingStores, readStoredEmbeddingIdentity } from '../core
import { resolveRecipe } from '../core/ai/model-resolver.ts';
import type { ResolvedAIOptions } from './init.ts';
-/** What the file plane keeps: the database's identity, or nothing (no embedding_disabled) when it holds vectors whose identity cannot be confirmed. */
-export interface KeptEmbedding { model?: string; dimensions?: number }
+/** The database identity the file plane keeps. Vectors whose model or width cannot be confirmed keep nothing: embedding_disabled is written as before, and doctor embedding_plane_disagreement points at migrate embeddings --status. */
+export interface KeptEmbedding { model: string; dimensions: number }
export async function keptEmbeddingIdentity(engine: BrainEngine, aiOpts: ResolvedAIOptions | undefined, fresh: boolean): Promise<KeptEmbedding | null> {
if (!aiOpts?.noEmbedding || !aiOpts.implicitKeyless || fresh) return null;
@@ -28,12 +28,11 @@ export async function keptEmbeddingIdentity(engine: BrainEngine, aiOpts: Resolve
const stored = await readStoredEmbeddingIdentity(engine).catch(() => null);
const configured = Number(await engine.getConfig('embedding_dimensions').catch(() => null) ?? NaN);
const agrees = stored?.model && (!Number.isFinite(configured) || configured === stored.dimensions);
- return agrees ? { model: stored!.model!, dimensions: stored!.dimensions } : {};
+ return agrees ? { model: stored!.model!, dimensions: stored!.dimensions } : null;
}
/** The notice init prints instead of the deferred-setup hint when it kept the database's identity. */
export function keptEmbeddingNotice(kept: KeptEmbedding): string {
- if (!kept.model) return ' Embedding: this database already holds vectors whose model could not be confirmed, so init left embedding settings unchanged instead of disabling them. Run gbrain migrate embeddings --status, then gbrain doctor --only embedding_plane_disagreement --json.';
let key = 'the provider API key';
try { key = resolveRecipe(kept.model.includes(':') ? kept.model : `openai:${kept.model}`).recipe.auth_env?.required?.[0] ?? key; } catch { /* unknown provider: generic wording */ }
return ` Embedding: kept this database's ${kept.model} (${kept.dimensions}d) instead of disabling embeddings; no provider key was found. Set ${key}, then run gbrain embed --stale to embed pages written meanwhile.`;
diff --git a/src/commands/init.ts b/src/commands/init.ts
index b79c493e4f..56fbad442a 100644
--- a/src/commands/init.ts
+++ b/src/commands/init.ts
@@ -1217,7 +1217,7 @@ export async function initPGLite(opts: {
database_path: dbPath,
...(opts.apiKey ? { openai_api_key: opts.apiKey } : {}),
...(opts.aiOpts?.noEmbedding
- ? kept ? (kept.model ? { embedding_model: kept.model, embedding_dimensions: kept.dimensions } : {}) : { embedding_disabled: true }
+ ? kept ? { embedding_model: kept.model, embedding_dimensions: kept.dimensions } : { embedding_disabled: true }
: (resolvedModel && resolvedDim)
? { embedding_model: resolvedModel, embedding_dimensions: resolvedDim }
: {}),
@@ -1562,7 +1562,7 @@ export async function initPostgresCore(opts: {
database_path: undefined, // clear any stale PGLite path
...(opts.apiKey ? { openai_api_key: opts.apiKey } : {}),
...(opts.aiOpts?.noEmbedding
- ? kept ? (kept.model ? { embedding_model: kept.model, embedding_dimensions: kept.dimensions } : {}) : { embedding_disabled: true }
+ ? kept ? { embedding_model: kept.model, embedding_dimensions: kept.dimensions } : { embedding_disabled: true }
: (resolvedModel && resolvedDim)
? { embedding_model: resolvedModel, embedding_dimensions: resolvedDim }
: {}),
diff --git a/src/core/persistence/journal.ts b/src/core/persistence/journal.ts
index 9a1c164195..fc748a994e 100644
--- a/src/core/persistence/journal.ts
+++ b/src/core/persistence/journal.ts
@@ -1254,7 +1254,7 @@ export async function writeHealthFacts(engine: BrainEngine, rows: WriteRequest[]
const facts = await Promise.race([query, new Promise<null>(resolve => {
timer = setTimeout(() => { abort.abort(); resolve(null); }, OWNER_READ_BUDGET_MS);
})]).finally(() => { if (timer) clearTimeout(timer); });
- const owners = await settleOwners(facts ? OWNER_READ_BUDGET_MS - (performance.now() - ownerReadStarted) : 0);
+ const owners = await settleOwners(facts ? OWNER_READ_BUDGET_MS - (performance.now() - ownerReadStarted) : 0) ?? new Map();
if (!facts) return result;
const byRoot = new Map(facts.map(fact => [fact.root, fact]));
for (const row of pending) {
diff --git a/src/core/persistence/owner-activity.ts b/src/core/persistence/owner-activity.ts
index d17f2e9c22..8c7cfc8a0a 100644
--- a/src/core/persistence/owner-activity.ts
+++ b/src/core/persistence/owner-activity.ts
@@ -39,12 +39,11 @@ export interface OwnerActivity {
}
export async function ownerActivity(engine: BrainEngine, worktreeIds: readonly string[], opts: { now?: number; signal?: AbortSignal } = {}): Promise<Map<string, OwnerActivity>> {
- const now = opts.now ?? Date.now();
const result = new Map<string, OwnerActivity>();
const ids = [...new Set(worktreeIds)].filter(Boolean);
if (!ids.length) return result;
- const rows = await engine.executeRaw<{ worktree_id: string; owner_host_id: string; live: boolean; last_active: string | Date | null; oldest_open: string | Date | null }>(`
- SELECT w.id::text AS worktree_id, w.owner_host_id::text AS owner_host_id,
+ const rows = await engine.executeRaw<{ worktree_id: string; owner_host_id: string; live: boolean; last_active: string | Date | null; oldest_open: string | Date | null; db_now: string | Date }>(`
+ SELECT now() AS db_now, w.id::text AS worktree_id, w.owner_host_id::text AS owner_host_id,
EXISTS (SELECT 1 FROM persistence_consumers c WHERE c.host_id=w.owner_host_id
AND c.renewed_at > now() - ($2::double precision * interval '1 millisecond')) AS live,
GREATEST(w.heartbeat_at,
@@ -64,7 +63,7 @@ export async function ownerActivity(engine: BrainEngine, worktreeIds: readonly s
const self = local === row.owner_host_id;
const foreign = engine.kind === 'pglite' && local !== null && !self;
const since = lastActive ?? (row.oldest_open === null ? null : new Date(row.oldest_open).toISOString());
- const quiet = since !== null && now - Date.parse(since) > OWNER_STALE_MS;
+ const quiet = since !== null && (opts.now ?? new Date(row.db_now).getTime()) - Date.parse(since) > OWNER_STALE_MS;
result.set(row.worktree_id, { worktree_id: row.worktree_id, owner_host_id: row.owner_host_id, live: !!row.live,
last_active: lastActive, foreign_file_holder: foreign, stale: !self && !row.live && (foreign || quiet) });
}
@@ -76,18 +75,21 @@ export const OWNER_READ_BUDGET_MS = 500;
/**
* Starts the owner read now and returns `settle(ms)`, which waits at most that
- * much longer for it. A read still running then is cancelled (Postgres) and adds
- * no owner facts, as does a failed one, so callers fold it into a budget they
- * already have instead of adding one.
+ * much longer for it. The read is cancelled (Postgres) OWNER_READ_BUDGET_MS
+ * after it starts, or when a settle gives up first, and then, like a failed
+ * read, settles to null (no answer), so callers fold it into a budget they
+ * already have instead of adding one and no read outlives that budget.
*/
-export function startOwnerRead(engine: BrainEngine, worktreeIds: readonly string[]): (budgetMs: number) => Promise<Map<string, OwnerActivity>> {
+export function startOwnerRead(engine: BrainEngine, worktreeIds: readonly string[]): (budgetMs: number) => Promise<Map<string, OwnerActivity> | null> {
const abort = new AbortController();
- const read = worktreeIds.length ? ownerActivity(engine, worktreeIds, { signal: abort.signal }).catch(() => null) : Promise.resolve(null);
+ const expiry = setTimeout(() => abort.abort(), OWNER_READ_BUDGET_MS);
+ const read = (worktreeIds.length ? ownerActivity(engine, worktreeIds, { signal: abort.signal }).catch(() => null) : Promise.resolve(null))
+ .finally(() => clearTimeout(expiry));
return async budgetMs => {
let timer: ReturnType<typeof setTimeout> | undefined;
const owners = await Promise.race([read, new Promise<null>(resolve => { timer = setTimeout(() => resolve(null), Math.max(0, budgetMs)); })])
.finally(() => { if (timer) clearTimeout(timer); });
if (!owners) abort.abort();
- return owners ?? new Map();
+ return owners;
};
}
diff --git a/src/core/persistence/service.ts b/src/core/persistence/service.ts
index 6de4c39b21..c456e90090 100644
--- a/src/core/persistence/service.ts
+++ b/src/core/persistence/service.ts
@@ -251,13 +251,14 @@ export async function awaitWrite(engine: BrainEngine, row: WriteRequest, config:
let deadline = started + waitMs;
const firstPoll = recentlySettled.get(engine)?.has(id) ? 0 : Math.min(WRITE_POLL_START_MS, waitMs / 2);
let delay = firstPoll, failure: { error: unknown; attempts: number } | undefined;
- // GBRA-248: owner facts for a write that may be left pending, read during the wait's last OWNER_READ_BUDGET_MS so they never extend it.
- let settleOwner: ((budgetMs: number) => Promise<Map<string, OwnerActivity>>) | undefined, ownerReadAt = 0;
+ // GBRA-248: owner facts for a write that may be left pending or blocked, read during the wait's last OWNER_READ_BUDGET_MS (a
+ // shorter wait is extended to that budget); waiters on one worktree share the read and reuse its answer (sharedOwnerRead).
+ let ownerRead: SharedOwnerRead | undefined;
try {
while (!service.stopping && !opts.signal?.aborted) {
if (handed) { row = handed; handed = undefined; if (isTerminal(row)) return { kind: 'terminal', row }; }
const remaining = deadline - performance.now();
- if (!settleOwner && row.worktree_id && remaining <= OWNER_READ_BUDGET_MS) { settleOwner = startOwnerRead(engine, [row.worktree_id]); ownerReadAt = performance.now(); }
+ if (!ownerRead && row.worktree_id && remaining <= OWNER_READ_BUDGET_MS) ownerRead = sharedOwnerRead(engine, row.worktree_id);
if (remaining <= 0) {
if (opts.whileHeldMs && opts.whileHeldMs > waitMs && deadline === started + waitMs
&& (consumer.holds(id) || row.state === 'queued' && !row.blocked_reason)) { deadline = started + opts.whileHeldMs; continue; }
@@ -316,16 +317,13 @@ export async function awaitWrite(engine: BrainEngine, row: WriteRequest, config:
return { kind: 'read_failed', row, request_id: row.request_id, reason: diagnosis.reason, transient: diagnosis.transient,
...(diagnosis.sqlstate ? { sqlstate: diagnosis.sqlstate } : {}), attempts: failure.attempts, message: diagnosis.message, why: diagnosis.remediation };
}
- const cause = BLOCKED_WRITE_REASONS.find(reason => reason === row.blocked_reason);
- if (cause) return { kind: 'blocked', row, request_id: row.request_id, cause, command: `gbrain sources writer status ${row.source_id} --json` };
- // GBRA-248: a write left pending names a stale owner, so the receipt (and --accept-pending) can tell it from a slow commit.
- // The read always gets OWNER_READ_BUDGET_MS from its start: a wait shorter than that (wait 0) is extended by the difference, never more.
+ // GBRA-248: a write left pending or blocked names a stale owner, so the receipt (and --accept-pending) can tell it from a slow commit.
if (row.worktree_id) {
- if (!settleOwner) { settleOwner = startOwnerRead(engine, [row.worktree_id]); ownerReadAt = performance.now(); }
- const owners = await settleOwner(Math.max(deadline, ownerReadAt + OWNER_READ_BUDGET_MS) - performance.now());
- const owner = owners.get(row.worktree_id);
+ const owner = await (ownerRead ?? sharedOwnerRead(engine, row.worktree_id)).answer();
if (owner) observedOwners.set(row, owner);
}
+ const cause = BLOCKED_WRITE_REASONS.find(reason => reason === row.blocked_reason);
+ if (cause) return { kind: 'blocked', row, request_id: row.request_id, cause, command: `gbrain sources writer status ${row.source_id} --json` };
return { kind: 'pending', row };
}
/** At most four progress reads per engine; concurrent waiters on one request share a read. */
@@ -371,6 +369,25 @@ function terminalReceiptHint(row: WriteRequest, reason: string): string {
}
/** GBRA-248: owner facts awaitWrite observed for a row it left pending (by identity; the row object travels to writeResponse unchanged). */
const observedOwners = new WeakMap<WriteRequest, OwnerActivity>();
+/** GBRA-248: staleness moves on a 24 h scale, so an owner answer is reused for a few seconds and a batch of waiters pays one read. */
+const OWNER_CACHE_MS = 10_000;
+interface SharedOwnerRead { at: number; answer(): Promise<OwnerActivity | undefined> }
+const ownerReads = new WeakMap<BrainEngine, Map<string, SharedOwnerRead>>();
+/** One owner read per engine and worktree at a time; it answers within OWNER_READ_BUDGET_MS of its start (undefined: no stale-owner facts). */
+function sharedOwnerRead(engine: BrainEngine, worktreeId: string): SharedOwnerRead {
+ let reads = ownerReads.get(engine);
+ if (!reads) { reads = new Map(); ownerReads.set(engine, reads); }
+ const current = reads.get(worktreeId);
+ if (current && performance.now() - current.at < OWNER_CACHE_MS) return current;
+ const at = performance.now();
+ const settled = startOwnerRead(engine, [worktreeId])(OWNER_READ_BUDGET_MS).then(owners => {
+ if (!owners && reads!.get(worktreeId) === read) reads!.delete(worktreeId);
+ return owners?.get(worktreeId);
+ });
+ const read: SharedOwnerRead = { at, answer: () => settled };
+ reads.set(worktreeId, read);
+ return read;
+}
export function writeResponse(row: WriteRequest, hints: { retryAfterMs?: number | null; waiterOnlyOwner?: ElectedOwner | null } = {}): Record<string, unknown> {
const owner = isTerminal(row) ? undefined : observedOwners.get(row);
const receipt = receiptFor(row, owner ? { owner } : undefined);
diff --git a/test/init-cold-home-embedding.test.ts b/test/init-cold-home-embedding.test.ts
index a774ce0a5c..d7fdce34cc 100644
--- a/test/init-cold-home-embedding.test.ts
+++ b/test/init-cold-home-embedding.test.ts
@@ -118,7 +118,7 @@ describe('cold-home re-init over an embedded PGLite brain', () => {
});
describe('keptEmbeddingIdentity', () => {
- test('keeps an agreeing identity only over vectors, and neither disables nor guesses when it cannot be confirmed', async () => {
+ test('keeps an agreeing identity only over vectors, and keeps nothing (so init disables as before) when it cannot be confirmed', async () => {
const engine = new PGLiteEngine();
await engine.connect({}); await engine.initSchema();
try {
@@ -130,12 +130,12 @@ describe('keptEmbeddingIdentity', () => {
expect(await keptEmbeddingIdentity(engine, { noEmbedding: true } as never, false)).toBeNull();
expect(await keptEmbeddingIdentity(engine, implicit, true)).toBeNull();
expect(await keptEmbeddingIdentity(engine, implicit, false)).toEqual({ model: stored.model!, dimensions: stored.dimensions });
+ expect(keptEmbeddingNotice({ model: stored.model!, dimensions: stored.dimensions })).toContain(`kept this database's ${stored.model} (${stored.dimensions}d)`);
await engine.setConfig('embedding_dimensions', String(stored.dimensions + 1));
- expect(await keptEmbeddingIdentity(engine, implicit, false)).toEqual({});
+ expect(await keptEmbeddingIdentity(engine, implicit, false)).toBeNull();
await engine.unsetConfig('embedding_dimensions');
await engine.unsetConfig('embedding_model');
- expect(await keptEmbeddingIdentity(engine, implicit, false)).toEqual({});
- expect(keptEmbeddingNotice({})).toContain('could not be confirmed');
+ expect(await keptEmbeddingIdentity(engine, implicit, false)).toBeNull();
await engine.setConfig('embedding_disabled', 'true');
expect(await keptEmbeddingIdentity(engine, implicit, false)).toBeNull();
} finally { await engine.disconnect(); }