Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes (receipt owner block without host id, owner read floor for short waits, test arms for unconfirmed identity and unrecorded model)

garrytan075900e334f6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 71aa2646eb..4d5f069d02 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,7 +14,7 @@ identifiers and attribution are available in the pre-removal Git revision
**A brain moved or restored under a new host identity no longer leaves writes pending forever behind an `--accept-pending` exit 0, and a keyless re-init from a cold `GBRAIN_HOME` no longer switches an embedded brain to keyword-only (GBRA-248 W0).**
-A managed source publishes only through the host that owns its checkout. When a brain moved to another machine, was restored from a backup, or ran in a container that restarted with a fresh `GBRAIN_HOME`, the new process got a new host identity, its writes queued for the old owner, and nothing said that owner was gone: the receipt read as an ordinary pending write and `--accept-pending` (or `GBRAIN_ACCEPT_PENDING=1`) exited 0, so hooks and cron treated writes that would never publish as saved. A pending receipt now names that owner (reason `owner_unavailable` with a new `diagnostic.owner` block, which older clients ignore) when it 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 another identity. `--accept-pending` does not cover such a write: `gbrain put`, `gbrain call`, brainstorm saves and `gbrain trust accept --all` exit 10 and say why. A consumer's clean stop now stamps the worktrees its host owns, so a stopped owner is not mistaken for a gone one. The owner host never sees the block, a repo-less (database-only) write never names an owner, and nothing claims or transfers ownership. New doctor check `owner_host_stale` lists the waiting writes with the owner and the read-only next step.
+A managed source publishes only through the host that owns its checkout. When a brain moved to another machine, was restored from a backup, or ran in a container that restarted with a fresh `GBRAIN_HOME`, the new process got a new host identity, its writes queued for the old owner, and nothing said that owner was gone: the receipt read as an ordinary pending write and `--accept-pending` (or `GBRAIN_ACCEPT_PENDING=1`) exited 0, so hooks and cron treated writes that would never publish as saved. A pending receipt now flags that owner (reason `owner_unavailable` with a new `diagnostic.owner` block holding its last activity, which older clients ignore; doctor names the host) when it 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 another identity. `--accept-pending` does not cover such a write: `gbrain put`, `gbrain call`, brainstorm saves and `gbrain trust accept --all` exit 10 and say why. A consumer's clean stop now stamps the worktrees its host owns, so a stopped owner is not mistaken for a gone one. The owner host never sees the block, a repo-less (database-only) write never names an owner, and nothing claims or transfers ownership. New doctor check `owner_host_stale` lists the waiting writes with the owner and the read-only next step.
`gbrain init` with no provider key in reach falls back to keyless. Run from a cold home against a database that already had an embedding model and vectors, it wrote `embedding_disabled: true` into the new config file, and the brain stopped embedding. When that fallback was implicit and the database holds vectors, init now keeps the database's stored model and width in the config file instead and prints the key to set and `gbrain embed --stale`. A fresh keyless install, a keyless brain with no vectors, an explicit `--no-embedding` and a database that already disables embeddings behave as before. New doctor check `embedding_plane_disagreement` finds brains the old behavior left in that state and prints the `gbrain init --force --embedding-model …` enable for the same model.
diff --git a/docs/architecture/key-files/core-persistence-capacity.md b/docs/architecture/key-files/core-persistence-capacity.md
index c69d542002..b09591a8f4 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` with a `diagnostic.owner` block, present only then, 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, 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.
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
index cc99de20b7..686e672cf3 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 only then, carries the owner host id and its last recorded activity (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 (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="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 408b63b4eb..825700deae 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 only then, carries the owner host id and its last recorded activity (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 (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="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/doctor/checks/owner-host-stale.ts b/src/commands/doctor/checks/owner-host-stale.ts
index c045e0ef1d..5e04ac1d0f 100644
--- a/src/commands/doctor/checks/owner-host-stale.ts
+++ b/src/commands/doctor/checks/owner-host-stale.ts
@@ -10,6 +10,7 @@
import type { Check } from '../../doctor.ts';
import type { BrainEngine } from '../../../core/engine.ts';
import { ownerActivity, OWNER_STALE_MS } from '../../../core/persistence/owner-activity.ts';
+import { PENDING_WRITE_EXIT_CODE } from '../../../core/exit-codes.ts';
import { agentFix, checkError } from '../check-fix.ts';
import { connectedEngine, type DoctorContext, type DoctorEntry } from '../context.ts';
@@ -39,7 +40,7 @@ export async function ownerHostStaleCheck(engine: BrainEngine, now = Date.now())
+ stale.slice(0, 3).map(row => `${row.source_ids.join(', ') || row.worktree_id}: owner host ${row.owner_host_id}, last active ${row.last_active ?? 'at no recorded time'}, ${row.open_writes} waiting since ${row.oldest_open}${row.foreign_file_holder ? ' (this process holds the PGLite file under a different host identity)' : ''}.`).join(' ')
+ `${stale.length > 3 ? ` (first 3 of ${stale.length} shown.)` : ''} `
+ 'These writes are kept and publish only when that host runs gbrain again. If the brain was moved or restored onto this machine, or this container restarted with a new GBRAIN_HOME, '
- + 'run gbrain with the owner\'s GBRAIN_HOME (keep it stable per container). The accept-pending opt-in does not cover these writes: they still exit 10. Never edit or delete a host.json.',
+ + 'run gbrain with the owner\'s GBRAIN_HOME (keep it stable per container). The accept-pending opt-in does not cover these writes: they still exit ' + PENDING_WRITE_EXIT_CODE + '. Never edit or delete a host.json.',
fix: agentFix(['gbrain', 'sources', 'writer', 'status', '--json'], 'Read-only: shows local_host_id, each binding\'s owner_host_id and the owner\'s consumers.', 'owner_host_stale', { docs: DOCS }) };
} catch (error) {
return checkError('owner_host_stale', 'read the owner hosts of waiting writes', error, { details: { count: 'unknown', health: 'unknown', docs: DOCS } });
diff --git a/src/core/persistence/health.ts b/src/core/persistence/health.ts
index 1025e23ff7..8d4821723d 100644
--- a/src/core/persistence/health.ts
+++ b/src/core/persistence/health.ts
@@ -27,7 +27,7 @@ export function writeHealth(row: { state: WriteRequestState; created_at: Date |
const unknown = reason === 'pending' || reason === 'cause_unknown';
if (aged && unknown) reason = 'cause_unknown';
const inspect = aged || unexpected || facts.inspect_owner || ['writer_pool_capacity', 'owner_unavailable', 'writer_lock_unavailable'].includes(reason);
- const owner = facts.owner?.stale ? { host_id: facts.owner.owner_host_id, live: false, last_active: facts.owner.last_active } : undefined;
+ const owner = facts.owner?.stale ? { last_active: facts.owner.last_active } : undefined;
return { retry_after_ms: inspect ? INSPECT_OWNER_RETRY_MS : !unknown || age >= 30_000 ? 5000 : 1000,
diagnostic: { age_ms: age, assessment: unknown ? aged ? 'stalled' : 'pending' : 'blocked', reason,
next_action: inspect ? 'inspect_owner' : 'poll', ...(facts.observed_at ? { observed_at: facts.observed_at } : {}), ...(owner ? { owner } : {}) } };
@@ -36,7 +36,7 @@ export function writeHealth(row: { state: WriteRequestState; created_at: Date |
export function pendingWriteHint(receipt: WriteReceipt, operation?: string): string {
const identity = `Use the same operation with the same arguments and request_id ${receipt.request_id}. Do not submit a new request_id for this write.`;
const owner = receipt.diagnostic?.owner
- ? ` The owner host ${receipt.diagnostic.owner.host_id} runs no consumer and was last active ${receipt.diagnostic.owner.last_active ?? 'at no recorded time'}; it may be asleep or gone, and this write publishes only when that host runs gbrain again or its ownership moves through an explicit operator step.` : '';
+ ? ` The worktree's owner host runs no consumer and was last active ${receipt.diagnostic.owner.last_active ?? 'at no recorded time'}; it may be asleep or gone, and this write publishes only when that host runs gbrain again or its ownership moves through an explicit operator step; gbrain doctor --only owner_host_stale names it.` : '';
if (receipt.diagnostic?.next_action === 'inspect_owner') return `${identity}${owner} Ask the operator to inspect gbrain sources writer status --probe --json on the selected brain's existing owner. Do not claim, transfer, activate, or remove locks. Poll no faster than ${receipt.retry_after_ms ?? 30_000} ms; if receipt helpers are unavailable, replay the same verb only after inspection.`;
const target = receipt.target?.slug ? ` Its fact goes to page ${receipt.target.slug}${receipt.target.entity_slug && receipt.target.entity_slug !== receipt.target.slug ? ` (entity ${receipt.target.entity_slug})` : ''}; get_write_request reports when it is saved there.` : '';
return `${identity}${target} Poll get_write_request after ${receipt.retry_after_ms ?? 1000} ms (with applied: true, or gbrain write-request ${receipt.request_id} --applied --json, it also says whether search can find the write yet), or retry the same verb with identical arguments if receipt helpers are unavailable.${operation === 'put_page' ? ' Next time pass wait_ms (up to 30000) so the reply waits for the commit, and write more than 3 pages with put_pages.' : ''}`;
diff --git a/src/core/persistence/journal.ts b/src/core/persistence/journal.ts
index f6708f124e..9a1c164195 100644
--- a/src/core/persistence/journal.ts
+++ b/src/core/persistence/journal.ts
@@ -1252,7 +1252,7 @@ export async function writeHealthFacts(engine: BrainEngine, rows: WriteRequest[]
const settleOwners = startOwnerRead(engine, pending.flatMap(row => row.worktree_id ? [row.worktree_id] : []));
let timer: ReturnType<typeof setTimeout> | undefined;
const facts = await Promise.race([query, new Promise<null>(resolve => {
- timer = setTimeout(() => { abort.abort(); resolve(null); }, 500);
+ 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);
if (!facts) return result;
diff --git a/src/core/persistence/params.ts b/src/core/persistence/params.ts
index 6d90a2dd22..8820d9d470 100644
--- a/src/core/persistence/params.ts
+++ b/src/core/persistence/params.ts
@@ -122,12 +122,8 @@ export const WRITE_RECEIPT_SCHEMA = {
reason: { type: 'string', enum: [...WRITE_HEALTH_REASONS] },
next_action: { type: 'string', enum: [...WRITE_HEALTH_ACTIONS] },
owner: {
- type: 'object', required: ['host_id', 'live', 'last_active'],
- properties: {
- host_id: { type: 'string' },
- live: { type: 'boolean' },
- last_active: { type: ['string', 'null'] },
- },
+ type: 'object', required: ['last_active'],
+ properties: { last_active: { type: ['string', 'null'] } },
},
},
},
diff --git a/src/core/persistence/service.ts b/src/core/persistence/service.ts
index 118a082a4b..6de4c39b21 100644
--- a/src/core/persistence/service.ts
+++ b/src/core/persistence/service.ts
@@ -252,12 +252,12 @@ export async function awaitWrite(engine: BrainEngine, row: WriteRequest, config:
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;
+ let settleOwner: ((budgetMs: number) => Promise<Map<string, OwnerActivity>>) | undefined, ownerReadAt = 0;
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]);
+ if (!settleOwner && row.worktree_id && remaining <= OWNER_READ_BUDGET_MS) { settleOwner = startOwnerRead(engine, [row.worktree_id]); ownerReadAt = performance.now(); }
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; }
@@ -319,8 +319,10 @@ export async function awaitWrite(engine: BrainEngine, row: WriteRequest, config:
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.
if (row.worktree_id) {
- const owners = await (settleOwner ?? startOwnerRead(engine, [row.worktree_id]))(Math.min(OWNER_READ_BUDGET_MS, deadline - performance.now()));
+ 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);
if (owner) observedOwners.set(row, owner);
}
diff --git a/src/core/persistence/types.ts b/src/core/persistence/types.ts
index 08231e52ef..286087eb57 100644
--- a/src/core/persistence/types.ts
+++ b/src/core/persistence/types.ts
@@ -36,8 +36,8 @@ export interface WriteDiagnostic {
assessment: typeof WRITE_HEALTH_ASSESSMENTS[number];
reason: typeof WRITE_HEALTH_REASONS[number];
next_action: typeof WRITE_HEALTH_ACTIONS[number];
- /** GBRA-248: present only when the worktree owner is stale (reason owner_unavailable): no live consumer and quiet past the stale window. Older readers ignore it. */
- owner?: { host_id: string; live: boolean; last_active: string | null };
+ /** GBRA-248: present whenever the worktree owner is stale (no live consumer, quiet past the stale window), with its last recorded activity; the reason is owner_unavailable unless recovery outranks it. No host id: receipts reach remote callers. Older readers ignore it. */
+ owner?: { last_active: string | null };
}
export interface WriteReceipt {
@@ -102,8 +102,7 @@ export function isWriteDiagnostic(value: unknown): value is WriteDiagnostic {
}
if (value.owner !== undefined) {
const owner = value.owner;
- if (!isRecord(owner) || typeof owner.host_id !== 'string' || !owner.host_id || typeof owner.live !== 'boolean'
- || (owner.last_active !== null && (typeof owner.last_active !== 'string' || !Number.isFinite(Date.parse(owner.last_active))))) return false;
+ if (!isRecord(owner) || (owner.last_active !== null && (typeof owner.last_active !== 'string' || !Number.isFinite(Date.parse(owner.last_active))))) return false;
}
return true;
}
@@ -167,8 +166,7 @@ export function publicWriteReceipt(receipt: WriteReceipt): WriteReceipt {
age_ms: receipt.diagnostic.age_ms, assessment: receipt.diagnostic.assessment,
reason: receipt.diagnostic.reason, next_action: receipt.diagnostic.next_action,
...(receipt.diagnostic.observed_at !== undefined ? { observed_at: receipt.diagnostic.observed_at } : {}),
- ...(receipt.diagnostic.owner !== undefined ? { owner: { host_id: receipt.diagnostic.owner.host_id, live: receipt.diagnostic.owner.live,
- last_active: receipt.diagnostic.owner.last_active } } : {}),
+ ...(receipt.diagnostic.owner !== undefined ? { owner: { last_active: receipt.diagnostic.owner.last_active } } : {}),
} } : {}),
};
}
diff --git a/test/doctor-embedding-plane-disagreement.test.ts b/test/doctor-embedding-plane-disagreement.test.ts
index d9ac753c1f..21a1bfa5eb 100644
--- a/test/doctor-embedding-plane-disagreement.test.ts
+++ b/test/doctor-embedding-plane-disagreement.test.ts
@@ -20,6 +20,11 @@ describe('embedding_plane_disagreement', () => {
expect(warn).toMatchObject({ status: 'warn', details: { model: stored.model, dimensions: stored.dimensions, vector_tables: ['content_chunks'] } });
expect(warn.fix).toMatchObject({ consent: ['credentials', 'paid'], actor: 'user', requires_exclusive: true,
argv: ['gbrain', 'init', '--force', '--embedding-model', stored.model!, '--embedding-dimensions', String(stored.dimensions), '--path', file.database_path] });
+ await engine.unsetConfig('embedding_model');
+ const unrecorded = await embeddingPlaneDisagreementCheck(engine, file);
+ expect(unrecorded).toMatchObject({ status: 'warn', details: { model: null, dimensions: stored.dimensions } });
+ expect(unrecorded.fix).toMatchObject({ argv: ['gbrain', 'migrate', 'embeddings', '--status', '--json'], actor: 'agent', consent: [] });
+ await engine.setConfig('embedding_model', stored.model!);
await engine.setConfig('embedding_disabled', 'true');
expect(await embeddingPlaneDisagreementCheck(engine, file)).toMatchObject({ status: 'ok', details: { database_disabled: true } });
await engine.unsetConfig('embedding_disabled');
diff --git a/test/init-cold-home-embedding.test.ts b/test/init-cold-home-embedding.test.ts
index b3b09f358a..a774ce0a5c 100644
--- a/test/init-cold-home-embedding.test.ts
+++ b/test/init-cold-home-embedding.test.ts
@@ -15,6 +15,7 @@ import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import type { BrainEngine } from '../src/core/engine.ts';
import { readStoredEmbeddingIdentity } from '../src/core/stored-embedding-identity.ts';
+import { keptEmbeddingIdentity, keptEmbeddingNotice } from '../src/commands/init-embedding-plane.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
const REPO_ROOT = join(import.meta.dir, '..');
@@ -116,6 +117,31 @@ describe('cold-home re-init over an embedded PGLite brain', () => {
}, 300_000);
});
+describe('keptEmbeddingIdentity', () => {
+ test('keeps an agreeing identity only over vectors, and neither disables nor guesses when it cannot be confirmed', async () => {
+ const engine = new PGLiteEngine();
+ await engine.connect({}); await engine.initSchema();
+ try {
+ const implicit = { noEmbedding: true, implicitKeyless: true } as never;
+ const stored = (await readStoredEmbeddingIdentity(engine))!;
+ expect(await keptEmbeddingIdentity(engine, implicit, false)).toBeNull();
+ await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
+ await embedOnePage(engine, stored.dimensions);
+ 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 });
+ await engine.setConfig('embedding_dimensions', String(stored.dimensions + 1));
+ expect(await keptEmbeddingIdentity(engine, implicit, false)).toEqual({});
+ await engine.unsetConfig('embedding_dimensions');
+ await engine.unsetConfig('embedding_model');
+ expect(await keptEmbeddingIdentity(engine, implicit, false)).toEqual({});
+ expect(keptEmbeddingNotice({})).toContain('could not be confirmed');
+ await engine.setConfig('embedding_disabled', 'true');
+ expect(await keptEmbeddingIdentity(engine, implicit, false)).toBeNull();
+ } finally { await engine.disconnect(); }
+ }, 120_000);
+});
+
describe('cold-home re-init over an embedded Postgres brain', () => {
const url = process.env.DATABASE_URL;
test.skipIf(!url)('a keyless re-init keeps the database identity', async () => {
diff --git a/test/owner-stale-moved-brain.test.ts b/test/owner-stale-moved-brain.test.ts
index e6030e6ee2..e11fa8bffb 100644
--- a/test/owner-stale-moved-brain.test.ts
+++ b/test/owner-stale-moved-brain.test.ts
@@ -78,7 +78,7 @@ describe('a moved PGLite brain and the pending-write contract', () => {
const pending = await cli(['put', 'notes/moved', '--request-id', id, '--wait', '1', '--accept-pending', '--json'], page('Moved body.'));
expect({ code: pending.code, stderr: pending.stderr }).toMatchObject({ code: PENDING_WRITE_EXIT_CODE });
const receipt = JSON.parse(pending.stdout).write_request;
- expect(receipt).toMatchObject({ request_id: id, diagnostic: { reason: 'owner_unavailable', next_action: 'inspect_owner', owner: { live: false } } });
+ expect(receipt).toMatchObject({ request_id: id, diagnostic: { reason: 'owner_unavailable', next_action: 'inspect_owner' } });
expect(Number.isFinite(Date.parse(receipt.diagnostic.owner.last_active))).toBe(true);
expect(pending.stderr).toContain('quiet past the stale window');
expect(pending.stderr).toContain('gbrain doctor --only owner_host_stale --json');
diff --git a/test/persistence-owner-activity.test.ts b/test/persistence-owner-activity.test.ts
index 63522d541d..f60cf44073 100644
--- a/test/persistence-owner-activity.test.ts
+++ b/test/persistence-owner-activity.test.ts
@@ -100,10 +100,12 @@ describe('owner activity', () => {
const rows = [(await getWriteRequestById(engine, id))!, (await getWriteRequestById(engine, dbOnly))!, (await getWriteRequestById(engine, recentId))!];
const facts = await writeHealthFacts(engine, rows);
const stale = receiptFor(rows[0]!, facts.get(id));
- expect(stale.diagnostic).toMatchObject({ reason: 'owner_unavailable', next_action: 'inspect_owner', owner: { host_id: owner, live: false } });
+ expect(stale.diagnostic).toMatchObject({ reason: 'owner_unavailable', next_action: 'inspect_owner' });
+ expect(Number.isFinite(Date.parse(stale.diagnostic!.owner!.last_active!))).toBe(true);
const wire = publicWriteReceipt(stale as never);
expect(isWriteReceipt(wire)).toBe(true);
- expect(wire.diagnostic?.owner?.host_id).toBe(owner);
+ expect(wire.diagnostic?.owner).toBeDefined();
+ expect(JSON.stringify(wire)).not.toContain(owner);
expect(acceptPendingCovers(wire)).toBe(false);
const pending = (receipt: unknown) => ({ toJSON: () => ({ error: 'write_pending', write_request: receipt }) });
expect(writeErrorExitCode(pending(wire), true)).toBe(PENDING_WRITE_EXIT_CODE);