Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix: owner_stale receipts keep --accept-pending at exit 10; keyless cold-home re-init keeps the database embedding identity (GBRA-248 W0)
garrytanc0ca6fc3ffd2
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex a1166e1e0a..25ced4ee5f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -10,6 +10,25 @@ credits are retained; no result has been reassigned to another provider. Originaidentifiers and attribution are available in the pre-removal Git revision`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).+## [Unreleased]++**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 carries the owner's liveness and last recorded activity, and names `owner_stale` 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 another identity. `--accept-pending` does not cover an `owner_stale` 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 `owner_stale`, 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 is not fresh, 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, 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.++### Itemized changes++- `src/core/persistence/owner-activity.ts` (new): owner liveness, last activity and the stale rule; `journal.ts` attaches it to receipt facts within the 500 ms budget; `health.ts`, `types.ts`, `params.ts`: the `owner_stale` reason and the optional `diagnostic.owner` receipt field.+- `src/core/persistence/service.ts`: a write left pending carries its owner facts into the receipt.+- `src/core/persistence/write-wait.ts`: `acceptPendingCovers`; `writeErrorExitCode` keeps exit 10 for `owner_stale`; `persistence-delegate.ts`, `brainstorm.ts`, `trust.ts` follow it.+- `src/core/persistence/consumer-heartbeat.ts`: a clean stop stamps `persistence_worktrees.heartbeat_at` for the host's worktrees.+- `src/commands/init-embedding-plane.ts` (new), `src/commands/init.ts`: the implicit-keyless marker and the kept database identity on both engines.+- Doctor: `owner_host_stale` (`checks/owner-host-stale.ts`) and `embedding_plane_disagreement` (`checks/embedding-plane.ts`); `core/readiness.ts` exports `enableArgv`.+- Docs: troubleshooting entries `#owner-host-stale` (with the stable `GBRAIN_HOME` guidance for servers and containers) and `#embedding-plane-disagreement`; the exit-status tables.+- Tests: `test/owner-stale-moved-brain.test.ts` (real CLI, PGLite), `test/persistence-owner-activity.test.ts` (PGLite and Postgres), `test/init-cold-home-embedding.test.ts` (PGLite and Postgres), `test/doctor-owner-host-stale.test.ts`, `test/doctor-embedding-plane-disagreement.test.ts`; doctor goldens.+## [0.60.519.0] - 2026-10-30**The unit lane now runs 28 shards instead of 22, on shard weights refreshed from the Oct 30 nightly. With the fresh weights, every one of 22 shards would be planned at 624.4 s against the 600 s per-shard budget; at 28 shards the largest is 490.6 s.**diff --git a/docs/architecture/key-files/commands-3-continued.md b/docs/architecture/key-files/commands-3-continued.mdindex b4ed46fb4d..23c3d7e1a1 100644--- a/docs/architecture/key-files/commands-3-continued.md+++ b/docs/architecture/key-files/commands-3-continued.md@@ -17,3 +17,4 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/commands/frontmatter-install-hook.ts` — `gbrain frontmatter install-hook [--source <id>] [--force] [--uninstall]`: writes the frontmatter pre-commit hook at `<git root>/.githooks/pre-commit` and sets `core.hooksPath` when unset. The root comes from `discoverGitRoot` (the same `git rev-parse --show-toplevel` walk `gbrain sync` uses, realpath'd on both sides), so a source registered as a SUBDIRECTORY of a host repo (bootstrap's `<workspace>/brain`) is accepted rather than skipped: the hook lands at the host root with `git diff --cached` limited to that subdirectory via shell-quoted git pathspecs, recorded as `# gbrain-scope: <dir>/` marker lines (one per guarded scope). The script carries `# gbrain-hook-version: N` (`FRONTMATTER_HOOK_VERSION`; no marker = version 1, which validated working-tree bytes), lists staged paths with `-z | tr '\0' '\n'`, collects them in a heredoc-fed `while IFS= read -r` loop (spaces and non-ASCII names survive; a newline inside a name is unsupported) and runs ONE `gbrain frontmatter validate --staged -- <paths>`, which checks the staged blobs under the strict producer rule and names failures as staged content. `inspectFrontmatterHook(localPath, sourceId?)` (read-only) returns the installed gbrain hook's version, `current`, and the `install-hook --force` refresh argv for doctor and post-upgrade. One hook per root — nested sources union their scopes on install and drop only their own on uninstall (the last one removes the file); a root-registered source renders the unscoped script and owns the whole hook. A foreign `.githooks/pre-commit` still needs `--force` (`.bak` saved, restored on uninstall). Both install and uninstall resolve the hook location through `hookPaths(root)`, which lstat-refuses a symlinked `.githooks/` or `pre-commit` (a committed link in a host repo would redirect the write/chmod/rm elsewhere); the CLI prints the refusal as a `skipped` line and continues with the other sources. Only a path outside any repo is otherwise skipped. Every branch that leaves a hook on disk — fresh write, `--force` overwrite, or a byte-identical refresh — reaches the wiring step, because the hook FILE travels with the repo while `core.hooksPath` is per-clone config: a fresh clone of a repo that committed the hook reports `installed` (and gets wired) rather than `unchanged` while inert; `unchanged` means current AND wired. Before wiring `core.hooksPath`, `hooksPathBlocker(root)` returns the operator-facing reason wiring is unsafe, or null: a `core.hooksPath` already set (any scope — a global/corporate value counts; `--type=path`-expanded and resolved against the root) to anywhere that does not realpath to `.githooks` (theirs to keep; git never reads `.githooks/` then — one resolving to `.githooks` counts as wired), a foreign executable under `.githooks/` (wiring would start running it — third-party clones commit hooks there) or an active hook in the repo's own hooks dir (`activeGitHooks` — executable non-`*.sample` entries under `<git rev-parse --git-common-dir>/hooks`, immune to a foreign `core.hooksPath`; wiring would make git ignore them). Every git spawn passes `env: process.env` (Bun's default child env is a startup snapshot), so `GIT_CONFIG_*` overrides reach the child. Any blocker returns `installed_unwired` — the hook is written, `core.hooksPath` stays untouched, and the CLI prints the reason + the manual `git config core.hooksPath .githooks` step. Pinned by `test/frontmatter-install-hook.test.ts`.- `src/commands/doctor/checks/outside-content-fences.ts` — `outside_content_fences` (GBRA-221, BRAIN, registered before `fence_integrity`). Lists facts (`row_num` set, active; world-visible counted apart), active takes and `links_fence` links indexed from a fence on an imported page whose body is outside-authored text (Google `email`/`meeting` pages, every GitHub-source page, pages with `transcript_import` frontmatter). Reads the derived rows, never a page body, so segmented pages are covered. Before GBRA-221 a sender could plant such rows and a re-render carries a stored fence forward; gbrain writers also add rows on purpose, so it only lists pages (location and counts, never a cell value) with an `ask_user` review fix (`gbrain get`) and removes nothing.+- `src/commands/doctor/checks/owner-host-stale.ts` + `src/commands/doctor/checks/embedding-plane.ts` — GBRA-248: doctor `owner_host_stale` (writes waiting on worktrees whose owner is stale per persistence/owner-activity.ts; fix is the read-only writer status) and `embedding_plane_disagreement` (the config file disables embeddings while the database does not and holds vectors; fix is `enableArgv` from core/readiness.ts for the stored model and width).diff --git a/docs/architecture/key-files/core-persistence-capacity.md b/docs/architecture/key-files/core-persistence-capacity.mdindex f42bbd8338..357ac02301 100644--- a/docs/architecture/key-files/core-persistence-capacity.md+++ b/docs/architecture/key-files/core-persistence-capacity.md@@ -23,3 +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 publication). `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). The journal attaches it to receipt facts within the 500 ms budget (`boundedOwnerActivity`), `writeHealth` maps it to `owner_stale` with `diagnostic.owner`, 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/architecture/key-files/providers.md b/docs/architecture/key-files/providers.mdindex e9a249c175..d61081efb8 100644--- a/docs/architecture/key-files/providers.md+++ b/docs/architecture/key-files/providers.md@@ -48,6 +48,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/core/embedding.ts` — OpenAI text-embedding-3-large, batch, retry, backoff. `BATCH_SIZE=100` (per-recipe pre-split + recursive halving + adaptive shrink-on-miss live in the gateway; the outer paginator is for progress-callback granularity, not batch protection). `estimateEmbeddingCostUsd(tokens)` prices against the currently-configured model's rate via `currentEmbeddingPricePerMTok()` (resolves the per-1M-token rate via `lookupEmbeddingPrice(gatewayGetModel())` from `embedding-pricing.ts`, falling back to the OpenAI 3-large rate 0.13 only when the gateway is unconfigured or the model is unknown to the pricing table). `EMBEDDING_COST_PER_1K_TOKENS` retained for back-compat with direct importers/tests. `currentEmbeddingSignature(): string` returns the embedding-provenance signature `<provider:model>:<dims>` (e.g. `openai:text-embedding-3-large:1536`) stamped onto `pages.embedding_signature` at every embed-write site; DELIBERATELY excludes the chunker version (tracked separately via `pages.chunker_version`) — this signature is strictly the EMBEDDING space, so a model OR dimension swap makes the stored signature differ from current and a page becomes stale. Same unconfigured-gateway fallback as the cost helpers. (See `src/core/sync-delta.ts` + `src/core/spend-posture.ts` for the cost-gate supporting modules.) `willEmbedSynchronously({v2Enabled, serialFlag, noEmbed}): SyncEmbedMode` retains the package-exported compatibility contract for downstream TypeScript and JavaScript consumers. The command-internal `resolveWorkerBackedSyncEmbedMode({deferEligible, noEmbed})` uses the engine-aware admission result, so PGLite/unknown runtimes stay inline while worker-backed Postgres preserves v2 deferral even with one runnable source; source count separately controls fan-out. `shouldBlockSync(costUsd, floorUsd, mode, posture='gated'): boolean` is the pure cost-gate decision: blocks ONLY when `mode === 'inline' && costUsd > floorUsd` — deferred mode never blocks (the backfill's $X/source/24h cap is the real money gate), and `posture === 'tokenmax'` never blocks (the operator declared cost isn't the constraint; an `off`/`unlimited` floor is `Infinity` and so is never exceeded). Pinned by `test/sync-cost-preview.test.ts` + `test/embedding-signature-stale.test.ts`. The Google embedding recipe caps each provider batch at 100; gateway splitting preserves input/vector order.- `src/core/init-embed-check.ts` — embedding-key validation at `gbrain init`. `runInitEmbedCheck(opts)` runs a config-only `diagnoseEmbedding` (catches a missing key for ANY provider) plus a best-effort `liveTestEmbed` (1-token `gateway.embed(['probe'], {inputType:'query', abortSignal})`, 5s `AbortController` timeout, never throws — catches an invalid/expired key). Loud warning to stderr; init still exits 0 (`--no-embedding` is the deferred-setup escape; `--skip-embed-check` / `GBRAIN_INIT_SKIP_EMBED_CHECK=1` skip the check). Builds the effective env (`process.env` + every file-plane provider key `buildGatewayConfig` folds — openai/anthropic/voyage/dashscope/google — from `loadConfigFileOnly()` + `opts.apiKey`) and configures the gateway via `buildGatewayConfig` before diagnose/probe, so the check sees the same keys AND provider base URLs runtime will (no false "missing key" for config.json-keyed users; the probe hits the right endpoint). Init-specific warning text names `--no-embedding` / `--skip-embed-check`, not the sync-flavored `--no-embed`. Wired into `initPGLite` + `initPostgres` in `src/commands/init.ts`, with the result added to the `--json` envelope as `embedding_check {ok, reason?, live_ok?}`. Pinned by `test/init-embed-check.test.ts` (hermetic via the gateway embed-transport seam + `withEnv`).+- `src/commands/init-embedding-plane.ts` — GBRA-248: when init fell back to keyless only because no provider key was found (`ResolvedAIOptions.implicitKeyless`) and the database is not fresh, `keptEmbeddingIdentity` keeps the database's stored model and width (or leaves embedding settings unchanged when its vectors' identity cannot be confirmed) instead of writing `embedding_disabled`, unless the database plane already disables embeddings or holds only the schema seed with no vectors; `keptEmbeddingNotice` names the provider key and `gbrain embed --stale`.- `src/core/llm-json.ts` — tolerant JSON extraction from LLM output. `parseLlmJson<T>(raw, {array?})` walks a strategy ladder (strip ```json fences → direct parse → first `{...}`/`[...]` substring; when the fenced extract fails, the same parses retry from the opening fence, or on the whole text when the fence sat inside a JSON string, so a quoted ``` cannot truncate the payload), then — only after the raw parse has failed — retries the same ladder with reasoning blocks stripped, so a payload that parses raw is untouched and a payload legitimately containing `<think>` is unaffected; returns null on any failure (adversarial throws swallowed). Exports `stripReasoningBlocks(raw)`: removes closed `<think>…</think>` pairs AND a truncated never-closed `<think>` tail (output-budget exhaustion) — reasoning models draft their JSON inside the think block, which defeats the greedy first-to-last-brace substring scan. Exports `matchingCloseBracket(text, openAt = 0)`: the index of the bracket closing the array/object that opens at `text[openAt]` (counts the opener's own kind, skips string literals whole including escapes; -1 when `text[openAt]` is not a bracket or the value never closes), which the chronicle judge, propose_takes and extract_atoms recovery paths use so a trailing `[Source: X]` citation cannot hijack the slice. `src/core/facts/extract.ts`'s hand-rolled `parseExtractorJsonDetailed` applies the same raw-first fallback ladder with the shared `stripReasoningBlocks`.diff --git a/docs/guides/exit-codes.md b/docs/guides/exit-codes.mdindex 5d92702396..7405203d07 100644--- a/docs/guides/exit-codes.md+++ b/docs/guides/exit-codes.md@@ -14,7 +14,7 @@ the exit code first, then reads the JSON document (`--json`) for the details:| 1 | failed | error envelope with `class` and `retryable` | follow `fix.next`; retry only when `retryable` is true || 2 | usage error or invalid input | error envelope (`invalid_params`, `unknown_flag`) | correct the command; `gbrain <command> --help` || 3 | `confirmation_required`: nothing ran | consent payload (`effects`, `user_message`, `fix`) | stop, relay `user_message` to the user, run `fix.command` only after they agree |-| 10 | the write was accepted and is still pending | write receipt | poll the receipt (`gbrain write-request -- <id>`); `--accept-pending` maps this to 0 |+| 10 | the write was accepted and is still pending | write receipt | poll the receipt (`gbrain write-request -- <id>`); `--accept-pending` maps this to 0, except an `owner_stale` receipt ([owner_stale](troubleshooting.md#owner-host-stale)) || 11 | partial, resumable budget stop | result with `remaining_*` and `resume_command` | run `resume_command` (it is safe to re-run) || 12 | `no_results`: `gbrain recall` (an entity, text, `--grep`, `--question` or `--query` lookup) or `gbrain entity` matched nothing. Opt-in: only with `GBRAIN_FAIL_ON_EMPTY=1`; otherwise a miss exits 0 | recall's list output: `status: "no_results"`; entity: `found: false` | treat it as a miss, not a failure; a script that filters stdout can branch on it || 13 | `pending_verify`: `gbrain bootstrap harness --token` wired a PGLite brain while no serve answered; nothing failed, nothing verified yet | the harness result with `status: "pending_verify"` and `fix` | tell the user to start `gbrain serve --http`, then run `fix.command` with the same token; `bootstrap harness --status` stays partial until it passes ([pending verify](bootstrap.md#pending-verify)) |diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.mdindex 16f137e91f..df515fdee6 100644--- a/docs/guides/troubleshooting.md+++ b/docs/guides/troubleshooting.md@@ -61,6 +61,8 @@| [Doctor warns `serve_build_drift`: serve is running an older build than this checkout](#serve-build-drift) | restart serve with the command the check prints (`systemctl --user restart gbrain-serve.service`, `launchctl kickstart -k gui/<uid>/com.gbrain.serve`, or stop the named pid and start it again), then restart each other listed worker | brain host, after the user agrees | none | `gbrain doctor --only serve_build_drift --json` is ok || [Doctor fails `runtime_build_skew`: serve, the jobs supervisor, workers and job children run different builds](#runtime-build-skew) | `gbrain upgrade --restart-only` restarts every listed process onto the installed build and verifies one build runs; it refuses with the exact step for a process it cannot restart (the check also prints the manual restart) | brain host, after the user agrees | none | `gbrain doctor --only runtime_build_skew --json` is ok || [Doctor warns `host_identity_mismatch`, or maintenance jobs report `owner_unavailable` / `host_mismatch` for weeks](#host-identity-mismatch) | set `GBRAIN_HOME` on that process's supervisor to the value the check prints (the owner's home; config appends `.gbrain` itself) and restart it; never edit or delete a `host.json` | brain host, after the user agrees | `persistent_install` when it rewrites a service definition | `gbrain doctor --only host_identity_mismatch --json` |+| [A write stays pending with `owner_stale`, `--accept-pending` exits 10, or doctor warns `owner_host_stale`](#owner-host-stale) | run gbrain with the owner's `GBRAIN_HOME` (or bring the owner host back); the waiting writes are kept | brain host, after the user agrees | none | `gbrain doctor --only owner_host_stale --json` |+| [Doctor warns `embedding_plane_disagreement`: the config file disables embeddings over a database with vectors](#embedding-plane-disagreement) | with the provider key set, run the `gbrain init --force --embedding-model …` the check prints (same model and width) | user (key), then agent | `credentials`, `paid` | `gbrain doctor --only embedding_plane_disagreement --json` || [`fence_repair` or chronicle refused `owner_unavailable`, reason `host_mismatch`](#owner-unavailable) | `gbrain sources writer status --source <id> --json` on the brain host (the owner host id); run the step there, or give the worker and the shell one `GBRAIN_HOME`. Never copy or regenerate `host.json`. Do not retry from the same host | brain host | none | `gbrain sources writer status --source <id> --json` shows this host's id as the owner || [`owner_unavailable`, reason `transfer_in_progress` or `clone_in_progress`](#owner-unavailable) | wait 30 s and retry the same step; the worktree is draining for a writer transfer or recovering from a topology clone | agent | none | `gbrain sources writer status --source <id> --json` shows state `active` || [A page write refused `owner_unavailable`, detail `unbound_source`, on a classic Postgres brain](write-refusals.md#unbound-sources-on-postgres) | don't retry; write the page as `<slug>.md` in the source's checkout, commit it, and run `gbrain sync --source <id>` (a remote agent gives those steps to the user); database-only pages or managed mode are the user's choice | agent, after the user agrees (remote: user) | none | `gbrain get <slug> --source <id>` |@@ -187,6 +189,8 @@ 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 write stays pending with reason `owner_stale`, `--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_stale` and `diagnostic.owner` 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 an `owner_stale` write 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.```text@@ -404,6 +408,8 @@ records completion and leaves every page as it was.<a id="maintenance-write-drift"></a>**Writes to the same pages keep refusing `source_changed` with `file_database_drift`, or doctor `maintenance_write_drift` warns?** Each of those pages has a canonical file that differs from its database copy, usually from an edit outside a coordinated write, so every coordinated write to it refuses and leaves a conflict receipt. Maintenance now checks the file first: `synthesize_concepts` skips a drifted concept before any model call (the phase warns and names the commands below) and other maintenance writes refuse before admission, so the pile stops growing. To list the pages, run `gbrain sources reconcile <id> --brain host --audit --conflicts` (read-only; receipts per slug, whether the file still differs, its drift class and producer; MCP `list_write_conflicts` gives remote readers the database-derived part). Then preview `gbrain repair file-drift --source <id> --all-drifted --prefer file` (add `--class <name>` when the preview reports mixed classes, narrow it with `--only '<path glob>'` / `--skip '<path glob>'` over the canonical file paths, or pick pages with `--slug`), show the user the per-page `exceptions`, and after they agree run the printed `--apply --expect <hash>` command exactly as printed. For derived pages under one directory, such as regenerated concepts: (6) preview `gbrain repair file-drift --source default --all-drifted --only 'concepts/**' --prefer database`, show the user the count and the exceptions, and after they agree run the apply command it prints, which applies exactly the previewed pages. To keep resolving such a directory with the database copy from now on, the user can declare it under `storage:` `keep_db:` in the source's gbrain.yml; the owner host's serve, jobs or autopilot consumer then reconciles drifted pages there at most 10 every 10 minutes, and doctor echoes the policy with its matched count and receipt cost ([keep_db](repair.md#file-drift-keep-db)). `--keep` is refused here: use `--prefer database` or `--prefer file`. See [file drift](repair.md#file-drift). **Say to your agent:** *"Which pages keep refusing source_changed? Preview resolving them and show me before you apply."*+<a id="embedding-plane-disagreement"></a>**Doctor warns `embedding_plane_disagreement`, or a brain that had semantic search went keyword-only after a re-setup?** The config file says `embedding_disabled: true`, but the database does not disable embeddings and already holds vectors. A re-init from a new `GBRAIN_HOME` or a restarted container with no provider key in reach used to write that flag. Init now keeps the database's model and width in that case and prints the key to set; a fresh keyless install and an explicit `--no-embedding` still write the flag. The check prints the model and width the vectors use and the enable command for exactly that model (`gbrain init --force --embedding-model <model> --embedding-dimensions <N>`, with `--path` on PGLite; effects `credentials` and `paid`). Set the provider key, run it after the user agrees, then `gbrain embed --stale` embeds pages written meanwhile. Pages and vectors are kept. When the stored model is unrecorded, the check points at `gbrain migrate embeddings --status` first. Verify with `gbrain doctor --only embedding_plane_disagreement --json`.+<a id="embedding-identity-unqualified"></a>**`facts-absorb` dies with `embedding_configuration` ("records its embedding model without a provider") while `gbrain config get embedding_model` shows a valid `provider:model`, or doctor `embedding_identity_unqualified` warns?** The brain's database `config` row `embedding_model` holds a bare model name from an older install (for example `text-embedding-3-small`), and managed fact extraction reads only that row. `gbrain config set` cannot change it. The doctor check prints the preview with the configured model filled in: run `gbrain migrate embeddings --to <provider:model> --dry-run` (read-only), show the user the cost, and only after they approve run it without `--dry-run`, with `--yes --max-cost-usd <cap>`. It re-embeds active facts even when the model is unchanged, so it is a paid step. When no model is configured outside the database, the check asks for the provider-qualified id instead. **Say to your agent:** *"Why did facts extraction stop with an embedding configuration error?"*## Embedding statediff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.mdindex a918b2cda4..191e96deb4 100644--- a/docs/guides/write-refusals.md+++ b/docs/guides/write-refusals.md@@ -140,7 +140,7 @@ a receipt can report has a row here.| `sync_cursor_replaced` | `sync_cursor_replaced` | A managed sync checkpoint found that another sync run of the same source (a rediscovery, a newer sync) replaced the cursor it belongs to, so it had nothing left to publish. The receipt is a conflict; no managed-sync failure is recorded for it, and the run that awaited it goes on with the cursor that now covers the source. | Nothing: let the current sync finish. `gbrain sync status --source <id> --json` shows that cursor. A same-run index lag keeps reporting `revision_conflict`. || <a id="revision-backfill"></a>`revision_backfill_pending` | `revision_backfill_pending` | The page was written before page revisions existed (an upgrade from below schema v150) and the resumable revision backfill has not reached it, so it has no revision to bind to. Its revision reads as `backfill_pending`, never a UUID. Nothing was written. `gbrain doctor` reports the backfill as `revision_backfill` with the pending count and any failed rows by page. | Resume the backfill on the brain host with `gbrain apply-migrations --force-schema` (it prints its progress; `--yes` alone does not resume it once the schema is current). Rows that used all three attempts are no longer retried: run `gbrain repair orphan-children` to preview orphaned child rows and torn page bodies ([orphan children](repair.md#orphan-children)). || `idempotency_conflict` | `idempotency_conflict` | The `request_id` was already used for a different target, content or protocol. | Use a new `request_id` for a different write; reuse an ID only to replay the same write. |-| <a id="write_pending"></a>`write_pending` | `write_pending` (CLI exit 10) | The write was accepted but has not committed yet. It keeps its request ID and may still commit. The CLI exits 10, not 1; a lost acknowledgment with no receipt is `submission_status: "unknown"` and exits 1. See [CLI exit status for writes](../protocol/MEMORY_VERBS_v1.md#cli-exit-status-for-writes). | Poll `gbrain call get_write_request '{"request_id":"<id>"}'`, or repeat the same command with the same `--request-id` and a longer `--wait <seconds>`. Scripts that only need the write admitted pass `--accept-pending` (or `GBRAIN_ACCEPT_PENDING=1`) to exit 0. |+| <a id="write_pending"></a>`write_pending` | `write_pending` (CLI exit 10) | The write was accepted but has not committed yet. It keeps its request ID and may still commit. The CLI exits 10, not 1; a lost acknowledgment with no receipt is `submission_status: "unknown"` and exits 1. See [CLI exit status for writes](../protocol/MEMORY_VERBS_v1.md#cli-exit-status-for-writes). | Poll `gbrain call get_write_request '{"request_id":"<id>"}'`, or repeat the same command with the same `--request-id` and a longer `--wait <seconds>`. Scripts that only need the write admitted pass `--accept-pending` (or `GBRAIN_ACCEPT_PENDING=1`) to exit 0, except for a receipt whose `diagnostic.reason` is `owner_stale`, which still exits 10 ([owner_stale](troubleshooting.md#owner-host-stale)). || <a id="invalid_write_wait"></a>`invalid_write_wait` | `invalid_write_wait` | `GBRAIN_WRITE_WAIT_MS` or `persistence.write_wait_ms` is not a whole number of milliseconds from 0 to 600000. Nothing was written. | `unset GBRAIN_WRITE_WAIT_MS` (or set it to e.g. `30000`), or `gbrain config set persistence.write_wait_ms 30000`. || <a id="edit_page"></a>`edit_no_match`, `edit_ambiguous_match`, `edit_protected_span`, `edit_invalid` | same | An `edit_page` edit matched nothing, matched more than once, touched a protected takes/facts section, or was malformed. `detail` names `edit_index` (and `match_count`). Nothing was admitted. | Re-read `get_page include_content:true`, fix the named edit and resend with a **new** request ID. See [partial page edits](../protocol/MEMORY_VERBS_v1.md#partial-page-edits-edit_page). || <a id="file_database_drift"></a>`file_database_drift` | `file_database_drift` (also the `detail` of a `source_changed` refusal) | A page's checkout file and its database copy differ, so the writer left both as they were instead of replacing one with the other (#6982). The page is held, the run reports it (`details.file_holds`, a `FACTS_FENCE_FAILED` or connector hold) and the rest of the batch continues. Nothing was overwritten. | If the file holds the newer edit, `gbrain sync --source <id>` imports it; if the database copy is newer, re-save the page with write-through on (`gbrain get <slug>`, then `gbrain put <slug>`). When both changed, ask the user which version to keep. |diff --git a/docs/protocol/MEMORY_VERBS_v1.md b/docs/protocol/MEMORY_VERBS_v1.mdindex f73810210a..3b8b645b36 100644--- a/docs/protocol/MEMORY_VERBS_v1.md+++ b/docs/protocol/MEMORY_VERBS_v1.md@@ -817,7 +817,7 @@ lock".| Exit | Meaning || --- | --- || 0 | Committed (or pending with `--accept-pending`). |-| 10 | Accepted, still pending; the receipt names the request. |+| 10 | Accepted, still pending; the receipt names the request. Also with `--accept-pending` when the receipt's `diagnostic.reason` is `owner_stale`: the owner host runs no consumer and has been quiet past the stale window, so the write will not commit on its own ([owner_stale](../guides/troubleshooting.md#owner-host-stale)). || 1 | Not committed: a terminal failure (`conflict`, `failed`, `cancelled`), a refusal before admission (for example "the persistence owner is closing", even with `--accept-pending`), or a lost response whose submission state is unknown (`submission_status: "unknown"`, no receipt). |The verdict keys on an admitted, non-terminal receipt, never on an error codediff --git a/llms-full.txt b/llms-full.txtindex 707718d6d4..2e30f73868 100644--- a/llms-full.txt+++ b/llms-full.txt@@ -9061,7 +9061,7 @@ lock".| Exit | Meaning || --- | --- || 0 | Committed (or pending with `--accept-pending`). |-| 10 | Accepted, still pending; the receipt names the request. |+| 10 | Accepted, still pending; the receipt names the request. Also with `--accept-pending` when the receipt's `diagnostic.reason` is `owner_stale`: the owner host runs no consumer and has been quiet past the stale window, so the write will not commit on its own ([owner_stale](../guides/troubleshooting.md#owner-host-stale)). || 1 | Not committed: a terminal failure (`conflict`, `failed`, `cancelled`), a refusal before admission (for example "the persistence owner is closing", even with `--accept-pending`), or a lost response whose submission state is unknown (`submission_status: "unknown"`, no receipt). |The verdict keys on an admitted, non-terminal receipt, never on an error code@@ -9952,6 +9952,8 @@ Source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/tro| [Doctor warns `serve_build_drift`: serve is running an older build than this checkout](#serve-build-drift) | restart serve with the command the check prints (`systemctl --user restart gbrain-serve.service`, `launchctl kickstart -k gui/<uid>/com.gbrain.serve`, or stop the named pid and start it again), then restart each other listed worker | brain host, after the user agrees | none | `gbrain doctor --only serve_build_drift --json` is ok || [Doctor fails `runtime_build_skew`: serve, the jobs supervisor, workers and job children run different builds](#runtime-build-skew) | `gbrain upgrade --restart-only` restarts every listed process onto the installed build and verifies one build runs; it refuses with the exact step for a process it cannot restart (the check also prints the manual restart) | brain host, after the user agrees | none | `gbrain doctor --only runtime_build_skew --json` is ok || [Doctor warns `host_identity_mismatch`, or maintenance jobs report `owner_unavailable` / `host_mismatch` for weeks](#host-identity-mismatch) | set `GBRAIN_HOME` on that process's supervisor to the value the check prints (the owner's home; config appends `.gbrain` itself) and restart it; never edit or delete a `host.json` | brain host, after the user agrees | `persistent_install` when it rewrites a service definition | `gbrain doctor --only host_identity_mismatch --json` |+| [A write stays pending with `owner_stale`, `--accept-pending` exits 10, or doctor warns `owner_host_stale`](#owner-host-stale) | run gbrain with the owner's `GBRAIN_HOME` (or bring the owner host back); the waiting writes are kept | brain host, after the user agrees | none | `gbrain doctor --only owner_host_stale --json` |+| [Doctor warns `embedding_plane_disagreement`: the config file disables embeddings over a database with vectors](#embedding-plane-disagreement) | with the provider key set, run the `gbrain init --force --embedding-model …` the check prints (same model and width) | user (key), then agent | `credentials`, `paid` | `gbrain doctor --only embedding_plane_disagreement --json` || [`fence_repair` or chronicle refused `owner_unavailable`, reason `host_mismatch`](#owner-unavailable) | `gbrain sources writer status --source <id> --json` on the brain host (the owner host id); run the step there, or give the worker and the shell one `GBRAIN_HOME`. Never copy or regenerate `host.json`. Do not retry from the same host | brain host | none | `gbrain sources writer status --source <id> --json` shows this host's id as the owner || [`owner_unavailable`, reason `transfer_in_progress` or `clone_in_progress`](#owner-unavailable) | wait 30 s and retry the same step; the worktree is draining for a writer transfer or recovering from a topology clone | agent | none | `gbrain sources writer status --source <id> --json` shows state `active` || [A page write refused `owner_unavailable`, detail `unbound_source`, on a classic Postgres brain](write-refusals.md#unbound-sources-on-postgres) | don't retry; write the page as `<slug>.md` in the source's checkout, commit it, and run `gbrain sync --source <id>` (a remote agent gives those steps to the user); database-only pages or managed mode are the user's choice | agent, after the user agrees (remote: user) | none | `gbrain get <slug> --source <id>` |@@ -10078,6 +10080,8 @@ 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 write stays pending with reason `owner_stale`, `--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_stale` and `diagnostic.owner` 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 an `owner_stale` write 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.```text@@ -10295,6 +10299,8 @@ records completion and leaves every page as it was.<a id="maintenance-write-drift"></a>**Writes to the same pages keep refusing `source_changed` with `file_database_drift`, or doctor `maintenance_write_drift` warns?** Each of those pages has a canonical file that differs from its database copy, usually from an edit outside a coordinated write, so every coordinated write to it refuses and leaves a conflict receipt. Maintenance now checks the file first: `synthesize_concepts` skips a drifted concept before any model call (the phase warns and names the commands below) and other maintenance writes refuse before admission, so the pile stops growing. To list the pages, run `gbrain sources reconcile <id> --brain host --audit --conflicts` (read-only; receipts per slug, whether the file still differs, its drift class and producer; MCP `list_write_conflicts` gives remote readers the database-derived part). Then preview `gbrain repair file-drift --source <id> --all-drifted --prefer file` (add `--class <name>` when the preview reports mixed classes, narrow it with `--only '<path glob>'` / `--skip '<path glob>'` over the canonical file paths, or pick pages with `--slug`), show the user the per-page `exceptions`, and after they agree run the printed `--apply --expect <hash>` command exactly as printed. For derived pages under one directory, such as regenerated concepts: (6) preview `gbrain repair file-drift --source default --all-drifted --only 'concepts/**' --prefer database`, show the user the count and the exceptions, and after they agree run the apply command it prints, which applies exactly the previewed pages. To keep resolving such a directory with the database copy from now on, the user can declare it under `storage:` `keep_db:` in the source's gbrain.yml; the owner host's serve, jobs or autopilot consumer then reconciles drifted pages there at most 10 every 10 minutes, and doctor echoes the policy with its matched count and receipt cost ([keep_db](repair.md#file-drift-keep-db)). `--keep` is refused here: use `--prefer database` or `--prefer file`. See [file drift](repair.md#file-drift). **Say to your agent:** *"Which pages keep refusing source_changed? Preview resolving them and show me before you apply."*+<a id="embedding-plane-disagreement"></a>**Doctor warns `embedding_plane_disagreement`, or a brain that had semantic search went keyword-only after a re-setup?** The config file says `embedding_disabled: true`, but the database does not disable embeddings and already holds vectors. A re-init from a new `GBRAIN_HOME` or a restarted container with no provider key in reach used to write that flag. Init now keeps the database's model and width in that case and prints the key to set; a fresh keyless install and an explicit `--no-embedding` still write the flag. The check prints the model and width the vectors use and the enable command for exactly that model (`gbrain init --force --embedding-model <model> --embedding-dimensions <N>`, with `--path` on PGLite; effects `credentials` and `paid`). Set the provider key, run it after the user agrees, then `gbrain embed --stale` embeds pages written meanwhile. Pages and vectors are kept. When the stored model is unrecorded, the check points at `gbrain migrate embeddings --status` first. Verify with `gbrain doctor --only embedding_plane_disagreement --json`.+<a id="embedding-identity-unqualified"></a>**`facts-absorb` dies with `embedding_configuration` ("records its embedding model without a provider") while `gbrain config get embedding_model` shows a valid `provider:model`, or doctor `embedding_identity_unqualified` warns?** The brain's database `config` row `embedding_model` holds a bare model name from an older install (for example `text-embedding-3-small`), and managed fact extraction reads only that row. `gbrain config set` cannot change it. The doctor check prints the preview with the configured model filled in: run `gbrain migrate embeddings --to <provider:model> --dry-run` (read-only), show the user the cost, and only after they approve run it without `--dry-run`, with `--yes --max-cost-usd <cap>`. It re-embeds active facts even when the model is unchanged, so it is a paid step. When no model is configured outside the database, the check asks for the provider-qualified id instead. **Say to your agent:** *"Why did facts extraction stop with an embedding configuration error?"*## Embedding state@@ -10800,7 +10806,7 @@ the exit code first, then reads the JSON document (`--json`) for the details:| 1 | failed | error envelope with `class` and `retryable` | follow `fix.next`; retry only when `retryable` is true || 2 | usage error or invalid input | error envelope (`invalid_params`, `unknown_flag`) | correct the command; `gbrain <command> --help` || 3 | `confirmation_required`: nothing ran | consent payload (`effects`, `user_message`, `fix`) | stop, relay `user_message` to the user, run `fix.command` only after they agree |-| 10 | the write was accepted and is still pending | write receipt | poll the receipt (`gbrain write-request -- <id>`); `--accept-pending` maps this to 0 |+| 10 | the write was accepted and is still pending | write receipt | poll the receipt (`gbrain write-request -- <id>`); `--accept-pending` maps this to 0, except an `owner_stale` receipt ([owner_stale](troubleshooting.md#owner-host-stale)) || 11 | partial, resumable budget stop | result with `remaining_*` and `resume_command` | run `resume_command` (it is safe to re-run) || 12 | `no_results`: `gbrain recall` (an entity, text, `--grep`, `--question` or `--query` lookup) or `gbrain entity` matched nothing. Opt-in: only with `GBRAIN_FAIL_ON_EMPTY=1`; otherwise a miss exits 0 | recall's list output: `status: "no_results"`; entity: `found: false` | treat it as a miss, not a failure; a script that filters stdout can branch on it || 13 | `pending_verify`: `gbrain bootstrap harness --token` wired a PGLite brain while no serve answered; nothing failed, nothing verified yet | the harness result with `status: "pending_verify"` and `fix` | tell the user to start `gbrain serve --http`, then run `fix.command` with the same token; `bootstrap harness --status` stays partial until it passes ([pending verify](bootstrap.md#pending-verify)) |diff --git a/scripts/module-size-limits.tsv b/scripts/module-size-limits.tsvindex d80fca694b..45cf3df01e 100644--- a/scripts/module-size-limits.tsv+++ b/scripts/module-size-limits.tsv@@ -25,7 +25,7 @@ src/core/postgres-engine.ts 3155 ratchet +1 System One v1 evals: search arms clasrc/core/search/hybrid.ts 1562 ratchet +5 GBRA-81 item 5 per-stage search timings: HybridSearchOpts._timings (interface field) and the timer bindings and import in hybridSearch/hybridSearchCached (collector logic in search/stage-timings.ts); +2 W5 page-unit ranking cut: HybridSearchOpts.pageRankCut (logic in search/page-rank-cut.ts); +9 W3 confidence-gated reranking: HybridSearchOpts.rerankGate and the gate/lookup threading through rerankAndPin and sizeReturnPool (logic in search/hybrid/rerank-gate.ts, crag.ts gradePreRerank); re-summed at the W3 merge onto master v0.60.168.0 (1641 measured); +2 System One v1: HybridSearchOpts.decide (search/decide-stage.ts); refactor wave 1 split target (W4 hybrid, cut line); ceiling rationale: docs/architecture/key-files/core-search-1.md entry for src/core/search/hybrid.ts; +10 #5691: per-request embedding_query_prefix read once and threaded to the embeds and cache key; +5 green master wave (embedding opt-out): HybridSearchOpts._embeddingOptedOut (interface field) read once per request and threaded to the cache-lookup embed and the keyword-only gate; +24 P2 explain RRF attribution stamp in rrfFusionWeighted, backlink_count stamp, explain_target stage observations, explain/explainTarget opts; +14 fix wave 13 P4.8 #6400: lazyQueryEmbedDeadline (the query-embed deadline starts when the embed starts) and the _queryEmbedDeadline getter; +1 query facts arm: HybridSearchOpts.onQueryEmbedding (interface field; its one-line call is paid inside the ceiling) after the vector arms, so the facts arm reuses the query embedding without a second model call; re-summed at the master a08578ca5 merge (1591 master lines + 3 integration lines: the onQueryEmbedding hook); lowered to 1562: LHF wave 2 item 3 peeled cosineReScore into search/cosine-rescore.tssrc/core/types.ts 2351 ratchet +4 Wave B PR 1 (1c): Page.body_storage/body_bytes (interface fields; guard logic in page-body/page-shape.ts); +8 W3 confidence-gated reranking: HybridSearchMeta.rerank_gate (RerankGateMeta in search/hybrid/rerank-gate.ts); re-summed at the W3 merge onto master v0.60.168.0 (2279 measured); +7 fix wave 11 W6.2/W6.3 (#5989, #6132): SearchOpts.hnswIterativeScan and cjkKeyword, the keyword_candidates_incomplete stage and HybridSearchMeta.keyword_candidates (logic in engine-sql/cjk-search.ts); +5 System One v1 retrieval lane: SearchResult injection_p/injection_suspected, HybridSearchMeta answerability, egress_denied degraded reason; +4 System One v1: SearchResult rerank_score_kind/decide_evidence, HybridSearchMeta decide/rerank; +3 wave review: PAGE_SORT_SQL.updated_asc source_id + id tiebreakers (total order under federated scopes); +5 #4881: OntologyReadOpts extends PageReadScope doc; +3 #4857: PAGE_SORT_SQL.slug total-order tiebreaker comment; grown v0.46.26.0 megawave: EvidenceOpts, pacing/usage result fields, PageFilters growth (#4352 #4218); wave-k: +9 SalienceOpts/AnomaliesOpts source scope (#3867); +20 2026-09 adversarial batch 2: keyword_relaxed_carried stage + relaxed_dropped meta field docs; +16 2026-09 fix wave: SearchResult.keyword_relaxed field + full fusion-demotion doc; (#3867); +9: #4648 rerank_passthrough degraded stage + empty_result_set/malformed_shape reasons | merged v0.48.1.0 true-up; +master v0.48 merge true-up (reranker succession: no_key preflight, reranker_skipped stage, readiness); corrective release: shared internal PageReadScope and PageReadPolicy; ranker wave v0.48.4.0: HybridSearchMeta relational_rerank_pin / keyword_arm_confidence / metadata_boost_gate + SearchResult.relational_pinned (+48 over master's peel); +12: #4681 Page.updated_at_iso + keyset cursor precision docs; #5105: canonical page state shared module and transaction/snapshot delegates; #5105: public page revision fields; upstream integration: preserve independently reviewed master additions with branch facade extraction; #5252 wave: typed vector pool and readiness metadata; merged company ingestion/schema routing changes; retired provider integration removed; +1 write-path wave: 'created' effective-date source; +3 read-path wave: rerank_failed degraded stage + budget reason (closed vocabularies) and its recall classification note; +8 fw3-search: SearchOpts.source_boosts + keyword_arm_failed/title_arm_failed stages; +2 wave-2 W4: ChunkInput.embedding_input_hash (#5553); fix wave 3 x fix wave 2 (v0.60.5.0) composition: +2 at the merge; evidence delivery: optional SearchResult.delivered (+2; shape in search/evidence-delivery.ts); +2 eval wave N1-3: OntologyReadOpts.visibility (remote world-only ontology reads); +4 #5827: GraphNode.source_id and GraphPath from_source_id/to_source_id; +2 #5824: SearchOpts.vectorLegacyGuard rollback switch; +7 #5154: PageFilters.listColumnsOnly (interface field); +11 Foundations 1 F1b: WriteAttributionView + AttributedPageVersion (get_versions / get_write_attribution read shapes); +1 #5988: SearchResult.stale carries the held-file detail (interface field); +6 retrieval feedback: SearchResult feedback_boost/content_hash/relational_path_edges stamps and RelationalFanoutRow.path_edges (interface fields); +2 RelationalFanoutOpts.wide (interface field); 1 GBRA-49: temporal annotation field on link rows; 1 GBRA-49: temporal annotation field on link rows; 1 GBRA-49: temporal annotation field on link rows; +44 P7 ChainHopOpts/ChainHopEdge chain-hop contract types; P7 SearchResult.relational evidence + RelationalEvidence type + relational_plan meta + planner per-call overrides; +2 P7 SearchOpts.relationalChainSlots per-call override; +1 P7 ChainHopOpts.temporal (relationship-validity policy per hop); P3 x P7 (v0.60.60.0) composition: deltas re-summed at the merge; 1 GBRA-49: temporal annotation field on link rows; +44 P7 ChainHopOpts/ChainHopEdge chain-hop contract types; P7 SearchResult.relational evidence + RelationalEvidence type + relational_plan meta + planner per-call overrides; +2 P7 SearchOpts.relationalChainSlots per-call override; +1 P7 ChainHopOpts.temporal (relationship-validity policy per hop); +1 green master wave: embedding_disabled degraded reason (closed vocabulary); +2 #5951: Chunk.source_id (get_chunks names each row's source); 1 P2 SearchResult explain fields (rrf attribution, blend_norm_rrf, score_details, backlink_count) + RrfAttribution (interface fields); +11 #5575 (L1b): PageReadScope minTrust/suppressFlagged, SearchResult trust_tier/origin/unconfirmed, TimelineOpts eligibility (interface fields cannot move); +8 #4772 (W14 PR3): BrainHealth.entity_types_status field (interface fields cannot move); +1 C4: question page type row; +6 entity anchoring: optional SearchResult.entity_anchored row stamp (logic in search/entity-anchor.ts); +4 query facts arm: optional SearchResult.fact_row and superseded_claim row fields (logic in search/facts-arm.ts); +2 query facts arm: SearchResult result_type/fact_id/page_slug/follow_up (fact rows are never page-shaped); +9 Cat 40 Hard fix wave (#6271): SearchResult matched_alias/evidence_omitted/provenance, SearchOpts.rankQuery, keyword_count_unavailable stage and rerank_failed reasons; +12 fix wave 15 P2.1 (#6500): PageFilters.slugAfter (single-source slug keyset, interface field + doc) and the updated_desc tiebreaker comment (the keyset walk lives in facts/conversation-enumeration.ts); +2 wave 16 G5.1 (#6495): EngineConfig.keyword_statement_timeout_ms (interface field + doc); +2 GBRA-92: EngineConfig.pglite_shared_buffers (interface field + doc); +11 large pages (Wave A): Chunk/ChunkInput projected_byte_start/end interface fields (span logic in chunkers/recursive.ts, page-window/document.ts); +4 wave 18b lane 2 (#6495): SearchOpts.keywordTimeoutCache, the skipped_after_timeout degraded reason and the useCache doc line; integrated at wave 18b: master 2319 + 4; +2 LHF wave 2 item 3: retrieval meta cosine_rescore field (js_fallback disclosure; logic in search/cosine-rescore.ts); +14 GBRA-154 ranking wave (#4612 #7153 #7156 #7162 #7164): SearchResult collapsed/redirect_to/image_page/rank_prior/rank_score/fused_score stamps and HybridSearchMeta.collapse (interface fields; logic in search/collapse.ts, rank-priors.ts, score-contract.ts); GBRA-151 retrieval P0 x operability wave merge: both sides grew the file, re-summed (2343 measured); GBRA-156 retrieval wave (#7201) composed with #7194 at the merge: re-summed (2345 measured); GBRA-151 #7147 follow-up re-summed at the v0.60.338.0 merge (2347 measured); +2 GBRA-95 G7a follow-up: Page.withheld_source_path field; +2 #7600: SearchResult.quoted (interface field; logic in search/transcript-quote.ts)src/core/minions/queue.ts 2547 ratchet grown #4078 + megawave probe-liveness unlatch (#4310) + master private-queue lifecycle: recovery classifier + monotonic lease; security: durable queued authority and confined filesystem dispatch; master integration: grown #4078 + megawave probe-liveness unlatch (#4310) + master private-queue lifecycle: recovery classifier + monotonic lease; harness support: boundary wiring to shared grants, isolated setup, withdrawal and delegated guards; merged v0.49: durable authority and delegated admission both enforced; typed readiness, configuration-blocked lifecycle and bounded release; +9: prune archives completed dream synthesis keys; +18 Lane D: deferJob (a deferral returns a job to delayed with no attempt counted and no stacktrace growth); the ceiling had 17 lines of slack; +5 agent operator follow-up Item 5 merged over master: claim-time spend fence token and legacy_default stamp (logic in minions/spend-authorization.ts); +5 GBRA-130 A-30: claim excludeWatchdogSuspects option (signature, doc and the mark parameter), the releaseWatchdogClaim delegate, and the co-runner stall call site in handleStalled (logic in minions/watchdog-attribution.ts); +5 GBRA-158 #7239/#7240: failJob result parameter (the #7216 hunk), jsonbSafeJson import and its call in add (sanitizer in text-safe.ts); +2 #7242 lane reservation: claim excludeNames option (doc line and the bound array; policy in minions/lanes.ts); +1 #7241 submitter label import (job-insight.ts) + 1 queue-families type import; #7252 x #7249 merge: both sides grew the file, re-summed (2544 measured); +3 GBRA-133: the stall sweep deletes a drain-lease holder record whose lease lock is gone or expired-src/commands/init.ts 1885 ratchet +2 fix wave 9 lane F #5253: leaving deferred setup also clears the DB-plane embedding_disabled row (both init branches); grown v0.46.x keyless capability notices; grown db-availability loop: initPostgresCore typed-failure extraction + --prefer-postgres ladder hook + pgvector rethrow fix; +1 at megawave/wave-k merge; +master-merge true-up; wave-k: merge; #3753 --force re-init engine-preservation guard; +1 wave-k merge-union brace (--prefer-postgres close); +10 ambient-writeback WP8: runWritebackNudge consent ask in both engine epilogues (logic lives in core/onboard/writeback-nudge.ts); +4: v0.48.2 reranker readiness at init + test seam; +1: v0.48.2 provider normalization; +3: v0.48.2 review fixes; master integration: +2: preserve typed PGLite busy errors in schema-only init; shared-skills integration on company-ingestion base; retired provider integration removed; retain stored-vector identity on re-init; -14: first-run bundle + quickstart registration helpers live in init-first-run.ts (writeback/skills asks folded into the bundle); +5 agent operator follow-up Item 2: --surface flag (value flag, parse, help line, module-level registration surface, type import) for the printed harness registration; +2 fix wave lane B3: both engine paths stamp a database init created as a fresh install for the behavior_changes notice (core/behavior-change-notice.ts); +4 GBRA-81 item 1: --search-mode value flag, its parse line, module-level choice, help line (picker logic lives in init-mode-picker.ts); +2 D8 funnel: a fresh init counts one clean_install when the opt-in funnel is on (core/funnel.ts); +1 GBRA-199: --surface help line names the default verbs listing+src/commands/init.ts 1892 ratchet +2 fix wave 9 lane F #5253: leaving deferred setup also clears the DB-plane embedding_disabled row (both init branches); grown v0.46.x keyless capability notices; grown db-availability loop: initPostgresCore typed-failure extraction + --prefer-postgres ladder hook + pgvector rethrow fix; +1 at megawave/wave-k merge; +master-merge true-up; wave-k: merge; #3753 --force re-init engine-preservation guard; +1 wave-k merge-union brace (--prefer-postgres close); +10 ambient-writeback WP8: runWritebackNudge consent ask in both engine epilogues (logic lives in core/onboard/writeback-nudge.ts); +4: v0.48.2 reranker readiness at init + test seam; +1: v0.48.2 provider normalization; +3: v0.48.2 review fixes; master integration: +2: preserve typed PGLite busy errors in schema-only init; shared-skills integration on company-ingestion base; retired provider integration removed; retain stored-vector identity on re-init; -14: first-run bundle + quickstart registration helpers live in init-first-run.ts (writeback/skills asks folded into the bundle); +5 agent operator follow-up Item 2: --surface flag (value flag, parse, help line, module-level registration surface, type import) for the printed harness registration; +2 fix wave lane B3: both engine paths stamp a database init created as a fresh install for the behavior_changes notice (core/behavior-change-notice.ts); +4 GBRA-81 item 1: --search-mode value flag, its parse line, module-level choice, help line (picker logic lives in init-mode-picker.ts); +2 D8 funnel: a fresh init counts one clean_install when the opt-in funnel is on (core/funnel.ts); +1 GBRA-199: --surface help line names the default verbs listing; +7 GBRA-248 W0b: the implicit-keyless marker on both zero-key fallbacks, the deferred-hint gate on both engine paths and the kept-identity call in both (logic in commands/init-embedding-plane.ts)src/commands/integrations.ts 1739 ratchet grown v0.46.26.0 megawave (#4039 connector compat) + 1 nosemgrep dataflow annotation (path-traversal audit); wave-k: exported heartbeatPath seam (#3900)src/core/minions/handlers/subagent.ts 1925 ratchet merged: master v131 settle rework + dream-wave C5 peel + C6 accounting + C7 lease heartbeats/lost-lease aborts + C9 oneshot dispatch + adversarial fix batches; grown by #4078 subagent-loop capability fix; +6 lines (reasoning-item replay: adaptContentBlocksToChatBlocks handles 'reasoning' blocks); +3 wave G #4514: Anthropic-via-OpenRouter allowed on the subagent loop; +36 lines (code review, same PR): isPromptTooLongError walks a bounded .cause chain so it still matches post-normalizeAIError() wrapping, plus extractPromptTooLongDetail so the dead-lettered job's error carries the matched provider detail instead of the generic normalizeAIError() wrapper text; master integration: harness support: boundary wiring to shared grants, isolated setup, withdrawal and delegated guards; #5105: +13 call-site wiring to shared tool-write-identity helper across fresh and replay dispatch; +7 fix wave 9 lane B #4921: ai.chat.per_turn_timeout_ms read once and passed to the oneshot and gateway-loop paths (resolver lives in minions/handler-timeouts.ts)src/commands/bootstrap.ts 2147 ratchet grandfathered at merge (grew past the 1500 cap on master); raised for #4066 HOME_WORKSPACE_GUARD_EXEMPT (status/uninstall/harness); +5 for the harnessDetect test seam (bulk lives in core/bootstrap/harness.ts); +23 for the contract subcommand dispatcher glue (#4105 absorb — bulk lives in core/bootstrap/contract.ts); +codex hooks-consent gate + mcp+hooks receipt registration + uninstall arm; +42 ambient-writeback WP8: interview-time SURFACE_MULTIUSER audience apply (pre-init ordering) + applyDeclaredAudienceFromInterview; +3 #4897 harness usage clause documenting --source ID semantics; +5 #5878: --refresh-skills dispatch and usage lines (logic in core/bootstrap/harness-skills.ts); +11 #5488: SUBCOMMAND_HELP harness entry (gate on --help / -h / help) — CLI help line, cannot move; +11 #4618 seat: --seat/--no-seat help lines and the runHooks parse (parse + notes live in core/bootstrap/hooks.ts parseSeatFlags); +13 #4082: runAdoptHooks (the --adopt branch of the hooks subcommand, kept out of runHooks for the function-size ratchet) and its two help lines (adoption logic lives in core/bootstrap/adopt-connection.ts + adopted-connections.ts)diff --git a/src/commands/brainstorm.ts b/src/commands/brainstorm.tsindex ad4ddaae73..2844245dbd 100644--- a/src/commands/brainstorm.ts+++ b/src/commands/brainstorm.ts@@ -31,7 +31,7 @@ import { isWriteThroughDisabled, resolvePageWriteTarget, writePageThrough, typeimport { fileDatabaseDriftToken, replaceableFile } from '../core/facts/file-body-guard.ts';import { managedPersistenceEnabled } from '../core/persistence/ownership.ts';import { submitPageMutation } from '../core/persistence/page-mutations.ts';-import { currentCliWriteWait, pendingReceiptOf, pollCommand } from '../core/persistence/write-wait.ts';+import { acceptPendingCovers, currentCliWriteWait, pendingReceiptOf, pollCommand } from '../core/persistence/write-wait.ts';import { PENDING_WRITE_EXIT_CODE } from '../core/exit-codes.ts';import { randomBytes } from 'crypto';import { legacyNestedErrorDocument } from '../core/agent-output.ts';@@ -415,7 +415,7 @@ export async function persistSavedIdea(} catch (err) {const receipt = pendingReceiptOf(err);if (receipt) return { dbSaved: false, writeThrough: { written: false }, pending: { requestId: receipt.request_id,- poll: pollCommand(receipt.request_id, (err as { fix?: { argv?: readonly string[] } }).fix), acceptPending: wait.acceptPending } };+ poll: pollCommand(receipt.request_id, (err as { fix?: { argv?: readonly string[] } }).fix), acceptPending: wait.acceptPending && acceptPendingCovers(receipt) } };return { dbSaved: false, dbError: err instanceof Error ? err.message : String(err), writeThrough: { written: false } };}let dbSaved = false;diff --git a/src/commands/doctor/checks/embedding-plane.ts b/src/commands/doctor/checks/embedding-plane.tsnew file mode 100644index 0000000000..0e2e15cc64--- /dev/null+++ b/src/commands/doctor/checks/embedding-plane.ts@@ -0,0 +1,58 @@+/**+ * GBRA-248 W0b: `embedding_plane_disagreement` warns when the config file+ * disables embeddings (`embedding_disabled: true`) while the database holds+ * vectors and does not disable them: the state a keyless re-init from a cold+ * home left before init kept the database's identity+ * (commands/init-embedding-plane.ts). Read-only; the fix is the+ * init --force enable for the database's own model and width.+ */+import type { Check } from '../../doctor.ts';+import type { BrainEngine } from '../../../core/engine.ts';+import { loadConfigFileOnly, type GBrainConfig } from '../../../core/config.ts';+import { enableArgv } from '../../../core/readiness.ts';+import { readPrimaryEmbeddingStores, readStoredEmbeddingIdentity } from '../../../core/stored-embedding-identity.ts';+import { checkError, doctorVerify } from '../check-fix.ts';+import { connectedEngine, type DoctorContext, type DoctorEntry } from '../context.ts';++const DOCS = 'docs/guides/troubleshooting.md#embedding-plane-disagreement';++export async function embeddingPlaneDisagreementCheck(engine: BrainEngine, file: GBrainConfig | null = loadConfigFileOnly()): Promise<Check> {+ try {+ if (file?.embedding_disabled !== true) return { name: 'embedding_plane_disagreement', status: 'ok', message: 'The config file does not disable embeddings.', details: { file_disabled: false, docs: DOCS } };+ if (await engine.getConfig('embedding_disabled') === 'true') return { name: 'embedding_plane_disagreement', status: 'ok', message: 'The config file and the database both disable embeddings (keyless by choice).', details: { file_disabled: true, database_disabled: true, docs: DOCS } };+ const stores: string[] = [];+ for (const table of await readPrimaryEmbeddingStores(engine)) {+ const [row] = await engine.executeRaw<{ present: boolean }>(`SELECT EXISTS (SELECT 1 FROM ${table} WHERE embedding IS NOT NULL) AS present`);+ if (row?.present) stores.push(table);+ }+ if (!stores.length) return { name: 'embedding_plane_disagreement', status: 'ok', message: 'The config file disables embeddings and the database holds no vectors.', details: { file_disabled: true, database_disabled: false, vector_tables: [], docs: DOCS } };+ const stored = await readStoredEmbeddingIdentity(engine);+ const details = { file_disabled: true, database_disabled: false, vector_tables: stores, model: stored?.model ?? null, dimensions: stored?.dimensions ?? null, docs: DOCS };+ const message = `embedding_plane_disagreement: the config file disables embeddings, but the database does not and holds vectors (${stores.join(', ')}) from ${stored?.model ?? 'an unrecorded model'}${stored ? ` (${stored.dimensions}d)` : ''}. `+ + 'A re-init without a provider key in reach (a new GBRAIN_HOME, a restarted container) wrote the flag, so new pages get no vectors and search is keyword-only. ';+ if (!stored?.model) return { name: 'embedding_plane_disagreement', status: 'warn', details,+ message: `${message}Run gbrain migrate embeddings --status to read the stored identity before turning embeddings back on.`,+ fix: { argv: ['gbrain', 'migrate', 'embeddings', '--status', '--json'], consent: [], actor: 'agent', requires_exclusive: false, verify: doctorVerify('embedding_plane_disagreement'), docs: DOCS,+ why: 'Read-only: shows the vectors\' recorded model and width, which the enable command must match.' } };+ const argv = enableArgv(file, stored.model, stored.dimensions);+ return { name: 'embedding_plane_disagreement', status: 'warn', details,+ message: `${message}With the provider key set, \`${argv.join(' ')}\` turns them back on for the same model and width; pages and vectors are kept.`,+ fix: { argv, consent: ['credentials', 'paid'], actor: 'user', requires_exclusive: true, verify: doctorVerify('embedding_plane_disagreement'), docs: DOCS,+ why: `Re-enables ${stored.model} (${stored.dimensions}d), the model the stored vectors already use, and clears embedding_disabled; pages written meanwhile are embedded by gbrain embed --stale.`,+ user_message: `Embeddings were switched off on this brain by a re-setup that could not find your provider key, although it already has vectors from ${stored.model}. With that key set, I can turn them back on (same model; embedding new pages costs a little). OK?` } };+ } catch (error) {+ return checkError('embedding_plane_disagreement', 'compare the file and database embedding settings', error, { details: { health: 'unknown', docs: DOCS } });+ }+}++async function runEmbeddingPlaneDisagreement(ctx: DoctorContext): Promise<Check[]> {+ const checks: Check[] = [];+ checks.push(await embeddingPlaneDisagreementCheck(connectedEngine(ctx)));+ return checks;+}++export const embeddingPlaneDisagreementEntry: DoctorEntry = {+ name: 'embedding_plane_disagreement',+ emits: ['embedding_plane_disagreement'],+ run: runEmbeddingPlaneDisagreement,+};diff --git a/src/commands/doctor/checks/owner-host-stale.ts b/src/commands/doctor/checks/owner-host-stale.tsnew file mode 100644index 0000000000..b8e3a5ff83--- /dev/null+++ b/src/commands/doctor/checks/owner-host-stale.ts@@ -0,0 +1,59 @@+/**+ * GBRA-248 W0a: `owner_host_stale` warns when managed writes wait on a+ * worktree whose owner host runs no consumer and has been quiet past the stale+ * window (owner-activity.ts): a brain moved or restored onto another machine,+ * or a container restarted with a fresh GBRAIN_HOME, queues writes for an+ * owner that never comes back. Read-only; never claims or transfers anything.+ * `host_identity_mismatch` (persistence-consumers.ts) is the sibling for an+ * owner whose checkout this filesystem holds.+ */+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 { agentFix, checkError } from '../check-fix.ts';+import { connectedEngine, type DoctorContext, type DoctorEntry } from '../context.ts';++const DOCS = 'docs/guides/troubleshooting.md#owner-host-stale';++export async function ownerHostStaleCheck(engine: BrainEngine, now = Date.now()): Promise<Check> {+ try {+ const [present] = await engine.executeRaw<{ managed: boolean }>(`SELECT to_regclass('public.persistence_requests') IS NOT NULL AND to_regclass('public.persistence_worktrees') IS NOT NULL AS managed`);+ if (!present?.managed) return { name: 'owner_host_stale', status: 'ok', message: 'This brain keeps no managed write journal.', details: { count: 0, stale_after_ms: OWNER_STALE_MS, stale: [], docs: DOCS } };+ const open = await engine.executeRaw<{ worktree_id: string; open_writes: number; oldest_open: string | Date; source_ids: string[] | null }>(`+ SELECT r.worktree_id::text AS worktree_id, count(*)::int AS open_writes, min(r.created_at) AS oldest_open,+ (SELECT array_agg(b.source_id ORDER BY b.source_id) FROM persistence_source_bindings b WHERE b.worktree_id=r.worktree_id) AS source_ids+ FROM persistence_requests r WHERE r.worktree_id IS NOT NULL AND r.state IN ('queued','running','recovering')+ GROUP BY r.worktree_id`);+ const owners = await ownerActivity(engine, open.map(row => row.worktree_id), now);+ const stale = open.flatMap(row => {+ const owner = owners.get(row.worktree_id);+ return owner?.stale ? [{ worktree_id: row.worktree_id, source_ids: row.source_ids ?? [], owner_host_id: owner.owner_host_id, last_active: owner.last_active,+ foreign_file_holder: owner.foreign_file_holder, open_writes: Number(row.open_writes), oldest_open: new Date(row.oldest_open).toISOString() }] : [];+ });+ const details = { count: stale.length, stale_after_ms: OWNER_STALE_MS, stale, docs: DOCS };+ if (!stale.length) return { name: 'owner_host_stale', status: 'ok', details,+ message: open.length ? `Every worktree with waiting writes has a live or recently active owner host (${open.length} checked).` : 'No managed write is waiting on an owner host.' };+ const waiting = stale.reduce((sum, row) => sum + row.open_writes, 0);+ return { name: 'owner_host_stale', status: 'warn', details,+ message: `owner_host_stale: ${waiting} write(s) wait for an owner host that runs no gbrain consumer and has been quiet for over ${OWNER_STALE_MS / 3_600_000} h. `+ + 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.',+ 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 } });+ }+}++async function runOwnerHostStale(ctx: DoctorContext): Promise<Check[]> {+ const checks: Check[] = [];+ checks.push(await ownerHostStaleCheck(connectedEngine(ctx)));+ return checks;+}++export const ownerHostStaleEntry: DoctorEntry = {+ name: 'owner_host_stale',+ emits: ['owner_host_stale'],+ run: runOwnerHostStale,+};diff --git a/src/commands/doctor/registry.ts b/src/commands/doctor/registry.tsindex bd397e15ca..6630fa6239 100644--- a/src/commands/doctor/registry.ts+++ b/src/commands/doctor/registry.ts@@ -95,6 +95,8 @@ import { legacyTokenGrantsEntry } from './checks/legacy-token-grants.ts';import { grantNewOpsEntry } from './checks/grant-new-ops.ts';import { linksExtractionLagEntry, syncFreshnessEntry, searchModeEntry } from './checks/sync-search.ts';import { persistenceConsumersEntry, serveBuildDriftEntry } from './checks/persistence-consumers.ts';+import { ownerHostStaleEntry } from './checks/owner-host-stale.ts';+import { embeddingPlaneDisagreementEntry } from './checks/embedding-plane.ts';import { runtimeBuildSkewEntry } from './checks/runtime-build-skew.ts';import { cliSocketRefusalsEntry } from './checks/cli-socket-refusals.ts';import { gitConvergenceEntry } from './checks/git-convergence.ts';@@ -304,6 +306,9 @@ export const DOCTOR_CHECK_REGISTRY: readonly DoctorEntry[] = [gitIndexLagEntry,// GBRA-221: live fence rows on imported pages whose body is outside-authored text (review only).outsideContentFencesEntry,+ // GBRA-248 W0: writes waiting on a long-quiet owner host, and a file plane that disables embeddings over a database with vectors.+ ownerHostStaleEntry,+ embeddingPlaneDisagreementEntry,fenceIntegrityEntry,searchModeEntry,];diff --git a/src/commands/init-embedding-plane.ts b/src/commands/init-embedding-plane.tsnew file mode 100644index 0000000000..3a1c9396fc--- /dev/null+++ b/src/commands/init-embedding-plane.ts@@ -0,0 +1,43 @@+/**+ * GBRA-248 W0b: a re-init that fell back to keyless only because no provider+ * key was in reach (a cold GBRAIN_HOME, a container restarted without its+ * key) must not write embedding_disabled over a content database that already+ * carries an embedding identity. It keeps the database's model and width in+ * the file plane instead and says which key to set. A fresh database, an+ * explicit --no-embedding and a database already keyless by choice behave as+ * before.+ */+import type { BrainEngine } from '../core/engine.ts';+import { readPrimaryEmbeddingStores, readStoredEmbeddingIdentity } from '../core/stored-embedding-identity.ts';+import { resolveRecipe } from '../core/ai/model-resolver.ts';+import type { ResolvedAIOptions } from './init.ts';++/** The embedding identity src/schema.sql seeds into every new config table; it names no choice anyone made. */+const SCHEMA_SEED_IDENTITY = { model: 'text-embedding-3-large', dimensions: 1536 };++/** 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 }++export async function keptEmbeddingIdentity(engine: BrainEngine, aiOpts: ResolvedAIOptions | undefined, fresh: boolean): Promise<KeptEmbedding | null> {+ if (!aiOpts?.noEmbedding || !aiOpts.implicitKeyless || fresh) return null;+ if (await engine.getConfig('embedding_disabled').catch(() => null) === 'true') return null;+ let embedded = false;+ for (const table of await readPrimaryEmbeddingStores(engine)) {+ const [row] = await engine.executeRaw<{ present: boolean }>(`SELECT EXISTS (SELECT 1 FROM ${table} WHERE embedding IS NOT NULL) AS present`);+ if (row?.present) { embedded = true; break; }+ }+ const stored = await readStoredEmbeddingIdentity(engine).catch(() => null);+ const seeded = !stored?.model || (stored.model === SCHEMA_SEED_IDENTITY.model && stored.dimensions === SCHEMA_SEED_IDENTITY.dimensions);+ if (!embedded && seeded) return 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 } : {};+}++/** 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.tsindex 9526125acc..b79c493e4f 100644--- a/src/commands/init.ts+++ b/src/commands/init.ts@@ -18,6 +18,7 @@ import type { BrainEngine } from '../core/engine.ts';import { readPrimaryEmbeddingStores, readStoredEmbeddingIdentity } from '../core/stored-embedding-identity.ts';import { deferInitJsonError, flushInitJsonResult, initJsonError, setInitJsonResult, writeDeferredInitJsonError } from './init-json.ts';import { deferredEmbeddingHint, firstRunBundle, firstRunJson, harnessRegistrationCommand } from './init-first-run.ts';+import { keptEmbeddingIdentity, keptEmbeddingNotice } from './init-embedding-plane.ts';import { writeCliNotices } from '../core/interop-notices.ts';import { exitCodeForCode } from '../core/error-catalogue.ts';import { promptLineStderr } from '../core/interaction.ts';@@ -311,6 +312,8 @@ export interface ResolvedAIOptions {chat_model?: string;/** v0.37 (D9): user opted into deferred embedding setup. */noEmbedding?: boolean;+ /** GBRA-248: noEmbedding came from the no-provider-key fallback, not a choice (init-embedding-plane.ts). */+ implicitKeyless?: boolean;}/**@@ -739,7 +742,7 @@ async function resolveEmbeddingByEnv(out: ResolvedAIOptions, nonInteractive: boo}if (!isTTY) {printKeylessContinueNotice();- out.noEmbedding = true;+ out.noEmbedding = out.implicitKeyless = true;return;}// TTY → picker (local providers like ollama may be selectable); a null@@ -748,7 +751,7 @@ async function resolveEmbeddingByEnv(out: ResolvedAIOptions, nonInteractive: booconst picked = await pickProvider({ touchpoint: 'embedding', env: effectiveEnv, isTTY: true });if (!picked) {printKeylessContinueNotice();- out.noEmbedding = true;+ out.noEmbedding = out.implicitKeyless = true;return;}out.embedding_model = picked.fullModel;@@ -1098,7 +1101,7 @@ export async function initPGLite(opts: {let resolvedModel: string | undefined;if (opts.aiOpts?.noEmbedding) {// D9 deferred-setup mode: skip preflight, no model/dim resolved.- console.log(deferredEmbeddingHint({ engine: 'pglite', database_path: dbPath, embedding_disabled: true }));+ if (!opts.aiOpts.implicitKeyless) console.log(deferredEmbeddingHint({ engine: 'pglite', database_path: dbPath, embedding_disabled: true }));} else if (opts.aiOpts?.embedding_model) {const { resolveSchemaEmbeddingDim } = await import('../core/embedding-dim-check.ts');const pre = resolveSchemaEmbeddingDim({@@ -1143,9 +1146,11 @@ export async function initPGLite(opts: {await engine.connect({ database_path: dbPath, engine: 'pglite' });const freshContentDatabase = await isNewContentDatabase(engine);await assertInitEmbeddingIdentity(engine, resolvedModel);+ const kept = await keptEmbeddingIdentity(engine, opts.aiOpts, freshContentDatabase);+ if (opts.aiOpts?.implicitKeyless) console.log(kept ? keptEmbeddingNotice(kept) : deferredEmbeddingHint({ engine: 'pglite', database_path: dbPath, embedding_disabled: true }));configureGateway({- embedding_model: resolvedModel ?? opts.aiOpts?.embedding_model,- embedding_dimensions: resolvedDim ?? opts.aiOpts?.embedding_dimensions ??+ embedding_model: resolvedModel ?? kept?.model ?? opts.aiOpts?.embedding_model,+ embedding_dimensions: resolvedDim ?? kept?.dimensions ?? opts.aiOpts?.embedding_dimensions ??(opts.aiOpts?.noEmbedding ? newInstallDims : undefined),expansion_model: opts.aiOpts?.expansion_model,chat_model: opts.aiOpts?.chat_model,@@ -1212,7 +1217,7 @@ export async function initPGLite(opts: {database_path: dbPath,...(opts.apiKey ? { openai_api_key: opts.apiKey } : {}),...(opts.aiOpts?.noEmbedding- ? { embedding_disabled: true }+ ? kept ? (kept.model ? { embedding_model: kept.model, embedding_dimensions: kept.dimensions } : {}) : { embedding_disabled: true }: (resolvedModel && resolvedDim)? { embedding_model: resolvedModel, embedding_dimensions: resolvedDim }: {}),@@ -1396,7 +1401,7 @@ export async function initPostgresCore(opts: {let resolvedDim: number | undefined;let resolvedModel: string | undefined;if (opts.aiOpts?.noEmbedding) {- console.log(deferredEmbeddingHint({ engine: 'postgres', database_url: databaseUrl, embedding_disabled: true }));+ if (!opts.aiOpts.implicitKeyless) console.log(deferredEmbeddingHint({ engine: 'postgres', database_url: databaseUrl, embedding_disabled: true }));} else if (opts.aiOpts?.embedding_model) {const { resolveSchemaEmbeddingDim } = await import('../core/embedding-dim-check.ts');const pre = resolveSchemaEmbeddingDim({@@ -1455,9 +1460,11 @@ export async function initPostgresCore(opts: {const freshContentDatabase = await isNewContentDatabase(engine);await assertInitEmbeddingIdentity(engine, resolvedModel);+ const kept = await keptEmbeddingIdentity(engine, opts.aiOpts, freshContentDatabase);+ if (opts.aiOpts?.implicitKeyless) console.log(kept ? keptEmbeddingNotice(kept) : deferredEmbeddingHint({ engine: 'postgres', database_url: databaseUrl, embedding_disabled: true }));configureGateway({- embedding_model: resolvedModel ?? opts.aiOpts?.embedding_model,- embedding_dimensions: resolvedDim ?? opts.aiOpts?.embedding_dimensions ??+ embedding_model: resolvedModel ?? kept?.model ?? opts.aiOpts?.embedding_model,+ embedding_dimensions: resolvedDim ?? kept?.dimensions ?? opts.aiOpts?.embedding_dimensions ??(opts.aiOpts?.noEmbedding ? newInstallDims : undefined),expansion_model: opts.aiOpts?.expansion_model,chat_model: opts.aiOpts?.chat_model,@@ -1555,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- ? { embedding_disabled: true }+ ? kept ? (kept.model ? { embedding_model: kept.model, embedding_dimensions: kept.dimensions } : {}) : { embedding_disabled: true }: (resolvedModel && resolvedDim)? { embedding_model: resolvedModel, embedding_dimensions: resolvedDim }: {}),diff --git a/src/commands/persistence-delegate.ts b/src/commands/persistence-delegate.tsindex 160c2b0eab..6834bbaf10 100644--- a/src/commands/persistence-delegate.ts+++ b/src/commands/persistence-delegate.ts@@ -9,7 +9,7 @@ import { PersistenceIpcTransportError } from '../core/persistence/ipc.ts';import { RemoteMcpError } from '../core/remote-mcp-error.ts';import { getCliOptions } from '../core/cli-options.ts';import { PENDING_WRITE_EXIT_CODE } from '../core/exit-codes.ts';-import { acceptPendingRequested, pendingReceiptOf, pollCommand, WRITE_EXIT_DOCS, writeErrorExitCode } from '../core/persistence/write-wait.ts';+import { acceptPendingCovers, acceptPendingRequested, pendingReceiptOf, pollCommand, WRITE_EXIT_DOCS, writeErrorExitCode } from '../core/persistence/write-wait.ts';import { cliRenderContext, toAgentError } from '../core/agent-output.ts';import { cliCommandOf } from '../cli/cli-error.ts';@@ -45,6 +45,7 @@ export async function reportPersistenceCliError(error: unknown, json = false,if (pending) {console.error(`Poll: ${poll}`);if (!acceptPending) console.error(`Exit ${PENDING_WRITE_EXIT_CODE}: accepted, not yet committed. Wait longer with --wait <seconds>, or pass --accept-pending to exit 0 (${WRITE_EXIT_DOCS}).`);+ else if (!acceptPendingCovers(pending)) console.error(`Exit ${PENDING_WRITE_EXIT_CODE}: accepted, but queued for an owner host that runs no consumer and has been quiet past the stale window (owner_stale); --accept-pending does not cover it. Run gbrain doctor --only owner_host_stale --json (${WRITE_EXIT_DOCS}).`);}setCliExitVerdict(writeErrorExitCode(error, acceptPending));return true;diff --git a/src/commands/trust.ts b/src/commands/trust.tsindex 134e7ee143..bbe65a04c6 100644--- a/src/commands/trust.ts+++ b/src/commands/trust.ts@@ -29,7 +29,7 @@ import {} from '../core/trust/review.ts';import { trustLabel } from '../core/trust/tier.ts';import { PENDING_WRITE_EXIT_CODE } from '../core/exit-codes.ts';-import { acceptPendingRequested, pendingReceiptOf, pollCommand } from '../core/persistence/write-wait.ts';+import { acceptPendingCovers, acceptPendingRequested, pendingReceiptOf, pollCommand } from '../core/persistence/write-wait.ts';import { getCliOptions } from '../core/cli-options.ts';import { cliRenderContext } from '../core/agent-output.ts';import { reportPersistenceCliError } from './persistence-delegate.ts';@@ -164,11 +164,13 @@ async function acceptAll(backend: TrustBackend, args: string[], json: boolean):await requireOwnerConfirmation(LOCAL_CTX, { ref: `${previews.length} items`, token, summary, command });const accepted: OwnerActionResult[] = [];const pending: Array<{ ref: string; request_id: string; poll: string }> = [];+ let uncovered = 0;const failed: Array<{ ref: string; error: unknown }> = [];for (let i = 0; i < inputs.length; i++) {try { accepted.push(await backend.apply(inputs[i]!, previews[i]!.binding, previews[i]!.raises)); }catch (error) {const receipt = pendingReceiptOf(error);+ if (receipt && !acceptPendingCovers(receipt)) uncovered++;if (receipt) pending.push({ ref: previews[i]!.ref, request_id: receipt.request_id,poll: pollCommand(receipt.request_id, (error as { fix?: { argv?: readonly string[] } }).fix, cliRenderContext().routing) });else failed.push({ ref: previews[i]!.ref, error: error instanceof OperationError ? error.toJSON() : String(error) });@@ -181,7 +183,7 @@ async function acceptAll(backend: TrustBackend, args: string[], json: boolean):for (const f of failed) console.log(`${f.ref}: not applied (${(f.error as { message?: string }).message ?? String(f.error)})`);}if (failed.length) setCliExitVerdict(1);- else if (pending.length && !acceptPendingRequested(getCliOptions().acceptPending)) setCliExitVerdict(PENDING_WRITE_EXIT_CODE);+ else if (pending.length && (!acceptPendingRequested(getCliOptions().acceptPending) || uncovered > 0)) setCliExitVerdict(PENDING_WRITE_EXIT_CODE);}/** Renders a refusal through the shared CLI envelope with its contract exit code (3 for consent refusals). */diff --git a/src/core/doctor-categories.ts b/src/core/doctor-categories.tsindex 47a09a31b7..a235cdd64f 100644--- a/src/core/doctor-categories.ts+++ b/src/core/doctor-categories.ts@@ -126,6 +126,8 @@ export const BRAIN_CHECK_NAMES: ReadonlySet<string> = new Set([// #5137: an env provider key shadowing a different config key.'embedding_key_source','embedding_migration_state',+ // GBRA-248 W0b: the config file disables embeddings over a database that holds vectors (doctor/checks/embedding-plane.ts).+ 'embedding_plane_disagreement','embedding_provider',// #5691: query-instruction advisory for instruction-style embedding models.'embedding_query_prefix',@@ -358,6 +360,8 @@ export const OPS_CHECK_NAMES: ReadonlySet<string> = new Set(['two_consumers_on_host','consumers_without_heartbeat','host_identity_mismatch',+ // GBRA-248 W0a: managed writes waiting on an owner host quiet past the stale window (doctor/checks/owner-host-stale.ts).+ 'owner_host_stale',// #6696 C6: a live serve or worker on an older build than this checkout (doctor/checks/persistence-consumers.ts).'serve_build_drift',// #7245: serve, the jobs supervisor, worker parents and job children on different builds (doctor/checks/runtime-build-skew.ts).diff --git a/src/core/persistence/consumer-heartbeat.ts b/src/core/persistence/consumer-heartbeat.tsindex 4341fe9c76..2954f919f1 100644--- a/src/core/persistence/consumer-heartbeat.ts+++ b/src/core/persistence/consumer-heartbeat.ts@@ -283,6 +283,10 @@ export function startConsumerHeartbeat(engine: DirectEngine, hostId: string, optclearInterval(cadence);await inFlight;const cancel = new AbortController();+ // GBRA-248: the worktrees this host owns keep the time it stopped, so owner-activity.ts can tell a stopped owner from one long gone.+ const stamp = new AbortController();+ try { await bounded(execute('UPDATE persistence_worktrees SET heartbeat_at=now() WHERE owner_host_id=$1::uuid', [hostId], stamp.signal), stamp, 1_000); }+ catch { /* best effort: owner activity falls back to publications and the last renewal */ }try { await bounded(execute('DELETE FROM persistence_consumers WHERE host_id=$1::uuid AND pid=$2::integer AND nonce=$3', [hostId, self.pid, self.nonce], cancel.signal), cancel, 1_000); }catch { /* the row lapses on its own; the next renewal on this host purges it */ }},diff --git a/src/core/persistence/health.ts b/src/core/persistence/health.tsindex 8d1f3a2d5a..390c9a7858 100644--- a/src/core/persistence/health.ts+++ b/src/core/persistence/health.ts@@ -1,4 +1,5 @@import { isTerminalWriteState, WRITE_HEALTH_REASONS, type WriteDiagnostic, type WriteReceipt, type WriteRequestState } from './types.ts';+import type { OwnerActivity } from './owner-activity.ts';export interface WriteHealthFacts {observed_at?: string;@@ -6,6 +7,8 @@ export interface WriteHealthFacts {recovery_required?: boolean;owner_unavailable?: boolean;inspect_owner?: boolean;+ /** GBRA-248: the worktree owner's liveness and last activity (owner-activity.ts). */+ owner?: OwnerActivity;}/** How long a receipt that needs an owner's inspection asks callers to wait; #6305: also how long a consumer holds a root it cannot lock. */export const INSPECT_OWNER_RETRY_MS = 30_000;@@ -18,20 +21,23 @@ export function writeHealth(row: { state: WriteRequestState; created_at: Date |const raw = row.blocked_reason;const unexpected = raw === 'unexpected_file_bytes' || raw === 'unexpected_staging_bytes';let reason: WriteDiagnostic['reason'] = unexpected || facts.inspect_owner || facts.recovery_required || row.state === 'recovering'- ? 'recovery_required' : facts.owner_unavailable ? 'owner_unavailable' : facts.earlier_write ? 'waiting_on_earlier_write'+ ? 'recovery_required' : facts.owner_unavailable ? 'owner_unavailable' : facts.owner?.stale ? 'owner_stale' : facts.earlier_write ? 'waiting_on_earlier_write': raw ? (WRITE_HEALTH_REASONS as readonly string[]).includes(raw) ? raw as WriteDiagnostic['reason'] : 'cause_unknown' : 'pending';const aged = age >= 120_000;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 inspect = aged || unexpected || facts.inspect_owner || ['writer_pool_capacity', 'owner_unavailable', 'writer_lock_unavailable', 'owner_stale'].includes(reason);+ const owner = facts.owner && !facts.owner.live ? { host_id: facts.owner.owner_host_id, live: false, 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 } : {}) } };+ next_action: inspect ? 'inspect_owner' : 'poll', ...(facts.observed_at ? { observed_at: facts.observed_at } : {}), ...(owner ? { owner } : {}) } };}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.`;- if (receipt.diagnostic?.next_action === 'inspect_owner') return `${identity} 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 owner = receipt.diagnostic?.reason === 'owner_stale' && 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.` : '';+ 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.tsindex 95e8998621..e8f3935477 100644--- a/src/core/persistence/journal.ts+++ b/src/core/persistence/journal.ts@@ -15,6 +15,7 @@ import { pipelined } from '../page-state/transactions.ts';import { backgroundPaused, backgroundWorktreeInactive, declaredBackground, readBackgroundPauseShare, resolveAdmissionOrigin, type AdmissionOrigin } from './admission-origin.ts';import { EFFECT_BYTES_SQL, RECEIPT_RESERVATION_FLOOR, receiptReservation, retainedReceiptBytes, TRUE_UP_CLAMP_SQL } from './receipt-bytes.ts';import { writeHealth, type WriteHealthFacts } from './health.ts';+import { ownerActivity, type OwnerActivity } from './owner-activity.ts';import { assertBackgroundOwner } from './owner-verification.ts';import { writerStamp } from './writer-versions.ts';import { intentCarriesContent, intentCarriesPurgedContent, PURGE_PRESENCE_COLUMNS } from './purged-intent.ts';@@ -1251,16 +1252,27 @@ export async function writeHealthFacts(engine: BrainEngine, rows: WriteRequest[]timer = setTimeout(() => { abort.abort(); resolve(null); }, 500);})]).finally(() => { if (timer) clearTimeout(timer); });if (!facts) return result;+ const owners = await boundedOwnerActivity(engine, pending.flatMap(row => row.worktree_id ? [row.worktree_id] : []));const byRoot = new Map(facts.map(fact => [fact.root, fact]));for (const row of pending) {const fact = byRoot.get(row.worktree_id ?? `db:${row.source_incarnation}`);if (!fact) continue;// #5984 Phase 4.5: a foreground write publishing beside running lane groups (claimed sync jobs) is not waiting on them.const head = row.state === 'queued' ? fact.sequence : row.worktree_id && row.operation !== 'submit_job' ? fact.started_unlaned : fact.started_sequence;+ const owner = row.worktree_id ? owners.get(row.worktree_id) : undefined;result.set(row.id, { observed_at, recovery_required: fact.recovery_required,owner_unavailable: fact.owner_unavailable,inspect_owner: fact.inspect_owner,- earlier_write: head != null && BigInt(head) < BigInt(row.sequence) });+ earlier_write: head != null && BigInt(head) < BigInt(row.sequence),+ ...(owner ? { owner } : {}) });}return result;}+/** GBRA-248: the owners of these worktrees, within the receipt read's 500 ms budget; a slow or failed read adds no owner facts. */+export async function boundedOwnerActivity(engine: BrainEngine, worktreeIds: readonly string[]): Promise<Map<string, OwnerActivity>> {+ if (!worktreeIds.length) return new Map();+ let timer: ReturnType<typeof setTimeout> | undefined;+ return Promise.race([ownerActivity(engine, worktreeIds).catch(() => new Map<string, OwnerActivity>()),+ new Promise<Map<string, OwnerActivity>>(resolve => { timer = setTimeout(() => resolve(new Map()), 500); })])+ .finally(() => { if (timer) clearTimeout(timer); });+}diff --git a/src/core/persistence/owner-activity.ts b/src/core/persistence/owner-activity.tsnew file mode 100644index 0000000000..cc651a9066--- /dev/null+++ b/src/core/persistence/owner-activity.ts@@ -0,0 +1,60 @@+/**+ * GBRA-248 W0a: when the host that owns a worktree was last active, read from+ * evidence that outlives a clean stop. A brain moved or restored onto another+ * machine (or a container with a fresh GBRAIN_HOME) queues writes for an owner+ * that never returns; receipts, doctor and --accept-pending need the facts to+ * say so instead of reading as an ordinary pending write.+ *+ * last_active is the greatest of: the owner's newest consumer heartbeat+ * (Postgres only; deleted on a clean stop), the owner's newest committed+ * publication on the worktree (durable; survives a clean stop and compaction)+ * and the worktree heartbeat (stamped at claim and on a consumer's clean stop).+ * null means no evidence at all: it reads as stale only once a write has+ * waited on the worktree past the stale window, and never as permission. The owner is never stale to itself:+ * on the owner host a pending write waits on this host's own consumer. Read-only.+ */+import type { BrainEngine } from '../engine.ts';+import { CONSUMER_LAPSED_MS } from './consumer-heartbeat.ts';+import { existingLocalHostId } from './identity.ts';++/** An owner with no live consumer and no activity for this long reads as stale. */+export const OWNER_STALE_MS = 24 * 60 * 60 * 1000;++export interface OwnerActivity {+ worktree_id: string;+ owner_host_id: string;+ /** A consumer of the owner host renewed its heartbeat within the lapse window (always false on PGLite). */+ live: boolean;+ last_active: string | null;+ /** PGLite: this process holds the database file but is not the owner host, so nothing here can publish for it. */+ foreign_file_holder: boolean;+ stale: boolean;+}++export async function ownerActivity(engine: BrainEngine, worktreeIds: readonly string[], now = Date.now()): Promise<Map<string, OwnerActivity>> {+ 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,+ 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,+ (SELECT max(c.renewed_at) FROM persistence_consumers c WHERE c.host_id=w.owner_host_id),+ (SELECT COALESCE(r.published_at, r.completed_at) FROM persistence_requests r+ WHERE r.worktree_id=w.id AND r.state='committed' ORDER BY r.sequence DESC LIMIT 1)) AS last_active,+ (SELECT min(r.created_at) FROM persistence_requests r WHERE r.worktree_id=w.id AND r.state IN ('queued','running','recovering')) AS oldest_open+ FROM persistence_worktrees w+ WHERE w.id::text = ANY($1::text[]) AND w.owner_host_id IS NOT NULL`, [ids, CONSUMER_LAPSED_MS]);+ const local = existingLocalHostId();+ for (const row of rows) {+ const lastActive = row.last_active === null ? null : new Date(row.last_active).toISOString();+ 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;+ 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) });+ }+ return result;+}diff --git a/src/core/persistence/params.ts b/src/core/persistence/params.tsindex 1be9870e13..6d90a2dd22 100644--- a/src/core/persistence/params.ts+++ b/src/core/persistence/params.ts@@ -121,6 +121,14 @@ export const WRITE_RECEIPT_SCHEMA = {assessment: { type: 'string', enum: [...WRITE_HEALTH_ASSESSMENTS] },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'] },+ },+ },},},},diff --git a/src/core/persistence/service.ts b/src/core/persistence/service.tsindex 249457062c..aba8905e9a 100644--- a/src/core/persistence/service.ts+++ b/src/core/persistence/service.ts@@ -10,7 +10,8 @@ import { claimOwnerKind, isOneShotCommand } from './claim-phase.ts';import { noteDirectPoolLease } from '../direct-pool-profile.ts';import { preparePageMutation } from './page-prepare.ts';import { prepareSemanticPageMutation } from './semantic-pages.ts';-import { getWriteRequestById, getWriteRequestProgress, receiptFor, type WriteRequestProgress } from './journal.ts';+import { boundedOwnerActivity, getWriteRequestById, getWriteRequestProgress, receiptFor, type WriteRequestProgress } from './journal.ts';+import type { OwnerActivity } from './owner-activity.ts';import { isTerminal, type WriteRequest } from './model.ts';import { isWriteErrorCode, type WriteReceipt } from './types.ts';import { registerPgliteReopen } from '../pglite-lifecycle.ts';@@ -313,7 +314,11 @@ export async function awaitWrite(engine: BrainEngine, row: WriteRequest, config:...(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);- return cause ? { kind: 'blocked', row, request_id: row.request_id, cause, command: `gbrain sources writer status ${row.source_id} --json` } : { kind: 'pending', row };+ 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 its owner when that host runs no consumer, so the receipt (and --accept-pending) can tell a stale owner from a slow commit.+ const owner = row.worktree_id ? (await boundedOwnerActivity(engine, [row.worktree_id])).get(row.worktree_id) : undefined;+ if (owner) observedOwners.set(row, owner);+ return { kind: 'pending', row };}/** At most four progress reads per engine; concurrent waiters on one request share a read. */async function readProgress(engine: BrainEngine, id: string, remaining: number): Promise<ProgressRead> {@@ -356,8 +361,11 @@ function terminalReceiptHint(row: WriteRequest, reason: string): string {? `${what} Submit again only if the change is still wanted, with a new request_id.`: `${what} Read the receipt and the current state before deciding to submit again; a new attempt needs a new request_id.`;}+/** 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>();export function writeResponse(row: WriteRequest, hints: { retryAfterMs?: number | null; waiterOnlyOwner?: ElectedOwner | null } = {}): Record<string, unknown> {- const receipt = receiptFor(row);+ const owner = isTerminal(row) ? undefined : observedOwners.get(row);+ const receipt = receiptFor(row, owner ? { owner } : undefined);// #6007: an in-process estimate beats the fixed fallback, never an owner-inspection hold.if (!isTerminal(row) && hints.retryAfterMs != null && receipt.diagnostic?.next_action !== 'inspect_owner') receipt.retry_after_ms = hints.retryAfterMs;if (row.state === 'committed') return { ...receipt, write_request: receipt };diff --git a/src/core/persistence/types.ts b/src/core/persistence/types.tsindex bb1a27aa91..be3c3f4f75 100644--- a/src/core/persistence/types.ts+++ b/src/core/persistence/types.ts@@ -27,7 +27,7 @@ export type WriteErrorCode = typeof WRITE_ERROR_CODES[number];export const WRITE_HEALTH_REASONS = ['pending', 'waiting_on_earlier_write', 'database_contention', 'writer_busy','revision_changed_repreparing', 'recovery_required', 'writer_pool_capacity', 'owner_unavailable',- 'writer_lock_unavailable', 'consumer_stopping', 'cause_unknown'] as const;+ 'writer_lock_unavailable', 'consumer_stopping', 'cause_unknown', 'owner_stale'] as const;export const WRITE_HEALTH_ASSESSMENTS = ['pending', 'blocked', 'stalled'] as const;export const WRITE_HEALTH_ACTIONS = ['poll', 'inspect_owner'] as const;export interface WriteDiagnostic {@@ -36,6 +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: the worktree owner when it runs no consumer: its host id and last recorded activity (null when none). */+ owner?: { host_id: string; live: boolean; last_active: string | null };}export interface WriteReceipt {@@ -98,6 +100,11 @@ export function isWriteDiagnostic(value: unknown): value is WriteDiagnostic {if (!utc || !Number.isFinite(Date.parse(value.observed_at))|| new Date(value.observed_at).toISOString() !== `${utc[1]}.${(utc[2] ?? '').padEnd(3, '0')}Z`) return false;}+ 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;+ }return true;}@@ -160,6 +167,8 @@ 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 } } : {}),} } : {}),};}diff --git a/src/core/persistence/write-wait.ts b/src/core/persistence/write-wait.tsindex f0e637377b..11fac114a9 100644--- a/src/core/persistence/write-wait.ts+++ b/src/core/persistence/write-wait.ts@@ -112,14 +112,25 @@ export function pendingReceiptOf(error: unknown): WriteReceipt | null {try { return admittedPendingReceipt(json.call(error)); } catch { return null; }}+/**+ * GBRA-248: `--accept-pending` covers a write that will commit on its own, not+ * one queued for an owner host that runs no consumer and has been quiet past+ * the stale window (a moved or restored brain, a replaced container home).+ */+export function acceptPendingCovers(receipt: WriteReceipt | null | undefined): boolean {+ return receipt?.diagnostic?.reason !== 'owner_stale';+}+/*** The one CLI exit verdict for a failed write (O-DX-1/O-ENG-1): an admitted- * pending receipt exits PENDING_WRITE_EXIT_CODE (0 with the opt-in); every- * other error, including a pre-admission `unavailable`, exits 1.+ * pending receipt exits PENDING_WRITE_EXIT_CODE (0 with the opt-in, unless the+ * receipt names a stale owner); every other error, including a pre-admission+ * `unavailable`, exits 1.*/export function writeErrorExitCode(error: unknown, acceptPending: boolean): number {- if (!pendingReceiptOf(error)) return 1;- return acceptPending ? 0 : PENDING_WRITE_EXIT_CODE;+ const receipt = pendingReceiptOf(error);+ if (!receipt) return 1;+ return acceptPending && acceptPendingCovers(receipt) ? 0 : PENDING_WRITE_EXIT_CODE;}/**diff --git a/src/core/readiness.ts b/src/core/readiness.tsindex e97c7f79ed..5dca7bb54b 100644--- a/src/core/readiness.ts+++ b/src/core/readiness.ts@@ -175,7 +175,7 @@ function keyInput(recipe: Recipe): ActionInput[] {}/** The datastore the enable command must target, resolved before any argv is built. */-function enableArgv(cfg: GBrainConfig, model: string, width: number): string[] {+export function enableArgv(cfg: GBrainConfig, model: string, width: number): string[] {const brainId = brainIdInMemory();if (brainId !== 'host') {return ['gbrain', 'embeddings', 'enable', '--brain', brainId, '--embedding-model', model, '--embedding-dimensions', String(width)];diff --git a/test/doctor-embedding-plane-disagreement.test.ts b/test/doctor-embedding-plane-disagreement.test.tsnew file mode 100644index 0000000000..d9ac753c1f--- /dev/null+++ b/test/doctor-embedding-plane-disagreement.test.ts@@ -0,0 +1,27 @@+/** GBRA-248: doctor embedding_plane_disagreement on PGLite: the file plane against the database's own setting and vectors. */+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+import { PGLiteEngine } from '../src/core/pglite-engine.ts';+import { embeddingPlaneDisagreementCheck } from '../src/commands/doctor/checks/embedding-plane.ts';+import { readStoredEmbeddingIdentity } from '../src/core/stored-embedding-identity.ts';++let engine: PGLiteEngine;+beforeAll(async () => { engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema(); }, 60_000);+afterAll(async () => { await engine.disconnect(); });++describe('embedding_plane_disagreement', () => {+ test('ok until the file disables embeddings over stored vectors the database does not disable', async () => {+ const file = { engine: 'pglite', database_path: '/tmp/example-brain.pglite', embedding_disabled: true } as const;+ expect(await embeddingPlaneDisagreementCheck(engine, { engine: 'pglite' })).toMatchObject({ status: 'ok', details: { file_disabled: false } });+ expect(await embeddingPlaneDisagreementCheck(engine, file)).toMatchObject({ status: 'ok', details: { vector_tables: [] } });+ const stored = (await readStoredEmbeddingIdentity(engine))!;+ await engine.putPage('notes/embedded', { type: 'note', title: 'Embedded', compiled_truth: 'A page with a vector.', timeline: '' });+ await engine.upsertChunks('notes/embedded', [{ chunk_index: 0, chunk_text: 'A page with a vector.', chunk_source: 'compiled_truth', embedding: new Float32Array(stored.dimensions).fill(0.01) }]);+ const warn = await embeddingPlaneDisagreementCheck(engine, file);+ 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.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/doctor-owner-host-stale.test.ts b/test/doctor-owner-host-stale.test.tsnew file mode 100644index 0000000000..956999bff7--- /dev/null+++ b/test/doctor-owner-host-stale.test.ts@@ -0,0 +1,50 @@+/** GBRA-248: doctor owner_host_stale on PGLite: ok with nothing waiting or an own-host owner; warn for writes queued on a foreign owner. */+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+import { randomUUID } from 'node:crypto';+import { mkdtempSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { PGLiteEngine } from '../src/core/pglite-engine.ts';+import { localHostId } from '../src/core/persistence/identity.ts';+import { ownerHostStaleCheck } from '../src/commands/doctor/checks/owner-host-stale.ts';+import { withEnv } from './helpers/with-env.ts';++const SOURCE = 'owner-host-stale-test';+let engine: PGLiteEngine;+let home: string;+const inHome = <T>(run: () => Promise<T>) => withEnv({ GBRAIN_HOME: home }, run);++beforeAll(async () => {+ home = mkdtempSync(join(tmpdir(), 'gbrain-doctor-owner-stale-'));+ engine = new PGLiteEngine();+ await engine.connect({}); await engine.initSchema();+ await engine.executeRaw('INSERT INTO sources(id,name) VALUES($1,$1)', [SOURCE]);+}, 60_000);+afterAll(async () => { await engine.disconnect(); rmSync(home, { recursive: true, force: true }); });++async function queuedOn(owner: string): Promise<string> {+ const [tree] = await engine.executeRaw<{ id: string }>("INSERT INTO persistence_worktrees(owner_host_id,heartbeat_at) VALUES($1::uuid,now()-interval '2 days') RETURNING id::text", [owner]);+ await engine.executeRaw(`INSERT INTO persistence_source_bindings(source_id,source_incarnation,worktree_id) VALUES($1,(SELECT incarnation FROM sources WHERE id=$1),$2::uuid)+ ON CONFLICT (source_id) DO UPDATE SET worktree_id=EXCLUDED.worktree_id`, [SOURCE, tree!.id]);+ await engine.transaction(async tx => {+ await tx.executeRaw("SELECT set_config('gbrain.persistence_protocol','2',true)");+ await tx.executeRaw(`INSERT INTO persistence_requests(principal_kind,principal_id,request_id,operation,source_id,source_incarnation,slug,digest,authority,intent_bytes,terminal_reservation,intent,worktree_id)+ VALUES('local_cli','doctor',$1::uuid,'put_page',$2,(SELECT incarnation FROM sources WHERE id=$2),'notes/x',$3,'{}'::jsonb,0,0,'{"content":"x"}'::jsonb,$4::uuid)`, [randomUUID(), SOURCE, randomUUID(), tree!.id]);+ });+ return tree!.id;+}++describe('owner_host_stale', () => {+ test('ok when nothing waits, ok for this host\'s own worktree, warn for a foreign owner', async () => inHome(async () => {+ expect(await ownerHostStaleCheck(engine)).toMatchObject({ name: 'owner_host_stale', status: 'ok', details: { count: 0 } });+ await queuedOn(localHostId());+ expect(await ownerHostStaleCheck(engine)).toMatchObject({ status: 'ok', details: { count: 0 } });+ const owner = randomUUID();+ const tree = await queuedOn(owner);+ const check = await ownerHostStaleCheck(engine);+ expect(check).toMatchObject({ status: 'warn', details: { count: 1 } });+ expect((check.details as { stale: unknown[] }).stale[0]).toMatchObject({ worktree_id: tree, owner_host_id: owner, source_ids: [SOURCE], foreign_file_holder: true, open_writes: 1 });+ expect(check.message).toContain('The accept-pending opt-in does not cover these writes');+ expect(check.fix?.argv).toEqual(['gbrain', 'sources', 'writer', 'status', '--json']);+ }));+});diff --git a/test/fixtures/goldens/doctor/json-pglite-degraded.json b/test/fixtures/goldens/doctor/json-pglite-degraded.jsonindex 119a317be6..2bbd109c4d 100644--- a/test/fixtures/goldens/doctor/json-pglite-degraded.json+++ b/test/fixtures/goldens/doctor/json-pglite-degraded.json@@ -3296,6 +3296,30 @@"name": "outside_content_fences","status": "ok"},+ {+ "category": "ops",+ "details": {+ "count": 0,+ "docs": "docs/guides/troubleshooting.md#owner-host-stale",+ "stale": [],+ "stale_after_ms": "<volatile>"+ },+ "elapsed_ms": "<volatile>",+ "message": "No managed write is waiting on an owner host.",+ "name": "owner_host_stale",+ "status": "ok"+ },+ {+ "category": "brain",+ "details": {+ "docs": "docs/guides/troubleshooting.md#embedding-plane-disagreement",+ "file_disabled": false+ },+ "elapsed_ms": "<volatile>",+ "message": "The config file does not disable embeddings.",+ "name": "embedding_plane_disagreement",+ "status": "ok"+ },{"category": "brain","details": {diff --git a/test/fixtures/goldens/doctor/json-pglite-fresh.json b/test/fixtures/goldens/doctor/json-pglite-fresh.jsonindex 1bdc34428d..fb099d2315 100644--- a/test/fixtures/goldens/doctor/json-pglite-fresh.json+++ b/test/fixtures/goldens/doctor/json-pglite-fresh.json@@ -3339,6 +3339,32 @@"name": "outside_content_fences","status": "ok"},+ {+ "category": "ops",+ "details": {+ "count": 0,+ "docs": "docs/guides/troubleshooting.md#owner-host-stale",+ "stale": [],+ "stale_after_ms": "<volatile>"+ },+ "elapsed_ms": "<volatile>",+ "message": "No managed write is waiting on an owner host.",+ "name": "owner_host_stale",+ "status": "ok"+ },+ {+ "category": "brain",+ "details": {+ "database_disabled": false,+ "docs": "docs/guides/troubleshooting.md#embedding-plane-disagreement",+ "file_disabled": true,+ "vector_tables": []+ },+ "elapsed_ms": "<volatile>",+ "message": "The config file disables embeddings and the database holds no vectors.",+ "name": "embedding_plane_disagreement",+ "status": "ok"+ },{"category": "brain","details": {diff --git a/test/fixtures/goldens/doctor/json-postgres-fresh.json b/test/fixtures/goldens/doctor/json-postgres-fresh.jsonindex 107359436b..901fa6ee32 100644--- a/test/fixtures/goldens/doctor/json-postgres-fresh.json+++ b/test/fixtures/goldens/doctor/json-postgres-fresh.json@@ -3342,6 +3342,32 @@"name": "outside_content_fences","status": "ok"},+ {+ "category": "ops",+ "details": {+ "count": 0,+ "docs": "docs/guides/troubleshooting.md#owner-host-stale",+ "stale": [],+ "stale_after_ms": "<volatile>"+ },+ "elapsed_ms": "<volatile>",+ "message": "No managed write is waiting on an owner host.",+ "name": "owner_host_stale",+ "status": "ok"+ },+ {+ "category": "brain",+ "details": {+ "database_disabled": false,+ "docs": "docs/guides/troubleshooting.md#embedding-plane-disagreement",+ "file_disabled": true,+ "vector_tables": []+ },+ "elapsed_ms": "<volatile>",+ "message": "The config file disables embeddings and the database holds no vectors.",+ "name": "embedding_plane_disagreement",+ "status": "ok"+ },{"category": "brain","details": {diff --git a/test/fixtures/goldens/doctor/registry-build-checks.json b/test/fixtures/goldens/doctor/registry-build-checks.jsonindex 8a88f77037..465e5f54cf 100644--- a/test/fixtures/goldens/doctor/registry-build-checks.json+++ b/test/fixtures/goldens/doctor/registry-build-checks.json@@ -1017,6 +1017,14 @@"category": "brain","name": "outside_content_fences"},+ {+ "category": "ops",+ "name": "owner_host_stale"+ },+ {+ "category": "brain",+ "name": "embedding_plane_disagreement"+ },{"category": "brain","name": "fence_integrity"diff --git a/test/init-cold-home-embedding.test.ts b/test/init-cold-home-embedding.test.tsnew file mode 100644index 0000000000..83a5e058a1--- /dev/null+++ b/test/init-cold-home-embedding.test.ts@@ -0,0 +1,121 @@+/**+ * GBRA-248 W0b: a re-init from a cold GBRAIN_HOME (no config.json) with no+ * provider key in reach used to write embedding_disabled over a database that+ * already holds vectors, switching an embedded brain to keyword-only. Init now+ * keeps the database's model and width in the file plane and names the key;+ * a fresh keyless install and an explicit --no-embedding are unchanged.+ * doctor's embedding_plane_disagreement names the earlier damage and the+ * enable command for the same model. PGLite (repo-less, the keyless default)+ * and Postgres; subprocess-driven with a hermetic per-run GBRAIN_HOME.+ */+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+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 { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';++const REPO_ROOT = join(import.meta.dir, '..');+const scratch: string[] = [];++async function runCli(args: string[], home: string): Promise<{ stdout: string; stderr: string; exitCode: number }> {+ const proc = Bun.spawn(['bun', 'run', join(REPO_ROOT, 'src', 'cli.ts'), ...args], {+ env: { PATH: process.env.PATH, HOME: home, GBRAIN_HOME: home, GBRAIN_NO_BANNER: '1', GBRAIN_SKIP_STARTUP_HOOKS: '1' },+ cwd: home, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe',+ });+ const watchdog = setTimeout(() => proc.kill('SIGKILL'), 150_000);+ try {+ const [stdout, stderr, exitCode] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]);+ return { stdout, stderr, exitCode };+ } finally { clearTimeout(watchdog); }+}+function coldHome(): string {+ const home = mkdtempSync(join(tmpdir(), 'gbrain-cold-home-'));+ scratch.push(home);+ return home;+}+const fileConfig = (home: string) => JSON.parse(readFileSync(join(home, '.gbrain', 'config.json'), 'utf8')) as Record<string, unknown>;+async function embedOnePage(engine: BrainEngine, dims: number): Promise<void> {+ await engine.putPage('notes/embedded', { type: 'note', title: 'Embedded', compiled_truth: 'A page with a vector.', timeline: '' });+ await engine.upsertChunks('notes/embedded', [{ chunk_index: 0, chunk_text: 'A page with a vector.', chunk_source: 'compiled_truth', embedding: new Float32Array(dims).fill(0.01) }]);+}+function doctorCheck(stdout: string): Record<string, any> {+ return (JSON.parse(stdout).checks as Array<Record<string, any>>).find(c => c.name === 'embedding_plane_disagreement')!;+}++afterAll(() => { for (const dir of scratch) rmSync(dir, { recursive: true, force: true }); });++describe('cold-home re-init over an embedded PGLite brain', () => {+ let db: string;+ beforeAll(async () => {+ const owner = coldHome();+ db = join(owner, 'brain.pglite');+ const created = await runCli(['init', '--pglite', '--path', db, '--embedding-model', 'voyage:voyage-4', '--embedding-dimensions', '1024', '--skip-embed-check'], owner);+ expect({ code: created.exitCode, stderr: created.stderr }).toMatchObject({ code: 0 });+ const engine = new PGLiteEngine();+ await engine.connect({ engine: 'pglite', database_path: db });+ try {+ // Fixture write outside the coordinator: managed persistence is paused around it and restored.+ await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');+ await embedOnePage(engine, 1024);+ await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');+ } finally { await engine.disconnect(); }+ }, 240_000);++ test('doctor names a file plane that disables embeddings over the vectors, with the same-model enable', async () => {+ const home = coldHome();+ mkdirSync(join(home, '.gbrain'));+ writeFileSync(join(home, '.gbrain', 'config.json'), JSON.stringify({ engine: 'pglite', database_path: db, embedding_disabled: true }));+ const doctor = await runCli(['doctor', '--only', 'embedding_plane_disagreement', '--json'], home);+ const check = doctorCheck(doctor.stdout);+ expect(check).toMatchObject({ status: 'warn', details: { model: 'voyage:voyage-4', dimensions: 1024, vector_tables: ['content_chunks'] } });+ expect(check.fix.argv).toEqual(['gbrain', 'init', '--force', '--embedding-model', 'voyage:voyage-4', '--embedding-dimensions', '1024', '--path', db]);+ }, 150_000);++ test('a keyless re-init from a cold home keeps the database identity instead of writing embedding_disabled', async () => {+ const home = coldHome();+ const init = await runCli(['init', '--pglite', '--path', db], home);+ expect({ code: init.exitCode, stderr: init.stderr }).toMatchObject({ code: 0 });+ const cfg = fileConfig(home);+ expect(cfg.embedding_disabled).toBeUndefined();+ expect(cfg).toMatchObject({ embedding_model: 'voyage:voyage-4', embedding_dimensions: 1024 });+ expect(init.stdout).toContain("kept this database's voyage:voyage-4 (1024d)");+ expect(init.stdout).toContain('VOYAGE_API_KEY');+ expect(init.stdout).toContain('gbrain embed --stale');+ const doctor = await runCli(['doctor', '--only', 'embedding_plane_disagreement', '--json'], home);+ expect(doctorCheck(doctor.stdout).status).toBe('ok');+ }, 150_000);++ test('a fresh keyless install and an explicit --no-embedding still write embedding_disabled', async () => {+ const fresh = coldHome();+ const first = await runCli(['init', '--pglite', '--path', join(fresh, 'new.pglite')], fresh);+ expect({ code: first.exitCode, stderr: first.stderr }).toMatchObject({ code: 0 });+ expect(fileConfig(fresh).embedding_disabled).toBe(true);+ expect(first.stdout).toContain('--no-embedding: deferred setup');+ const explicit = coldHome();+ const chosen = await runCli(['init', '--pglite', '--path', db, '--no-embedding'], explicit);+ expect({ code: chosen.exitCode, stderr: chosen.stderr }).toMatchObject({ code: 0 });+ expect(fileConfig(explicit).embedding_disabled).toBe(true);+ expect(fileConfig(explicit).embedding_model).toBeUndefined();+ }, 240_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 () => {+ const isolated = await isolatedPersistencePostgres(url!);+ try {+ const stored = (await readStoredEmbeddingIdentity(isolated.engine))!;+ await embedOnePage(isolated.engine, stored.dimensions);+ const home = coldHome();+ const init = await runCli(['init', '--url', isolated.databaseUrl, '--non-interactive'], home);+ expect({ code: init.exitCode, stderr: init.stderr }).toMatchObject({ code: 0 });+ const cfg = fileConfig(home);+ expect(cfg.embedding_disabled).toBeUndefined();+ expect(cfg).toMatchObject({ embedding_model: stored.model, embedding_dimensions: stored.dimensions });+ expect(init.stdout).toContain(`kept this database's ${stored.model} (${stored.dimensions}d)`);+ } finally { await isolated.close(); }+ }, 240_000);+});diff --git a/test/owner-stale-moved-brain.test.ts b/test/owner-stale-moved-brain.test.tsnew file mode 100644index 0000000000..80ac975ca6--- /dev/null+++ b/test/owner-stale-moved-brain.test.ts@@ -0,0 +1,97 @@+/**+ * GBRA-248 W0a against the real CLI: a PGLite brain moved or restored under a+ * new host identity (its host.json did not come along, as with a fresh+ * container GBRAIN_HOME) queues writes for the old owner, which will never+ * publish them. The receipt names owner_stale with the owner's last activity,+ * --accept-pending (flag and env) still exits 10, and doctor's+ * owner_host_stale warns. Before the move the same brain's opt-in exits 0.+ */+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+import { randomUUID } from 'node:crypto';+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { PGLiteEngine } from '../src/core/pglite-engine.ts';+import { acquireWorktree, getWorktreeBinding } from '../src/core/persistence/ownership.ts';+import { withEnv } from './helpers/with-env.ts';+import { PENDING_WRITE_EXIT_CODE } from '../src/core/exit-codes.ts';++const CLI = join(import.meta.dir, '../src/cli.ts');+let dir: string;+let config: { engine: 'pglite'; database_path: string };+const page = (body: string) => `---\ntitle: Example\ntype: note\n---\n\n${body}\n`;++async function cli(args: string[], stdin?: string, env: Record<string, string> = {}) {+ const childEnv: Record<string, string | undefined> = { ...process.env, GBRAIN_HOME: dir, GBRAIN_BRAIN_ID: 'host', GBRAIN_NO_BANNER: '1',+ GBRAIN_BACKUP_CHECK: '0', GBRAIN_WRITE_WAIT_MS: undefined, GBRAIN_ACCEPT_PENDING: undefined, ...env };+ for (const name of ['DATABASE_URL', 'GBRAIN_DATABASE_URL', 'GBRAIN_SOURCE']) delete childEnv[name];+ const child = Bun.spawn([process.execPath, CLI, ...args], { cwd: dir, env: childEnv,+ stdin: stdin === undefined ? 'ignore' : new Blob([stdin]), stdout: 'pipe', stderr: 'pipe' });+ const watchdog = setTimeout(() => child.kill('SIGKILL'), 60_000);+ try {+ const [stdout, stderr, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);+ return { stdout, stderr, code };+ } finally { clearTimeout(watchdog); }+}++beforeAll(async () => {+ dir = mkdtempSync(join(tmpdir(), 'gb-owner-stale-'));+ config = { engine: 'pglite', database_path: join(dir, 'db') };+ mkdirSync(join(dir, '.gbrain'), { recursive: true });+ mkdirSync(join(dir, 'brain'), { recursive: true });+ writeFileSync(join(dir, '.gbrain', 'config.json'), JSON.stringify(config));+ await withEnv({ GBRAIN_HOME: dir, GBRAIN_BRAIN_ID: 'host', GBRAIN_SOURCE: undefined, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined }, async () => {+ const engine = new PGLiteEngine();+ await engine.connect(config); await engine.initSchema();+ await engine.setConfig('sync.repo_path', join(dir, 'brain'));+ await engine.disconnect();+ });+});+afterAll(() => { rmSync(dir, { recursive: true, force: true }); });++describe('a moved PGLite brain and the pending-write contract', () => {+ test('on its owner a paused write is covered by --accept-pending; after the move it is owner_stale and exits 10', async () => {+ const seeded = await cli(['put', 'notes/seed', '--json'], page('Seed body.'));+ expect({ code: seeded.code, stderr: seeded.stderr }).toMatchObject({ code: 0 });++ // On the owner host: a write held behind the worktree lock is an ordinary pending write the opt-in covers.+ const heldId = randomUUID();+ await withEnv({ GBRAIN_HOME: dir, GBRAIN_BRAIN_ID: 'host' }, async () => {+ const engine = new PGLiteEngine();+ await engine.connect(config);+ const binding = await getWorktreeBinding(engine, 'default');+ await engine.disconnect();+ const lock = (await acquireWorktree(binding!))!;+ try {+ const held = await cli(['put', 'notes/held', '--request-id', heldId, '--wait', '1', '--accept-pending', '--json'], page('Held body.'));+ expect({ code: held.code, stderr: held.stderr }).toMatchObject({ code: 0 });+ expect(JSON.parse(held.stdout).write_request.diagnostic?.reason).not.toBe('owner_stale');+ } finally { await lock.release(); }+ });+ const drained = await cli(['put', 'notes/held', '--request-id', heldId, '--wait', '30', '--json'], page('Held body.'));+ expect({ code: drained.code, stderr: drained.stderr }).toMatchObject({ code: 0 });+ expect(JSON.parse(drained.stdout).state).toBe('committed');++ // The move: the brain's files arrive under a home whose host identity is new.+ rmSync(join(dir, '.gbrain', 'persistence', 'host.json'));+ const id = randomUUID();+ 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_stale', next_action: 'inspect_owner', owner: { live: false } } });+ expect(Number.isFinite(Date.parse(receipt.diagnostic.owner.last_active))).toBe(true);+ expect(pending.stderr).toContain('owner_stale');+ expect(pending.stderr).toContain('gbrain doctor --only owner_host_stale --json');++ const viaEnv = await cli(['put', 'notes/moved', '--request-id', id, '--wait', '0', '--json'], page('Moved body.'), { GBRAIN_ACCEPT_PENDING: '1' });+ expect({ code: viaEnv.code, stderr: viaEnv.stderr }).toMatchObject({ code: PENDING_WRITE_EXIT_CODE });+ const plain = await cli(['put', 'notes/moved', '--request-id', id, '--wait', '0', '--json'], page('Moved body.'));+ expect({ code: plain.code }).toMatchObject({ code: PENDING_WRITE_EXIT_CODE });++ const doctor = await cli(['doctor', '--only', 'owner_host_stale', '--json']);+ const check = (JSON.parse(doctor.stdout).checks as Array<Record<string, any>>).find(c => c.name === 'owner_host_stale')!;+ expect(check).toMatchObject({ status: 'warn', details: { count: 1 } });+ expect(check.details.stale[0]).toMatchObject({ source_ids: ['default'], foreign_file_holder: true, open_writes: 1 });+ expect(check.fix.argv.slice(0, 5)).toEqual(['gbrain', 'sources', 'writer', 'status', '--json']);+ }, 240_000);+});diff --git a/test/persistence-owner-activity.test.ts b/test/persistence-owner-activity.test.tsnew file mode 100644index 0000000000..eb3ed3c98c--- /dev/null+++ b/test/persistence-owner-activity.test.ts@@ -0,0 +1,127 @@+/**+ * GBRA-248 W0a: owner activity on both engines. A worktree whose owner host+ * runs no consumer and has been quiet past 24 h reads owner_stale in the+ * receipt, which --accept-pending does not cover; a PGLite file held under+ * another host identity is stale at once; the owner is never stale to itself;+ * a live consumer keeps its owner fresh and its clean stop leaves a durable+ * timestamp; a repo-less (database-only) write never names an owner.+ */+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+import { randomUUID } from 'node:crypto';+import { mkdtempSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { PGLiteEngine } from '../src/core/pglite-engine.ts';+import type { BrainEngine } from '../src/core/engine.ts';+import { localHostId } from '../src/core/persistence/identity.ts';+import { ownerActivity, OWNER_STALE_MS } from '../src/core/persistence/owner-activity.ts';+import { startConsumerHeartbeat } from '../src/core/persistence/consumer-heartbeat.ts';+import { getWriteRequestById, receiptFor, writeHealthFacts } from '../src/core/persistence/journal.ts';+import { isWriteReceipt, publicWriteReceipt } from '../src/core/persistence/types.ts';+import { acceptPendingCovers, writeErrorExitCode } from '../src/core/persistence/write-wait.ts';+import { PENDING_WRITE_EXIT_CODE } from '../src/core/exit-codes.ts';+import { withEnv } from './helpers/with-env.ts';+import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';++const SOURCE = 'owner-activity-test';+const engines: BrainEngine[] = [];+let closePostgres: (() => Promise<void>) | undefined;+let home: string;+let self: string;+const inHome = <T>(run: () => Promise<T>) => withEnv({ GBRAIN_HOME: home }, run);++beforeAll(async () => {+ home = mkdtempSync(join(tmpdir(), 'gbrain-owner-activity-'));+ self = await inHome(async () => localHostId());+ const local = new PGLiteEngine();+ await local.connect({}); await local.initSchema(); engines.push(local);+ const pg = process.env.DATABASE_URL;+ if (pg) { const isolated = await isolatedPersistencePostgres(pg); closePostgres = isolated.close; engines.push(isolated.engine); }+ for (const engine of engines) await engine.executeRaw('INSERT INTO sources(id,name) VALUES($1,$1) ON CONFLICT DO NOTHING', [SOURCE]);+}, 120_000);+afterAll(async () => {+ for (const engine of engines) await engine.disconnect();+ await closePostgres?.();+ rmSync(home, { recursive: true, force: true });+});++async function worktree(engine: BrainEngine, owner: string, heartbeatHoursAgo: number | null): Promise<string> {+ const [row] = await engine.executeRaw<{ id: string }>(`INSERT INTO persistence_worktrees(owner_host_id,heartbeat_at)+ VALUES($1::uuid, CASE WHEN $2::double precision IS NULL THEN NULL ELSE now()-($2::double precision*interval '1 hour') END) RETURNING id::text`, [owner, heartbeatHoursAgo]);+ return row!.id;+}+async function request(engine: BrainEngine, worktreeId: string | null, state: 'queued' | 'committed', hoursAgo: number): Promise<string> {+ return engine.transaction(async tx => {+ await tx.executeRaw("SELECT set_config('gbrain.persistence_protocol','2',true)");+ const [row] = await tx.executeRaw<{ id: string }>(`INSERT INTO persistence_requests(principal_kind,principal_id,request_id,operation,source_id,source_incarnation,slug,digest,authority,+ intent_bytes,terminal_reservation,state,intent,worktree_id,created_at,updated_at,completed_at,published_at)+ VALUES('local_cli','owner-activity',$1::uuid,'put_page',$2,(SELECT incarnation FROM sources WHERE id=$2),$3,$4,'{}'::jsonb,0,0,$5,'{"content":"x"}'::jsonb,$6::uuid,+ now()-($7::double precision*interval '1 hour'),now()-($7::double precision*interval '1 hour'),+ CASE WHEN $5='committed' THEN now()-($7::double precision*interval '1 hour') END,CASE WHEN $5='committed' THEN now()-($7::double precision*interval '1 hour') END)+ RETURNING id::text`, [randomUUID(), SOURCE, `notes/${randomUUID()}`, randomUUID(), state, worktreeId, hoursAgo]);+ return row!.id;+ });+}++describe('owner activity', () => {+ test('a quiet foreign owner is stale past 24 h; a PGLite file holder is never the owner; the owner is never stale to itself', async () => inHome(async () => {+ for (const engine of engines) {+ const pglite = engine.kind === 'pglite';+ const gone = await worktree(engine, randomUUID(), 48); await request(engine, gone, 'queued', 48);+ const recent = await worktree(engine, randomUUID(), 1); await request(engine, recent, 'queued', 1);+ const own = await worktree(engine, self, 48); await request(engine, own, 'queued', 48);+ const unknownYoung = await worktree(engine, randomUUID(), null); await request(engine, unknownYoung, 'queued', 1);+ const unknownOld = await worktree(engine, randomUUID(), null); await request(engine, unknownOld, 'queued', 48);+ const published = await worktree(engine, randomUUID(), 48); await request(engine, published, 'committed', 1); await request(engine, published, 'queued', 2);+ const owners = await ownerActivity(engine, [gone, recent, own, unknownYoung, unknownOld, published]);+ expect(owners.get(gone)).toMatchObject({ live: false, stale: true, foreign_file_holder: pglite });+ expect(Date.now() - Date.parse(owners.get(gone)!.last_active!)).toBeGreaterThan(OWNER_STALE_MS);+ expect(owners.get(recent)).toMatchObject({ live: false, stale: pglite });+ expect(owners.get(own)).toMatchObject({ owner_host_id: self, stale: false, foreign_file_holder: false });+ expect(owners.get(unknownYoung)).toMatchObject({ last_active: null, stale: pglite });+ expect(owners.get(unknownOld)).toMatchObject({ last_active: null, stale: true });+ expect(owners.get(published)!.stale).toBe(pglite);+ expect(Date.now() - Date.parse(owners.get(published)!.last_active!)).toBeLessThan(2 * 3_600_000);+ }+ }));++ test('the receipt names owner_stale and --accept-pending does not cover it; a repo-less write never names an owner', async () => inHome(async () => {+ for (const engine of engines) {+ const owner = randomUUID();+ const gone = await worktree(engine, owner, 48);+ const id = await request(engine, gone, 'queued', 48);+ const dbOnly = await request(engine, null, 'queued', 48);+ const rows = [(await getWriteRequestById(engine, id))!, (await getWriteRequestById(engine, dbOnly))!];+ const facts = await writeHealthFacts(engine, rows);+ const stale = receiptFor(rows[0]!, facts.get(id));+ expect(stale.diagnostic).toMatchObject({ reason: 'owner_stale', next_action: 'inspect_owner', owner: { host_id: owner, live: false } });+ const wire = publicWriteReceipt(stale as never);+ expect(isWriteReceipt(wire)).toBe(true);+ expect(wire.diagnostic?.owner?.host_id).toBe(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);+ expect(writeErrorExitCode(pending(wire), false)).toBe(PENDING_WRITE_EXIT_CODE);+ const repoLess = publicWriteReceipt(receiptFor(rows[1]!, facts.get(dbOnly)) as never);+ expect(repoLess.diagnostic?.reason).not.toBe('owner_stale');+ expect(repoLess.diagnostic?.owner).toBeUndefined();+ expect(writeErrorExitCode(pending(repoLess), true)).toBe(0);+ }+ }));++ test('Postgres: a live consumer keeps its owner fresh and a clean stop leaves the time it stopped', async () => inHome(async () => {+ for (const engine of engines.filter(e => e.kind === 'postgres')) {+ const owner = randomUUID();+ const tree = await worktree(engine, owner, 48);+ await request(engine, tree, 'queued', 48);+ expect((await ownerActivity(engine, [tree])).get(tree)).toMatchObject({ live: false, stale: true });+ const heartbeat = startConsumerHeartbeat(engine as never, owner, { kind: 'serve', mode: 'full', everyMs: 1_000_000, report: () => ({ restart_required: false, root_barrier_age_ms: null }) });+ await heartbeat.renew();+ expect((await ownerActivity(engine, [tree])).get(tree)).toMatchObject({ live: true, stale: false });+ await heartbeat.stop();+ const after = (await ownerActivity(engine, [tree])).get(tree)!;+ expect(after).toMatchObject({ live: false, stale: false });+ expect(Date.now() - Date.parse(after.last_active!)).toBeLessThan(60_000);+ }+ }));+});diff --git a/test/postgres-unit-arms.txt b/test/postgres-unit-arms.txtindex 51f073d68c..69caecc66f 100644--- a/test/postgres-unit-arms.txt+++ b/test/postgres-unit-arms.txt@@ -118,6 +118,7 @@ test/import-file-result-callback-gbra130.test.tstest/import-frontmatter-key-order-5158.test.tstest/import-inline-chunk-keep.test.tstest/import-revision-concurrency.test.ts+test/init-cold-home-embedding.test.tstest/keyword-statement-timeout-knob-6495.test.tstest/keyword-timeout-negative-cache-6495.test.tstest/lane-apply-pipelining.test.ts@@ -395,6 +396,7 @@ test/persistence-managed-lifecycle.test.tstest/persistence-managed-sync.test.tstest/persistence-manifest-git-scope.test.tstest/persistence-memory-mutations.test.ts+test/persistence-owner-activity.test.tstest/persistence-page-authority.test.tstest/persistence-physical-root-device.test.tstest/persistence-preactivation-claim.test.ts