Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

W3 (GBRA-224): bounded, audited, switchable self-heals for dream and embedding noise

garrytan5a27923c8243
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9bdfa4a6c8..a945bfdd0d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,30 @@ credits are retained; no result has been reassigned to another provider. Origina
identifiers and attribution are available in the pre-removal Git revision
`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).
+## [Unreleased]
+
+**Dream and embedding maintenance fix their own routine noise for free, and tell you only when that stops working.**
+
+A self-hosted nightly cycle could end `partial` for reasons that needed no one: a purge or consolidate write accepted but still committing after its 5-second wait, a synthesize window with nothing new in it, or pages whose vectors already belonged to the current model but carried no signature, so they read as another model's space and invited a paid re-embed. Each of these now heals inside the cycle with no model or provider call, within a fixed bound, with a record of what it did and a config switch to turn it off. When a heal hits its bound, a doctor check says so.
+
+### What changed
+
+| Situation | Before | Now |
+|---|---|---|
+| A purge or consolidate write is accepted but still pending after the publish wait | the phase failed and the cycle ended `partial` | the phase warns `dream_write_deferred` with the receipt id; the next pass reads that receipt before it submits anything for the source. After 3 passes still pending, doctor `dream_write_deferred` names the receipt |
+| Every transcript in the synthesize window is already synthesized | triage, the manifest context and the child queue still ran | the phase returns `no_candidates` before any of that |
+| A transcript grows between runs that keep dying | each run had a new content key, so the 3-deaths breaker never tripped | deaths also count per transcript (`dream:synth-v2:@file:<source>:<file>`); the same 3-in-24h limit applies |
+| `gbrain dream reset-key` on a `dream:phase:` key that `--list` printed | refused as not a breaker key | resets it |
+| Pages whose chunks already hold current-model vectors but have no or an old signature | read as another model's space until a paid drain stamped them | the embed phase stamps them first, up to 500 pages a run, with no provider call |
+| A soft-deleted page keeps unembedded chunks | health's embedding coverage dropped | coverage counts live pages only, like `missing_embeddings` |
+
+### For operators
+
+- New doctor checks `dream_write_deferred` and `embedding_restamp_stalled` (read-only). Both are meant for the page class of `gbrain doctor --alert`.
+- New switches, on by default: `dream.write_deferral.enabled` and `embed.restamp.enabled`. Setting either to `false` restores the old behavior.
+- Every heal writes a row to the `heal.audit` config record (last 200 rows, 30 days).
+- Nothing runs on upgrade: the restamp runs only in the maintenance cycle's embed phase, and repo-less brains get the same behavior.
+
## [0.60.476.0] - 2026-10-27
**Text someone else wrote can no longer add facts to your brain.**
diff --git a/docs/architecture/key-files/core-cycle-continued.md b/docs/architecture/key-files/core-cycle-continued.md
index 10f4067407..93ca3f78dc 100644
--- a/docs/architecture/key-files/core-cycle-continued.md
+++ b/docs/architecture/key-files/core-cycle-continued.md
@@ -6,5 +6,7 @@ Synthesis, patterns, consolidation and connector atom gating.
- `src/core/cycle/synthesize-postprocess.ts` — Managed synthesis quote repair and provenance stamping publish together through a deterministic maintenance request bound to the source incarnation, transcript hash, child output, and original committed page revision. `loadCommittedSynthesisOutputs` finds each child's committed output by canonicalizing the retained `brain_put_page` input (`parseWriteRequestId` for the request id, `journaledPageSlug` for the slug) before matching request id, source, incarnation, committed put_page, slug and revision (#6616); slug discovery (`collectChildPutPageSlugs`) and postprocessing share that set. The immutable committed receipt is the completion checkpoint: later runs skip finalized output rather than repairing user edits. Pending work replays its retained intent under the original revision and existing authority/file guards; missing provenance fails closed. A publish still `write_pending` after the job's shared maintenance wait is deferred, never written or finalized: `withPublishPending` turns the phase result into `warn` with `publish_pending` and `SYNTH_PUBLISH_DEFERRED` ("publish deferred (writer busy); finishes next cycle, no action needed"), `synthesize.ts` leaves `dream.synthesize.last_completion_ts` unstamped, and the next ordinary cycle resumes the same deterministic request id. Runs the same claim verification as the unmanaged path (`groundSource` + `resolveVerifyPrior` + `verifyDreamPage` from `synthesize-verify.ts`, scoped by the ref's `first_write_at`, else the child write epochs passed as `sinceByTranscript`) and stamps the dream provenance fields only on dream-owned pages (`isDreamOwnedPage`); the published page reconciles its automatic links like an ordinary put_page (`page-prepare.ts` treats `managed_maintenance_page` intents as auto-linked); the unmanaged path retains its fail-open behavior. Covered by `test/managed-synthesis-postprocess.test.ts` and its PostgreSQL E2E wrapper. The optional `grounding` pass (System One S8) runs after `verifyDreamPage` and before `publishMaintenancePage`, so the published revision never carries a unit S8 quarantined; pinned by `test/decide/writepath-phase.serial.test.ts`. The postprocess stamps the transcript's `seat` next to `raw_source` on dream-owned output. `deferPublishOrThrow` defers an output or summary publish that is still pending, whose admission gave up on database contention (`publicationHold` in `persistence/accepted-pending.ts`), or whose unadmitted request was refused `queue_capacity` by a positive principal or brain outstanding-request cap (`isWriteCapacityWait` + `outstandingCapacityOf`, no write receipt) exactly like the pending case: `publish_pending`, phase warn, no cooldown stamp, and the next cycle retries the same request id; a contended or capacity-blocked publish writes one stderr line. A zero cap, cumulative quotas, unknown capacity, a capacity refusal carrying a receipt and every other error fail the phase. Pinned by `test/managed-synthesis-postprocess.test.ts`. #5575 I2: each output publishes with `derivation` from its transcript (`dream-taint.ts` `transcriptDerivation`; `meetingTranscriptsDir` in opts); a retained request replays the declaration it was admitted with. #6360: when the page moved after the child commit, a drift made only by committed local `managed_maintenance_page` requests (for example the next cycle's lint `created:` fix) over a body equal to the child's is adopted: the postprocess runs on the current snapshot under a request id that also binds that base revision (found again on replay among the later requests). Any other later write leaves the page alone as a `PostprocessConflict` (`withPostprocessConflicts`: phase `warn`, `details.postprocess_conflicts` with the read-only `gbrain get` fix); it is reported once (config `dream.synthesize.postprocess_conflicts`, 30-day memory) and does not block the cooldown stamp. #6757: the committed-outputs join (`COMMITTED_OUTPUT_REQUESTS_SQL`) compares `request_id` as a uuid within the source, served by `persistence_requests_request_id`. The phase loads it through `loadCommittedOutputsOrDefer`; a statement timeout there, or on an output's own `getWriteRequest`, defers the pass instead of failing it (`withPublishPending` with `details.postprocess_deferred`: phase warn, no cooldown stamp, no summary). Deferred and publish-pending outputs are carried by `synthesize-postprocess-deferral.ts` and finished by a later pass from the carried fields, with no child; `finishDeferredPostprocess` (run after the phase body by `runPhaseSynthesize`) finishes them when that pass returned before postprocessing. GBRA-130 A-4: outputs run as `ItemRun` items (`synthesize.postprocess`). A postprocess request that ended conflict, failed or cancelled, or whose retained intent no longer matches, is a `PostprocessConflict` (the request's `error_code`, else `recovery_required`; fix `gbrain write-request -- <id>`) dropped from the pending row; the summary names each slug and code. Other item errors let the rest run and the pass save, then fail the phase; run-scoped errors and `item_failures_systemic` stop it and record nothing. Pinned by `test/pathological/a4-synthesize-postprocess.test.ts`.
- `src/core/cycle/synthesize-postprocess-deferral.ts` — #6757: config row `dream.synthesize.postprocess_pending`, keyed by source and bound to its incarnation: each pending output (child request id, journaled and input slug, revision, job key, transcript path, content hash, seat, first write) and the source's consecutive deferred passes with the last read and its elapsed time. `isPostprocessReadTimeout` unwinds a cancelled cycle first, then accepts only SQLSTATE 57014 with the statement-timeout message (a user cancel is not deferred). `recordPostprocessPass` drops settled outputs, adds deferred and carried ones and resets the count on a pass that deferred nothing; `repeatedPostprocessDeferrals` lists sources at three or more for doctor `persistence_request_indexes`. The replay runs no child job and verifies a replayed output's quotes against the transcript as it is now, even when it grew after synthesis; a quote not found there goes to `unverified_claims` like any failed quote.
+- `src/core/cycle/dream-write-deferral.ts` — W3 (#7587): config row `dream.write_deferral.pending`, keyed `<phase>:<source>`. A purge or consolidate write accepted but still pending after its publish wait (`maintenancePublishWaitMs`) is recorded with its request id (`deferDreamWrite`); the next pass's `reconcileDreamWriteDeferrals` reads each receipt before anything is submitted: committed clears it, a terminal failure is reported with its real code and not resubmitted that pass, still pending holds the source (nothing new submitted) and counts a replay. At `DREAM_WRITE_DEFERRAL_MAX_REPLAYS` (3) doctor's `dream_write_deferred` (`src/commands/doctor/checks/dream-write-deferred.ts`) warns with the receipt and `gbrain write-request -- <id>`. `dream.write_deferral.enabled=false` restores the failing phase. Audit rows go to `src/core/heal-audit.ts` (config `heal.audit`, 200 rows, 30 days) in the same transaction. Tests: `test/dream-write-deferral-w3.test.ts` (PGLite, Postgres, repo and repo-less).
+- `src/core/embedding-restamp.ts` — W3 (#5527 class): `restampCurrentSpaceSignatures` runs at the start of the cycle embed phase (never on upgrade, skipped in dry runs) and sets `pages.embedding_signature` on up to 500 pages per run whose every chunk already holds a current-model vector (`currentSpaceChunkPredicate`), with no provider call. Each stamp takes `lockPageKeys` and re-checks the selected revision and signature, the sealed text projection, the active column and every chunk, so a concurrent edit or re-embed makes it match nothing (`rejected`). Three failed runs in a row escalate to doctor `embedding_restamp_stalled` (`src/commands/doctor/checks/embedding-restamp.ts`); `embed.restamp.enabled=false` turns it off. Tests: `test/embedding-restamp-w3.test.ts`.
Patterns, drift and the entries after them: [Core Cycle (patterns)](core-cycle-patterns.md).
diff --git a/docs/architecture/key-files/core-cycle.md b/docs/architecture/key-files/core-cycle.md
index 8e7a38e28c..3c79c54282 100644
--- a/docs/architecture/key-files/core-cycle.md
+++ b/docs/architecture/key-files/core-cycle.md
@@ -42,7 +42,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/core/cycle/nightly-quality-probe.ts` + `src/core/audit-quality-probe.ts` + `test/fixtures/longmemeval-nightly.jsonl` + `test/nightly-quality-probe.test.ts` — opt-in nightly cross-modal quality probe. The phase runs `gbrain eval longmemeval --by-type` against the committed 10-question placeholder fixture, pipes output through `gbrain eval cross-modal --batch --max-usd 5 --yes`, and writes one event per run to `~/.gbrain/audit/quality-probe-YYYY-Www.jsonl` (ISO-week-rotated, mirrors `audit-slug-fallback.ts`; honors `GBRAIN_AUDIT_DIR`). Default DISABLED — opt-in via `gbrain config set autopilot.nightly_quality_probe.enabled true` (prevents surprise API spend). 24h rate limit (pure `shouldRunNightly(now, recentEvents, windowMs?)`) skips without an audit row. An unreadable fixture writes `outcome: skipped` with `reason: fixture_unavailable` (exit 0, no model call; the row also holds the 24h gate). Embedding-key short-circuit: longmemeval needs `gateway.embedQuery()`, so the phase exits early with `outcome: no_embedding_key` + stderr warn when no provider configured. Full DI surface via `NightlyProbeDeps` (`isEnabled`, `hasEmbeddingProvider`, `resolveMaxUsd`, optional `resolveBudgetPolicy`, `resolveFixturePath` (wins) / `resolveRepoRoot`, `resolveSearchConfigSnapshot` and `resolveModelRoutes`, `runLongMemEval`, `runCrossModalBatch`, `now`) so the unit test stubs every external effect. `resolveModelRoutes` runs inside the run's `try` before LongMemEval and its routes reach both adapters; a rejection becomes an `error` audit row naming the model routes and LongMemEval never starts. Rows also carry the evidence behind the verdict (#5506), every field optional so older rows read unchanged (`logQualityProbeEvent` copies them from one explicit list): `reader_model` / `extractor_model` once the routes resolved; `judge_models` in slot order, `judge_scored_questions` per slot, and `distinct_judge_models` / `distinct_judge_providers` over the slots that scored, from a completed batch; on a non-pass row, up to 10 `failures` (failing dimensions with mean, slot-indexed scores and fail reason, or redacted error text) and a one-line digest `detail` counting every question that did not pass, malformed rows included, and naming a slot that scored none. One pricing `withChatCallMeter` meter wraps LongMemEval and the batch, so every row of a run that reached its model calls, a part-way failure included, records `chat_calls`, `chat_cost_usd` (reader, extractor and judges) and `unpriced_chat_calls`; `est_cost_usd` stays the batch's pre-flight estimate for its judge calls only, 0 without a summary. Run-level budget (CEO B4): one `BudgetTracker` (`withBudgetTracker`) wraps both stages with `max_usd` as the cap (`resolveProbeCap`: a configured value is a `user` cap, else the $5 `default`; `pricing.overrides` from the brain), so every gateway chat/embed call of LongMemEval and the judges reserves first. A refusal is kept by the `ProbeBudgetTracker` subclass even when LongMemEval records it as a per-question error: exhausted after LongMemEval → `budget_exceeded`, no judge call; exhausted while judging → `budget_exceeded` whatever the batch said; a user cap refuses an unpriced model with the shared no_pricing text (`reason: no_pricing`), a default cap warns and runs it. Rows carry `cap_usd` / `cap_source`. A pass or fail from a collapsed panel (one model holding two judged slots, or fewer than two models judged) becomes `inconclusive` with `reason: panel_collapsed`, the batch verdict and the slot-key remedy in `detail` (D12). A non-pass run copies `summary.json` / `lme-output.jsonl` to `<audit dir>/nightly-probe/<ts>/` (newest 7) and names it in `receipt_dir`. The `nightly_quality_probe_health` doctor check (`computeNightlyQualityProbeHealthCheck` in `src/commands/doctor/checks/search-eval.ts`, registered right after `slug_fallback_audit` by `src/commands/doctor/checks/local-audits.ts`) reads last 7 days: SKIPPED when flag off (with enable command); OK when enabled + all PASS; WARN on any non-PASS outcome with per-outcome counts (`skipped=N` appended when a run skipped), so a skipped run is never OK. OK and WARN append the latest row's judge panel and name a slot that scored no question; among the slots that scored, a model holding two or more gets the remedy (three different models in `models.eval.cross_modal.slot_a` / `slot_b` / `slot_c`), fewer than three providers get the not-cross-modal information; a row without valid panel fields keeps the plain message. Pinned by `test/nightly-quality-probe.test.ts`.
-- `src/core/cycle/dream-breaker.ts` — dream paid-loop circuit breaker. `countDeadDreamSubmissions` is the one counting rule shared by synthesize, patterns, `gbrain dream reset-key` and the `dream_paid_loop` doctor check: dead `subagent` rows finished in the last 24 h (partial index `idx_minion_jobs_dead_subagent_finished`, migration 173), keyed by the live or released idempotency key with the `:c<i>of<n>` chunk suffix stripped, counted as distinct queues (one per run), ignoring deaths before the key's persisted reset (`dream.breaker.resets` config JSON, database clock). A key at `dream.breaker.max_dead_submissions` (default 3; 0 disables) is refused before synthesis submission; a failed count leaves the breaker off for that run with a warning. Completed jobs, including legitimate zero-write completions, never count. Growing transcripts change their content-hashed key and unkeyed patterns runs are not covered. Contained cycle-phase failures after paid model calls (`recordContainedPaidFailure`, `dream.breaker.contained_failures` config JSON, 24 h window, database clock) are counted under `dream:phase:<phase>:<source>` keys; the breaker never refuses those phases, doctor reports them and `gbrain dream reset-key` clears them. Tests: `test/dream-breaker.test.ts`, `test/cycle-synthesize-breaker.test.ts`, `test/e2e/dream-breaker-postgres.test.ts`. Patterns rows count under the per-source key `dream:patterns:source:<data.source_id or default>` (never their content key), and a patterns child `cancelled` with recorded tokens counts as a death; `patternsBreakerSkip` returns the phase skip (`dream_breaker_tripped`, paid reset `fix`, read-only `--list --json` verify) and `clearPatternsSourceDeaths` resets the source after a completed child (`test/dream-breaker-patterns-source.test.ts`).
+- `src/core/cycle/dream-breaker.ts` — dream paid-loop circuit breaker. `countDeadDreamSubmissions` is the one counting rule shared by synthesize, patterns, `gbrain dream reset-key` and the `dream_paid_loop` doctor check: dead `subagent` rows finished in the last 24 h (partial index `idx_minion_jobs_dead_subagent_finished`, migration 173), keyed by the live or released idempotency key with the `:c<i>of<n>` chunk suffix stripped, counted as distinct queues (one per run), ignoring deaths before the key's persisted reset (`dream.breaker.resets` config JSON, database clock). A key at `dream.breaker.max_dead_submissions` (default 3; 0 disables) is refused before synthesis submission; a failed count leaves the breaker off for that run with a warning. Completed jobs, including legitimate zero-write completions, never count. Synthesize deaths also count per transcript under `dream:synth-v2:@file:<source id>:<encoded file>` (`dreamSynthFileKey`) once they span two content keys, so a growing transcript trips too (W3, #6753), and `gbrain dream reset-key` accepts every key `--list` prints (`DREAM_RESETTABLE_KEY_PREFIXES`, #7505); unkeyed patterns runs are not covered. Contained cycle-phase failures after paid model calls (`recordContainedPaidFailure`, `dream.breaker.contained_failures` config JSON, 24 h window, database clock) are counted under `dream:phase:<phase>:<source>` keys; the breaker never refuses those phases, doctor reports them and `gbrain dream reset-key` clears them. Tests: `test/dream-breaker.test.ts`, `test/cycle-synthesize-breaker.test.ts`, `test/e2e/dream-breaker-postgres.test.ts`. Patterns rows count under the per-source key `dream:patterns:source:<data.source_id or default>` (never their content key), and a patterns child `cancelled` with recorded tokens counts as a death; `patternsBreakerSkip` returns the phase skip (`dream_breaker_tripped`, paid reset `fix`, read-only `--list --json` verify) and `clearPatternsSourceDeaths` resets the source after a completed child (`test/dream-breaker-patterns-source.test.ts`).
- `src/core/cycle/phantom-redirect.ts` — Phantom-redirect orchestrator. Exports `runPhantomRedirectPass(engine, brainDir, sourceId, dryRun): Promise<PhantomPassResult>` (per-cycle wrapper acquiring the `gbrain-sync` writer lock once for the whole pass, 30s bounded retry, walks up to `GBRAIN_PHANTOM_REDIRECT_LIMIT` unprefixed phantoms) + `tryRedirectPhantom(engine, page, sourceId, brainDir, dryRun): Promise<RedirectResult>` + `stripFenceAndFrontmatterAndLeadingH1` (pure body-shape gate helper — strips facts fence incl. preceding `## Facts` heading and the leading H1). Only fence rows migrate, so the residue gate also counts the page's timeline text, any `timeline_entries` row, and frontmatter keys beyond `title`/`type`/`tags`; any residue = not a phantom. Handler order: body-shape gate → `resolvePhantomCanonical` (bypasses exact-self-match; a fuzzy hit needs a 0.1 margin over the runner-up) → `findPrefixCandidates` ambiguity check (a canonical that is not the single prefix candidate is ambiguous too) → `fenceDbDrift` bi-directional check → a phantom fence that parses with warnings is `drift` (its skipped rows would go with the deleted phantom, #6385 R12) → dry-run early exit → canonical file resolved through `resolvePageWriteTarget` (recorded `source_path`, own-`local_path` roots; only a brain with no configured root falls back to `brainDir`) → materialize canonical via `serializeMarkdown` if DB-only → append phantom fence rows to that file with `(claim, valid_from)` dedup-guard, numbering past both the file's and the DB's highest row number and rewriting `superseded by #N` to the new numbers → `engine.refreshPageBody` → move the phantom's fact withdrawals to the canonical subject → move every phantom fact row by id (a row takes its on-disk canonical row number unless the canonical index already holds it; history, duplicates and rows absent from the fence move expired and detached, never deleted) → move the phantom's links to the canonical page id (skipping duplicates and self-links) → `recordRenameAlias` (phantom → canonical in `slug_aliases`) → `engine.softDeletePage` + unlink. `RedirectResult.canonical` populated on `'redirected'` (incl. dry-run preview) so the caller builds `touched_canonicals`. Idempotent on re-run: phantom soft-deleted → predicate fails (`deleted_at IS NULL`); migrate UPDATE matches no rows; dedup-guard prevents double-append. `mergePhantomFenceRows` (pure body merge; throws `FenceRewriteRefusal` on a canonical fence that parses with warnings, which the pass records as `drift`), `movePhantomFacts` (row move inside the caller's transaction) and `mergePhantomLinks` are shared with `phantom-redirect-managed.ts`, which a managed brain uses instead of the file-first commit phase. GBRA-130 A-24: the pass resumes after the last slug it examined (`slug > cursor`, op_checkpoints op `PHANTOM_REDIRECT_CURSOR_OP` = `phantom-redirect-cursor`, fingerprint the source id, via `rotationAfter`/`saveRotation`), so root prose notes that are not phantoms no longer starve later phantoms; the cursor resets to `''` after a full pass and stays put on a dry run, an abort or a stop. Phantoms run as `ItemRun` items (`extract_facts.phantom_redirect`): an item error is a `failures[]` entry (`key`, `code`, `message`, `fix` `gbrain dream --phase extract_facts --source <id>`) and the next phantom still runs; a run-scoped error rethrows and `item_failures_systemic` sets `stopped`. `extract-facts.ts` turns them into `phantom_redirect_failed: <slug> (<code>); retry: <fix>` and `phantom_redirect_stopped: …` warnings. Pinned by `test/pathological/a24-phantom-redirect-cursor.test.ts` (both engines). #6982 (GBRA-131 D-5/D-6): with `sync.write_through` off the phantom's rows merge into the canonical's database body under a row lock (prior body in page_versions) and no file is written or removed. With it on, the phantom's file is removed only when `replaceableFile` finds nothing in it its row lacks (re-read right before the unlink; a changed file is kept and reported), and the canonical file takes the rows only when its body and timeline equal the canonical's database body; the mirror then runs under the row lock (`mirrorFileBody`, prior body in page_versions, importer hash), the file is re-read immediately before the `.tmp` is renamed last, and a body that moved, or a file that moved (which rolls the transaction back), holds the phantom. Holds are `drift` outcomes listed in `PhantomPassResult.held` (`<slug> (file_database_drift: …)` with its fix), which extract_facts turns into `phantom_redirect_held:` warnings. Pinned by `test/pathological/d5-phantom-canonical-overwrite.test.ts` and `test/pathological/d6-phantom-file-unlink.test.ts` (both engines).
diff --git a/docs/guides/cron-schedule.md b/docs/guides/cron-schedule.md
index 8c38f2ec88..654ab73446 100644
--- a/docs/guides/cron-schedule.md
+++ b/docs/guides/cron-schedule.md
@@ -381,7 +381,9 @@ times (default 3; `0` disables) within 24 hours is refused before the next
submission, and `gbrain doctor` reports it as `dream_paid_loop`. Fix the
cause first (a missing provider key, a quota, a failing transcript), then
`gbrain dream reset-key --list` shows the refused keys and
-`gbrain dream reset-key '<key>'` re-enables one. Details in
+`gbrain dream reset-key '<key>'` re-enables one. A purge or consolidate write
+still pending after its publish wait is deferred and reconciled on the next
+pass instead of failing the cycle (`dream_write_deferred` after 3 passes). Details in
[spend controls](../operations/spend-controls.md#dream-paid-loop-breaker-dreambreakermax_dead_submissions).
Three more fields answer "what did that cost and did it land":
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
index 37aac2e35a..74402452eb 100644
--- a/docs/guides/troubleshooting.md
+++ b/docs/guides/troubleshooting.md
@@ -82,6 +82,8 @@
| `gbrain init` or `gbrain upgrade` stops with `schema_lock_blocked` naming a pid (or, before #5227, sat in `wait_event_type=Lock` with no output) | let the named session finish, or with the user's agreement end it on the database host: `SELECT pg_terminate_backend(<pid>)`; then rerun the same command ([ENGINES.md](../ENGINES.md#schema-lock-blocked)) | brain host, after the user agrees | `destructive` when it ends another session | the rerun completes; `gbrain doctor --json` shows the schema at head |
| [`queue_capacity`, `persistence_capacity` or `persistence_request_growth`](#write-capacity) | run the printed `gbrain config set persistence.limits.<limit> <value>` | brain host | none | `gbrain doctor --only persistence_capacity,persistence_request_growth --json` |
| [`dream_paid_loop`, or dream keeps skipping one transcript](#dream-paid-loop) | fix the cause, then `gbrain dream reset-key --list` and `gbrain dream reset-key '<key>'` | agent, after the user agrees | `paid` (the key is retried) | `gbrain doctor --only dream_paid_loop --json` |
+| [`dream_write_deferred`: a purge or consolidate write is still pending after 3 passes](#dream-write-deferred) | read the receipt it names (`gbrain write-request -- <id>`), then `gbrain sources writer status --source <id> --json` | agent | none | `gbrain doctor --only dream_write_deferred --json` |
+| [`embedding_restamp_stalled`](#embedding-restamp-stalled) | fix the error it names, then `gbrain dream --phase embed --json` | agent | `paid` only for stale chunks the embed phase embeds | `gbrain doctor --only embedding_restamp_stalled --json` |
| [A page exists (`gbrain get <slug>` returns it) but search never finds text from it](memory-boundaries.md#large-pages) | `gbrain reindex --oversized --dry-run --json` lists pages stored before the upgrade with a size-based `embed_skip` marker (without `--dry-run` it keyword-indexes them, free); a page above an operator-lowered `content_sanity.bytes_block` keeps its marker until it is raised; a page the content-quality gate quarantined shows in `gbrain quarantine list` (`gbrain quarantine clear <slug>` re-checks it once the user agrees); a file over the 24 MiB page ceiling was never stored ([`file_too_large`](write-refusals.md#file_too_large)). Its chunks waiting for embedding approval (doctor `partial_embedding`) are a paid step: `gbrain embed --held --dry-run`, then `gbrain embed --held --source <id> --max-usd <N>` as printed | agent for the reindex; the user decides embedding spend, a `bytes_block` change and a quarantine clear | none for the reindex; `paid` for `gbrain embed` | `gbrain reindex --oversized --dry-run --json` lists nothing; `gbrain search "<phrase from deep in the page>"` returns the page |
| [Search answers look keyword-only on a large Postgres brain](#hybrid-search-returns-only-keyword-hits) | read doctor's `vector_plan`; run the index command it prints | brain host | none | `gbrain doctor --only vector_plan --json` |
| [Broad keyword queries take about 8 s and come back vector-only (`keyword_arm_failed`, or `skipped_after_timeout` for 10 minutes after a timeout) on a large Postgres brain](#keyword-search-times-out-on-a-large-postgres-brain) | read doctor's `keyword_plan`; narrow with `--source-id`, or raise `search.keyword_statement_timeout_ms` on the brain host and restart the serving process | brain host | none | `gbrain doctor --only keyword_plan --json` |
@@ -284,6 +286,10 @@ A running sync is not one of these: `gbrain repair fences` now runs during a cat
<a id="dream-paid-loop"></a>**Dream keeps skipping one transcript, or doctor warns `dream_paid_loop`?** A dream key died `dream.breaker.max_dead_submissions` times (default 3) in 24 hours and is refused so it stops billing you. Fix the cause, then `gbrain dream reset-key --list` and `gbrain dream reset-key '<key>'`. See [the paid-loop breaker](../operations/spend-controls.md#dream-paid-loop-breaker-dreambreakermax_dead_submissions).
+<a id="dream-write-deferred"></a>**Doctor warns `dream_write_deferred`?** A purge or consolidate write was accepted but still pending after its publish wait. The phase reports it as deferred (warn, not a failed cycle), keeps the receipt id and reconciles it on the next pass before it submits anything for that source. After 3 passes still pending, doctor names the receipt: read it with `gbrain write-request -- <id>`, and `gbrain sources writer status --source <id> --json` says why the writer has not committed it. `gbrain config set dream.write_deferral.enabled false` turns deferral off (a pending write then fails the phase, as before).
+
+<a id="embedding-restamp-stalled"></a>**Doctor warns `embedding_restamp_stalled`?** The embed phase first stamps the current embedding signature on pages whose vectors already match the current model, with no provider call. That stamp failed 3 runs in a row; the message names the error. Fix it, then run `gbrain dream --phase embed --json`. `gbrain config set embed.restamp.enabled false` turns the restamp off.
+
**Hourly cron sync keeps timing out on a federated brain?** Switch your
cron to a per-source loop with shell `timeout(1)` doing the OS-level kill
and gbrain self-terminating gracefully half-a-minute earlier:
diff --git a/docs/operations/spend-controls.md b/docs/operations/spend-controls.md
index 1eacfc7c37..1240934422 100644
--- a/docs/operations/spend-controls.md
+++ b/docs/operations/spend-controls.md
@@ -401,8 +401,11 @@ gbrain config set dream.breaker.max_dead_submissions 5 # raise the limit; 0 di
cancelled before any work does not. A completed run resets the count, so only
deaths in a row trip it; reset a tripped source with
`gbrain dream reset-key 'dream:patterns:source:<source id>'`.
-- Not covered: a transcript that keeps growing gets a new content-hashed key each
- cycle, and patterns runs outside maintenance carry no key.
+- A transcript that keeps growing gets a new content-hashed key each cycle, so
+ synthesize deaths also count per transcript under
+ `dream:synth-v2:@file:<source id>:<file>` once they span two content keys; the same
+ limit applies. `gbrain dream reset-key --list` prints it, and reset it the same way.
+- Not covered: patterns runs outside maintenance carry no key.
- If the count query fails, the breaker is skipped for that run with a warning, the
same posture as the synthesize daily cap.
diff --git a/llms-full.txt b/llms-full.txt
index 8bb509c82f..019601628e 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -8206,7 +8206,9 @@ times (default 3; `0` disables) within 24 hours is refused before the next
submission, and `gbrain doctor` reports it as `dream_paid_loop`. Fix the
cause first (a missing provider key, a quota, a failing transcript), then
`gbrain dream reset-key --list` shows the refused keys and
-`gbrain dream reset-key '<key>'` re-enables one. Details in
+`gbrain dream reset-key '<key>'` re-enables one. A purge or consolidate write
+still pending after its publish wait is deferred and reconciled on the next
+pass instead of failing the cycle (`dream_write_deferred` after 3 passes). Details in
[spend controls](../operations/spend-controls.md#dream-paid-loop-breaker-dreambreakermax_dead_submissions).
Three more fields answer "what did that cost and did it land":
@@ -10291,6 +10293,8 @@ Source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/tro
| `gbrain init` or `gbrain upgrade` stops with `schema_lock_blocked` naming a pid (or, before #5227, sat in `wait_event_type=Lock` with no output) | let the named session finish, or with the user's agreement end it on the database host: `SELECT pg_terminate_backend(<pid>)`; then rerun the same command ([ENGINES.md](../ENGINES.md#schema-lock-blocked)) | brain host, after the user agrees | `destructive` when it ends another session | the rerun completes; `gbrain doctor --json` shows the schema at head |
| [`queue_capacity`, `persistence_capacity` or `persistence_request_growth`](#write-capacity) | run the printed `gbrain config set persistence.limits.<limit> <value>` | brain host | none | `gbrain doctor --only persistence_capacity,persistence_request_growth --json` |
| [`dream_paid_loop`, or dream keeps skipping one transcript](#dream-paid-loop) | fix the cause, then `gbrain dream reset-key --list` and `gbrain dream reset-key '<key>'` | agent, after the user agrees | `paid` (the key is retried) | `gbrain doctor --only dream_paid_loop --json` |
+| [`dream_write_deferred`: a purge or consolidate write is still pending after 3 passes](#dream-write-deferred) | read the receipt it names (`gbrain write-request -- <id>`), then `gbrain sources writer status --source <id> --json` | agent | none | `gbrain doctor --only dream_write_deferred --json` |
+| [`embedding_restamp_stalled`](#embedding-restamp-stalled) | fix the error it names, then `gbrain dream --phase embed --json` | agent | `paid` only for stale chunks the embed phase embeds | `gbrain doctor --only embedding_restamp_stalled --json` |
| [A page exists (`gbrain get <slug>` returns it) but search never finds text from it](memory-boundaries.md#large-pages) | `gbrain reindex --oversized --dry-run --json` lists pages stored before the upgrade with a size-based `embed_skip` marker (without `--dry-run` it keyword-indexes them, free); a page above an operator-lowered `content_sanity.bytes_block` keeps its marker until it is raised; a page the content-quality gate quarantined shows in `gbrain quarantine list` (`gbrain quarantine clear <slug>` re-checks it once the user agrees); a file over the 24 MiB page ceiling was never stored ([`file_too_large`](write-refusals.md#file_too_large)). Its chunks waiting for embedding approval (doctor `partial_embedding`) are a paid step: `gbrain embed --held --dry-run`, then `gbrain embed --held --source <id> --max-usd <N>` as printed | agent for the reindex; the user decides embedding spend, a `bytes_block` change and a quarantine clear | none for the reindex; `paid` for `gbrain embed` | `gbrain reindex --oversized --dry-run --json` lists nothing; `gbrain search "<phrase from deep in the page>"` returns the page |
| [Search answers look keyword-only on a large Postgres brain](#hybrid-search-returns-only-keyword-hits) | read doctor's `vector_plan`; run the index command it prints | brain host | none | `gbrain doctor --only vector_plan --json` |
| [Broad keyword queries take about 8 s and come back vector-only (`keyword_arm_failed`, or `skipped_after_timeout` for 10 minutes after a timeout) on a large Postgres brain](#keyword-search-times-out-on-a-large-postgres-brain) | read doctor's `keyword_plan`; narrow with `--source-id`, or raise `search.keyword_statement_timeout_ms` on the brain host and restart the serving process | brain host | none | `gbrain doctor --only keyword_plan --json` |
@@ -10493,6 +10497,10 @@ A running sync is not one of these: `gbrain repair fences` now runs during a cat
<a id="dream-paid-loop"></a>**Dream keeps skipping one transcript, or doctor warns `dream_paid_loop`?** A dream key died `dream.breaker.max_dead_submissions` times (default 3) in 24 hours and is refused so it stops billing you. Fix the cause, then `gbrain dream reset-key --list` and `gbrain dream reset-key '<key>'`. See [the paid-loop breaker](../operations/spend-controls.md#dream-paid-loop-breaker-dreambreakermax_dead_submissions).
+<a id="dream-write-deferred"></a>**Doctor warns `dream_write_deferred`?** A purge or consolidate write was accepted but still pending after its publish wait. The phase reports it as deferred (warn, not a failed cycle), keeps the receipt id and reconciles it on the next pass before it submits anything for that source. After 3 passes still pending, doctor names the receipt: read it with `gbrain write-request -- <id>`, and `gbrain sources writer status --source <id> --json` says why the writer has not committed it. `gbrain config set dream.write_deferral.enabled false` turns deferral off (a pending write then fails the phase, as before).
+
+<a id="embedding-restamp-stalled"></a>**Doctor warns `embedding_restamp_stalled`?** The embed phase first stamps the current embedding signature on pages whose vectors already match the current model, with no provider call. That stamp failed 3 runs in a row; the message names the error. Fix it, then run `gbrain dream --phase embed --json`. `gbrain config set embed.restamp.enabled false` turns the restamp off.
+
**Hourly cron sync keeps timing out on a federated brain?** Switch your
cron to a per-source loop with shell `timeout(1)` doing the OS-level kill
and gbrain self-terminating gracefully half-a-minute earlier:
diff --git a/scripts/module-size-limits.tsv b/scripts/module-size-limits.tsv
index bfa01bceb3..00777c9450 100644
--- a/scripts/module-size-limits.tsv
+++ b/scripts/module-size-limits.tsv
@@ -36,7 +36,7 @@ src/core/embedding-migration.ts 1587 ratchet new row: crossed 1500 in v0.46.25.0
src/core/github-source.ts 1530 ratchet new row: crossed the 1500 unlisted cap in v0.46.23.0 review fix wave (scope-state gating, client hardening, symlink containment); merged reliability/shared-skills source integration; managed sweep lease wrapper; fix wave 3 lane A: config parser peeled to github-source-config.ts (-47), +account pin wiring and pinned-installation refresh
src/commands/hook.ts 1932 ratchet cathedral-5 heartbeat extraction offsets part of the BrainBench-seam growth; grown v0.46.26.0 megawave hooks-ipc (#4245); +108 monthly backup check: banner + gated session-start note + detached spawn (backup/status-file readers); +28 ship-review egress hardening: per-harness capture dispatch (capture-spec), memorable gate + receipt + relay block, fail-closed unscanned/newest-guess skips; +79 ambient-writeback WP4: hookStop bank step (gate -> bankWritebackTurn -> IPC flush; gate/bank logic live in core/facts + corpus-segments); +41 adversarial fix wave: wide-tail retry when the 128KB window misses the user turn, by-design heartbeat outcome classes, source-in-name banking; +11 #5413 session-end skips claude-cli self-transcripts; +11 #5701: hook lanes pass allowOversize so a long session reaches the bounded tail read; +1 #5371: the stop-hook dirty probe ignores physical-root ownership metadata (root-metadata.ts, engine-free); 2 core memory: user-prompt context-pressure notice wiring (logic in core/context/pressure.ts; session-start composition in core/context/session-start-output.ts); +3 fix wave 11 W2.1 #6091: PreCompact/SessionEnd capture-time consent record calls (logic in core/context/capture-consent.ts); +5 fix wave 11 W2.9 #6083: the three detached-push call sites skip a managed canonical worktree (push_managed_coordinator) + import; +2 fix wave 11 integration: W1 router help guard import beside the W2 managed-root import; +2 fix wave 13 P4.9 #6399: a header-only Codex rollout ends empty_session, not parser_drift; +3 W14 P4.16 (#5799): banner and SessionStart note read livePushStatuses (predicate in core/workspace-push.ts); +1 W15 P5.7 (#4992): gitChildEnv import for the hook git probes (launches moved onto core/spawn.ts)
src/core/chunkers/code.ts 1602 ratchet new row: crossed the 1500 unlisted cap in v0.46.26.0 megawave (decorated-python defs #3821, version-gate + timeout chunker fixes); grown wave-g (#4511): named defs never folded into merged chunks; grown #4669: skip WASM parse for languages without TOP_LEVEL_TYPES; +6 N13-1: CodeChunkMetadata.definesFunction field + merge-guard stamp (predicate lives in def-types.ts); +10 Lua grammar swap: GRAMMAR_REVISIONS + chunkerStamp() (per-language re-chunk gate); +4: CodeChunkOptions.timeoutMs (per-call parse cap; markdown fences parse under a short cap) and the "Parsing failed" → ChunkerTimeoutError mapping in parseWithTimeout
-src/core/config.ts 2012 ratchet +2 W5: search.page_rank_cut / page_rank_cut_factor KNOWN_CONFIG_KEYS rows (read in search/page-rank-cut.ts); +3 W3 confidence-gated reranking: search.reranker.gate / gate_min_gap KNOWN_CONFIG_KEYS rows (values parsed in search/crag.ts); re-summed at the W3 merge onto master v0.60.169.0 (1951 measured); +1 budgeted delivery PR 1: the search.auto_packing KNOWN_CONFIG_KEYS row (values validated in search/evidence-packing.ts); +1 #6278: persistence.sync_preparation_ms/maintenance_preparation_ms/preparation_ceiling_ms/max_preparation_attempts/preparation_deadlines key row (logic in persistence/preparation-budget.ts, switches.ts); +22 fix wave 11 W6.2/W6.3 (#5989, #6132): search.cjk_keyword_deadline_ms and search.hnsw_iterative_scan type fields, KNOWN_CONFIG_KEYS rows and the mergeSearchScanKnobs helper that keeps loadConfigWithEngine under its function-size baseline (logic in search/cjk-keyword-deadline.ts, search/hnsw-iterative-scan.ts); +8 #5988: sync.holds/hold_cap/hold_escalate_count/hold_escalate_pct/parser_regression key registration (read by persistence/sync-holds.ts); +3 agent operator wave A4: GBrainConfig.consent file-plane slot + 2 consent.preapprove.* key rows (logic in core/consent.ts); +1 System One v1: decide.* key prefix (validated by ai/decide/config.ts); new row: crossed the 1500 unlisted cap in v0.46.26.0 megawave (spend-controls hint #3703, config-set validation); +3 wave G #3974: sync.include_working_tree key; grown wave-g (#4540 #4494 #4415): extractor caps + intent-pattern config keys; +1 chat-connectors: connectors. config prefix; wave-k: config-table snapshot serving the DB-plane reads (#3980 + #2119 merge); +8: loadConfig hook for ~/.gbrain/.env, loader lives in gbrain-env-file.ts (#3893); +17: litellm/together key-fold slots (#3904 reimpl: two GBrainConfig fields + KNOWN_CONFIG_KEYS rows); +1: link_resolution.cross_source key (#3908); +4 v0.47 gmail-loops: loops.extraction_enabled key; +1: pricing.overrides key (#4633 adoption); +7 #4667 adoption: sync.exclude key registration; +4: eval fix wave keys (quote_verify + 3 rescue knobs); +memorable file-plane key registration (integrations.memorable.enabled + consent-event doc); +33 ambient-writeback: memory.* + brain.audience key registration + GBrainConfig.memory mirror slot (resolvers live in facts/writeback-config.ts); +38 2026-08 wave: retrieval_reflex_volunteer key + env mapping (volunteer-arm kill switch) + E5a registration of the 10 adaptive_return*/autocut*/crag_* search (incl. adversarial batch isEnvDisabled dedup); ambient-writeback (master merge): facts/writeback-config.ts); new row: crossed the 1500 unlisted cap in v0.46.26.0 megawave; prior growth: sync/intent/chat-connectors/litellm/pricing/loops key folds; +34: #4702 content_sanity.disabled_patterns (type + DB-plane parse/merge + key registration); composition true-up (fix-wave multi-train) | merged v0.48.1.0: master #4788 writeback keys + wave #4702/#4748 keys; master: | merged v0.48.1.0 true-up; ranker wave v0.48.4.0: +4 KNOWN_CONFIG_KEYS rows (+8); +5 #4895: CWD_DOTENV_FILES gains the per-NODE_ENV .local variants Bun auto-loads; +2 #5003: sync.include_hidden key registration; +57 #4605: search.* registry reconciled to the keys mode.ts reads (+20 knob rows, +4 direct-read singletons) + GBrainConfig.search slot + adaptive_return* DB-plane merge; +2 pre-landing review: fts.reindex_in_progress key registration (#4795 marker escape hatch); +4 #4987: auto_timeline key registration (the documented off switch was rejected as unknown); lowered to 1793: GHSA wave v0.50.5.0 moved CWD_DOTENV_FILES + dotenvValuesForKey into core/env-trust.ts (-49, re-exported); re-summed to the merged line count after merging master v0.50.2.0 (#5122) with the v0.50.5.0 security wave; fix wave 3 x fix wave 2 (v0.60.5.0) composition: +1 at the merge; evidence delivery: 5 registered config keys + comment (+7); +2 #5691: embedding_query_prefix key registration; evidence delivery auto v2: search.return_budget_conversation key row (+1); +1 #5836: facts.entity_inference key row; +6 #5824: search.vector_legacy_guard key row + GBrainConfig.search slot + DB-plane merge; +3 wave 8 lane D1 #5885: takes.auto_embed key row; +3 #5232: GBrainConfig.persistence.write_wait_ms file-plane slot + key row (resolver in persistence/write-wait.ts); +2 F4b: planner.* and import.analyze_every_pages keys; +3 cat40 cost wave C1 (garrytan/gbrain-evals#57 follow-ups): mcp.result_rows GBrainConfig slot + key row (resolver in mcp/result-rows.ts); v0.60.46.0 merge: both waves' +3 compose (1824 + 3 = 1827 measured); +4 #5984: sync.bulk, sync.bulk_size, sync.bulk_max_txn_ms known keys; v0.60.48.0 merge: #5984 growth re-summed over v0.60.47.0 (1838 measured); +3 retrieval feedback: the feedback keys in KNOWN_CONFIG_KEYS; 2 engine graduation (GBRA-50 G3): GBrainConfig.migrate.graduation file-plane opt-out slot + key row (read by commands/migrate-graduation.ts); P3 x engine graduation composition: both deltas re-summed at the merge; 2 Lane D: facts.drain_budget_usd, facts.drain_daily_budget_usd, facts.drain_max_jobs key registration (validated in core/facts/drain.ts); +2 engine graduation (GBRA-50 G3): GBrainConfig.migrate.graduation file-plane opt-out slot + key row (read by commands/migrate-graduation.ts); P3 x foundations-2 composition: deltas re-summed at the merge; 2 Lane D: facts.drain_budget_usd, facts.drain_daily_budget_usd, facts.drain_max_jobs key registration (validated in core/facts/drain.ts); +2 engine graduation (GBRA-50 G3): GBrainConfig.migrate.graduation file-plane opt-out slot + key row (read by commands/migrate-graduation.ts); +1 GBRA-49: graph.* key prefix (graph.edge_validity, read by link-validity.ts); P3 x P1 (v0.60.57.0) composition: deltas re-summed at the merge; 2 Lane D: facts.drain_budget_usd, facts.drain_daily_budget_usd, facts.drain_max_jobs key registration (validated in core/facts/drain.ts); +2 engine graduation (GBRA-50 G3): GBrainConfig.migrate.graduation file-plane opt-out slot + key row (read by commands/migrate-graduation.ts); +1 GBRA-49: graph.* key prefix (graph.edge_validity, read by link-validity.ts); +3 P7 search.relational_planner / search.relational_orient_onehop key registration; +2 P7 search.relational_chain_slots key registration; P3 x P7 (v0.60.60.0) composition: deltas re-summed at the merge; 2 Lane D: facts.drain_budget_usd, facts.drain_daily_budget_usd, facts.drain_max_jobs key registration (validated in core/facts/drain.ts); +2 engine graduation (GBRA-50 G3): GBrainConfig.migrate.graduation file-plane opt-out slot + key row (read by commands/migrate-graduation.ts); +1 GBRA-49: graph.* key prefix (graph.edge_validity, read by link-validity.ts); +3 P7 search.relational_planner / search.relational_orient_onehop key registration; +2 P7 search.relational_chain_slots key registration; +3 agent operator follow-up Item 2: mcp.allow_session_widen (GBrainConfig.mcp slot + known key); P3 x aow-followup composition: deltas re-summed at the merge; 2 Lane D: facts.drain_budget_usd, facts.drain_daily_budget_usd, facts.drain_max_jobs key registration (validated in core/facts/drain.ts); +2 engine graduation (GBRA-50 G3): GBrainConfig.migrate.graduation file-plane opt-out slot + key row (read by commands/migrate-graduation.ts); +1 GBRA-49: graph.* key prefix (graph.edge_validity, read by link-validity.ts); +3 P7 search.relational_planner / search.relational_orient_onehop key registration; +2 P7 search.relational_chain_slots key registration; +3 agent operator follow-up Item 2: mcp.allow_session_widen (GBrainConfig.mcp slot + known key); +2 entity mention index: mentions.auto_link, mentions.entity_types, mentions.ignore key rows (resolver in core/mentions/policy.ts); cat40 entity wave merge with v0.60.61.0 (1853 measured); P3 x cat40-entity-wave composition: deltas re-summed at the merge; +6 fix wave lane B3: chat_fallback_on_refusal (GBrainConfig slot, GBRAIN_CHAT_FALLBACK_ON_REFUSAL env fold, known key); +2 W-B4: shared_skills.inventory.* known keys (logic in shared-skills/inventory-limits.ts); +2 fix wave 9 lane B #4921: ai.chat.per_turn_timeout_ms known key; +1 wave 9 lane W #5363: cycle.consolidate.cluster_threshold key row; +1 #5984 lanes: sync.lanes key registration; +2 P8: dream.quote_verify and think.quote_verify known keys; +2 P8: GBrainConfig.mcp.advertised_surface interface slot (resolver in mcp/surface.ts); +2 fix wave 10 lane L1 #4907: cycle.synthesize_concepts.budget_usd registered (validation in cycle/phase-config-values.ts); +2 #5958: dream.propose_takes.call_timeout_ms registered; 3 core memory: memory.core.* and memory.pressure.* known keys; +15 P5: wanted_pages.enabled/remote, line_grammar.enabled/allow_undeclared_types/effective_ranges and put_page.similar_pages key rows (logic in wanted-links.ts, line-grammar.ts, similar-pages.ts); +1 P2 extraction.date_grounding / facts.attribution keys; +1 #6188: fences.normalize registered in KNOWN_CONFIG_KEYS; +2 #6188: fences.repair.max_usd_per_page/per_day key rows; +1 fix wave 12 W2.3 #6231: facts.page_write_notability_filter key row (resolver in facts/notability-filter.ts); +1 #6317: persistence.single_consumer key row (logic in persistence/switches.ts, consumer-election.ts); +2 newer mentions on context_pack cards: mentions.newer_on_cards key row (logic in mentions/newer-mentions.ts); master v0.60.136.0 merge into #5575 memory trust (both sides kept); +1 #5329 (W14 PR3): chronicle.max_events_per_page registered in KNOWN_CONFIG_KEYS (validation in chronicle/config.ts); +2 C1/C2 memory proof wave: search.evidence_date_header + facts.candidate_fusion registry rows; +1 facts.supersession_thresholds registry row (per-model supersession calibration); +1 C4: models.standing_questions key row; +1 search.entity_anchoring key registration (default off; search/entity-anchor.ts); +1 search.query_facts_arm key registration (default off; search/facts-arm.ts); re-summed at the master 6ccf30c3e merge (1871 integration + 1868 master - 1865 base); +1 search.temporal_fact_reserve key registration (default off; search/facts-arm.ts); +1 fix wave 13 PR2: persistence.publication_ceiling_ms (P2.1/P2.3); v0.60.165.0 merge: W14 PR4 +7 and master +2 compose (1947 measured); +1 memory proof wave 2 W1: the recall.question_admission KNOWN_CONFIG_KEYS row (values validated in facts/question-recall.ts); +2 Cat 40 Hard fix wave (#6271) on top: mentions.alias_deny/multiword_aliases/sibling_merge and search.alias_fanout_max/demote_generated KNOWN_CONFIG_KEYS rows (1950 measured); +1 wave 15 P7.1 #5213: cycle.propose_takes.types KNOWN_CONFIG_KEYS row (parse + filter live in cycle/propose-takes.ts); +1 wave 15 P7.2 #6451: autopilot.git_pull KNOWN_CONFIG_KEYS row (read in persistence/automatic-sync-policy.ts); +1 wave 15 P7.3 #6369: cycle.lint.enabled KNOWN_CONFIG_KEYS row (read in cycle/lint-fix-setting.ts); +2 wave 15 P7.4 #5461: think.pages_budget_chars / think.excerpt_ceiling_chars KNOWN_CONFIG_KEYS rows (validation in think/pages-budget.ts); +6 wave 16 G5.1 (#6495): search.keyword_statement_timeout_ms type field, DB merge and KNOWN_CONFIG_KEYS row, toEngineConfig carries it (range + resolver live in postgres-engine/keyword-statement-timeout.ts); +1 GBRA-81 item 1: search.mode_source registered; +1 GBRA-60 S1: search.diverse_pool_depth in the known search keys; +3 #6643: sync.knock_on_refreeze_limit / sync.knock_on_run_limit KNOWN_CONFIG_KEYS rows (read by persistence/sync-run.ts knockOnLimits); +3 #6696: KNOWN_CONFIG_KEYS rows for persistence.maintenance.compaction_stale_hours and refusal_breaker_threshold; +1 wave 5 D5: context.proactive_brief KNOWN_CONFIG_KEYS row (read in context/proactive-brief.ts); +3 Cat 40 next wave part 1: KNOWN_CONFIG_KEYS rows for entity.names_references + entity.record_types + entity.row_page_status (one line), mcp.instructions_governing_rule and search.long_page_unit (re-summed at the 0.60.242.0 merge: master 1975 + 3); +1 wave 17 (#6667): cycle.consolidate.enabled KNOWN_CONFIG_KEYS row (read in cycle/phases/consolidate.ts); +2 Wave B PR 1: pages.segmented_storage and the segmented ceiling/retention keys (page-body/limits.ts); merge v0.60.249.0: Wave B PR 1 and master growth compose at 1981; +1 #6297: dream.patterns.min_interval_hours / child_read_budget_kb known keys; +1 #5012: loops.updates_require_reciprocity known key; +1 wave 18b lane 2 (#6495): search.keyword_timeout_negative_cache_seconds KNOWN_CONFIG_KEYS row; integrated at wave 18b: master 1981 + 4 (lanes 2, 3, 5 known keys); +1 #6948: sync.origin_twins.auto_resolve KNOWN_CONFIG_KEYS row (read in repair/origin-twins-heal.ts); +1 #6948 sweep C-9: facts.absorb_retry.max_resubmits KNOWN_CONFIG_KEYS row (read in facts/dead-absorb-retry.ts); +1 #6907: backup.remote_timeout_ms KNOWN_CONFIG_KEYS row (resolver in backup/repository.ts); +1 at the #6712 PR 4b merge onto master v0.60.310.0 (both sides added a key); +3 #7130: sync.max_deletes / sync.max_delete_ratio / purge.retention_hours KNOWN_CONFIG_KEYS rows and the two per-source cap prefixes (parsers live in core/sync-reconcile.ts); +2 GBRA-154: search.collapse / search.rank_priors KNOWN_CONFIG_KEYS rows (read in search/mode.ts); +1 GBRA-150: sync.metafile_pages KNOWN_CONFIG_KEYS row (read in core/sync.ts); +1 GBRA-159: visibility.honor_aliases KNOWN_CONFIG_KEYS row (read in search/private-visibility.ts); +4 GBRA-156 warm CLI socket: GBrainConfig.serve_cli_socket slot and the published-config.ts import/re-export (snapshot-only merge and MERGED_CONFIG_BY_ENGINE live in core/published-config.ts); re-summed at the GBRA-159 hotfix merge (2000 measured); +2 #7242 GBrainConfig.minions.terminal_hook (interface field); #7252 merge of master v0.60.343.0: both sides grew the file, re-summed (2002 measured); +1 GBRA-155: entity.name_variants KNOWN_CONFIG_KEYS row (read in verbs/entity-variants.ts); +2 GBRA-161: the generations.* KNOWN_CONFIG_KEYS rows and their comment (bounds and reader in generations/config.ts); +1 GBRA-156: search.evidence_tail_trim KNOWN_CONFIG_KEYS row (read in search/evidence-tail-trim.ts); +2 GBRA-175: self_upgrade.channel (the GBrainConfig field and its KNOWN_CONFIG_KEYS row; resolved in core/self-upgrade.ts); re-summed at the master 440eeef6 merge (2009 measured); +2 GBRA-156 vector prewarm: GBrainConfig.serve_vector_prewarm slot (snapshot merge lives in core/published-config.ts); +1 GBRA-95 G7a: storage.git_lfs KNOWN_CONFIG_KEYS row (read in persistence/git-declared.ts); re-summed at the v0.60.449.0 merge (2012 measured)
+src/core/config.ts 2013 ratchet +2 W5: search.page_rank_cut / page_rank_cut_factor KNOWN_CONFIG_KEYS rows (read in search/page-rank-cut.ts); +3 W3 confidence-gated reranking: search.reranker.gate / gate_min_gap KNOWN_CONFIG_KEYS rows (values parsed in search/crag.ts); re-summed at the W3 merge onto master v0.60.169.0 (1951 measured); +1 budgeted delivery PR 1: the search.auto_packing KNOWN_CONFIG_KEYS row (values validated in search/evidence-packing.ts); +1 #6278: persistence.sync_preparation_ms/maintenance_preparation_ms/preparation_ceiling_ms/max_preparation_attempts/preparation_deadlines key row (logic in persistence/preparation-budget.ts, switches.ts); +22 fix wave 11 W6.2/W6.3 (#5989, #6132): search.cjk_keyword_deadline_ms and search.hnsw_iterative_scan type fields, KNOWN_CONFIG_KEYS rows and the mergeSearchScanKnobs helper that keeps loadConfigWithEngine under its function-size baseline (logic in search/cjk-keyword-deadline.ts, search/hnsw-iterative-scan.ts); +8 #5988: sync.holds/hold_cap/hold_escalate_count/hold_escalate_pct/parser_regression key registration (read by persistence/sync-holds.ts); +3 agent operator wave A4: GBrainConfig.consent file-plane slot + 2 consent.preapprove.* key rows (logic in core/consent.ts); +1 System One v1: decide.* key prefix (validated by ai/decide/config.ts); new row: crossed the 1500 unlisted cap in v0.46.26.0 megawave (spend-controls hint #3703, config-set validation); +3 wave G #3974: sync.include_working_tree key; grown wave-g (#4540 #4494 #4415): extractor caps + intent-pattern config keys; +1 chat-connectors: connectors. config prefix; wave-k: config-table snapshot serving the DB-plane reads (#3980 + #2119 merge); +8: loadConfig hook for ~/.gbrain/.env, loader lives in gbrain-env-file.ts (#3893); +17: litellm/together key-fold slots (#3904 reimpl: two GBrainConfig fields + KNOWN_CONFIG_KEYS rows); +1: link_resolution.cross_source key (#3908); +4 v0.47 gmail-loops: loops.extraction_enabled key; +1: pricing.overrides key (#4633 adoption); +7 #4667 adoption: sync.exclude key registration; +4: eval fix wave keys (quote_verify + 3 rescue knobs); +memorable file-plane key registration (integrations.memorable.enabled + consent-event doc); +33 ambient-writeback: memory.* + brain.audience key registration + GBrainConfig.memory mirror slot (resolvers live in facts/writeback-config.ts); +38 2026-08 wave: retrieval_reflex_volunteer key + env mapping (volunteer-arm kill switch) + E5a registration of the 10 adaptive_return*/autocut*/crag_* search (incl. adversarial batch isEnvDisabled dedup); ambient-writeback (master merge): facts/writeback-config.ts); new row: crossed the 1500 unlisted cap in v0.46.26.0 megawave; prior growth: sync/intent/chat-connectors/litellm/pricing/loops key folds; +34: #4702 content_sanity.disabled_patterns (type + DB-plane parse/merge + key registration); composition true-up (fix-wave multi-train) | merged v0.48.1.0: master #4788 writeback keys + wave #4702/#4748 keys; master: | merged v0.48.1.0 true-up; ranker wave v0.48.4.0: +4 KNOWN_CONFIG_KEYS rows (+8); +5 #4895: CWD_DOTENV_FILES gains the per-NODE_ENV .local variants Bun auto-loads; +2 #5003: sync.include_hidden key registration; +57 #4605: search.* registry reconciled to the keys mode.ts reads (+20 knob rows, +4 direct-read singletons) + GBrainConfig.search slot + adaptive_return* DB-plane merge; +2 pre-landing review: fts.reindex_in_progress key registration (#4795 marker escape hatch); +4 #4987: auto_timeline key registration (the documented off switch was rejected as unknown); lowered to 1793: GHSA wave v0.50.5.0 moved CWD_DOTENV_FILES + dotenvValuesForKey into core/env-trust.ts (-49, re-exported); re-summed to the merged line count after merging master v0.50.2.0 (#5122) with the v0.50.5.0 security wave; fix wave 3 x fix wave 2 (v0.60.5.0) composition: +1 at the merge; evidence delivery: 5 registered config keys + comment (+7); +2 #5691: embedding_query_prefix key registration; evidence delivery auto v2: search.return_budget_conversation key row (+1); +1 #5836: facts.entity_inference key row; +6 #5824: search.vector_legacy_guard key row + GBrainConfig.search slot + DB-plane merge; +3 wave 8 lane D1 #5885: takes.auto_embed key row; +3 #5232: GBrainConfig.persistence.write_wait_ms file-plane slot + key row (resolver in persistence/write-wait.ts); +2 F4b: planner.* and import.analyze_every_pages keys; +3 cat40 cost wave C1 (garrytan/gbrain-evals#57 follow-ups): mcp.result_rows GBrainConfig slot + key row (resolver in mcp/result-rows.ts); v0.60.46.0 merge: both waves' +3 compose (1824 + 3 = 1827 measured); +4 #5984: sync.bulk, sync.bulk_size, sync.bulk_max_txn_ms known keys; v0.60.48.0 merge: #5984 growth re-summed over v0.60.47.0 (1838 measured); +3 retrieval feedback: the feedback keys in KNOWN_CONFIG_KEYS; 2 engine graduation (GBRA-50 G3): GBrainConfig.migrate.graduation file-plane opt-out slot + key row (read by commands/migrate-graduation.ts); P3 x engine graduation composition: both deltas re-summed at the merge; 2 Lane D: facts.drain_budget_usd, facts.drain_daily_budget_usd, facts.drain_max_jobs key registration (validated in core/facts/drain.ts); +2 engine graduation (GBRA-50 G3): GBrainConfig.migrate.graduation file-plane opt-out slot + key row (read by commands/migrate-graduation.ts); P3 x foundations-2 composition: deltas re-summed at the merge; 2 Lane D: facts.drain_budget_usd, facts.drain_daily_budget_usd, facts.drain_max_jobs key registration (validated in core/facts/drain.ts); +2 engine graduation (GBRA-50 G3): GBrainConfig.migrate.graduation file-plane opt-out slot + key row (read by commands/migrate-graduation.ts); +1 GBRA-49: graph.* key prefix (graph.edge_validity, read by link-validity.ts); P3 x P1 (v0.60.57.0) composition: deltas re-summed at the merge; 2 Lane D: facts.drain_budget_usd, facts.drain_daily_budget_usd, facts.drain_max_jobs key registration (validated in core/facts/drain.ts); +2 engine graduation (GBRA-50 G3): GBrainConfig.migrate.graduation file-plane opt-out slot + key row (read by commands/migrate-graduation.ts); +1 GBRA-49: graph.* key prefix (graph.edge_validity, read by link-validity.ts); +3 P7 search.relational_planner / search.relational_orient_onehop key registration; +2 P7 search.relational_chain_slots key registration; P3 x P7 (v0.60.60.0) composition: deltas re-summed at the merge; 2 Lane D: facts.drain_budget_usd, facts.drain_daily_budget_usd, facts.drain_max_jobs key registration (validated in core/facts/drain.ts); +2 engine graduation (GBRA-50 G3): GBrainConfig.migrate.graduation file-plane opt-out slot + key row (read by commands/migrate-graduation.ts); +1 GBRA-49: graph.* key prefix (graph.edge_validity, read by link-validity.ts); +3 P7 search.relational_planner / search.relational_orient_onehop key registration; +2 P7 search.relational_chain_slots key registration; +3 agent operator follow-up Item 2: mcp.allow_session_widen (GBrainConfig.mcp slot + known key); P3 x aow-followup composition: deltas re-summed at the merge; 2 Lane D: facts.drain_budget_usd, facts.drain_daily_budget_usd, facts.drain_max_jobs key registration (validated in core/facts/drain.ts); +2 engine graduation (GBRA-50 G3): GBrainConfig.migrate.graduation file-plane opt-out slot + key row (read by commands/migrate-graduation.ts); +1 GBRA-49: graph.* key prefix (graph.edge_validity, read by link-validity.ts); +3 P7 search.relational_planner / search.relational_orient_onehop key registration; +2 P7 search.relational_chain_slots key registration; +3 agent operator follow-up Item 2: mcp.allow_session_widen (GBrainConfig.mcp slot + known key); +2 entity mention index: mentions.auto_link, mentions.entity_types, mentions.ignore key rows (resolver in core/mentions/policy.ts); cat40 entity wave merge with v0.60.61.0 (1853 measured); P3 x cat40-entity-wave composition: deltas re-summed at the merge; +6 fix wave lane B3: chat_fallback_on_refusal (GBrainConfig slot, GBRAIN_CHAT_FALLBACK_ON_REFUSAL env fold, known key); +2 W-B4: shared_skills.inventory.* known keys (logic in shared-skills/inventory-limits.ts); +2 fix wave 9 lane B #4921: ai.chat.per_turn_timeout_ms known key; +1 wave 9 lane W #5363: cycle.consolidate.cluster_threshold key row; +1 #5984 lanes: sync.lanes key registration; +2 P8: dream.quote_verify and think.quote_verify known keys; +2 P8: GBrainConfig.mcp.advertised_surface interface slot (resolver in mcp/surface.ts); +2 fix wave 10 lane L1 #4907: cycle.synthesize_concepts.budget_usd registered (validation in cycle/phase-config-values.ts); +2 #5958: dream.propose_takes.call_timeout_ms registered; 3 core memory: memory.core.* and memory.pressure.* known keys; +15 P5: wanted_pages.enabled/remote, line_grammar.enabled/allow_undeclared_types/effective_ranges and put_page.similar_pages key rows (logic in wanted-links.ts, line-grammar.ts, similar-pages.ts); +1 P2 extraction.date_grounding / facts.attribution keys; +1 #6188: fences.normalize registered in KNOWN_CONFIG_KEYS; +2 #6188: fences.repair.max_usd_per_page/per_day key rows; +1 fix wave 12 W2.3 #6231: facts.page_write_notability_filter key row (resolver in facts/notability-filter.ts); +1 #6317: persistence.single_consumer key row (logic in persistence/switches.ts, consumer-election.ts); +2 newer mentions on context_pack cards: mentions.newer_on_cards key row (logic in mentions/newer-mentions.ts); master v0.60.136.0 merge into #5575 memory trust (both sides kept); +1 #5329 (W14 PR3): chronicle.max_events_per_page registered in KNOWN_CONFIG_KEYS (validation in chronicle/config.ts); +2 C1/C2 memory proof wave: search.evidence_date_header + facts.candidate_fusion registry rows; +1 facts.supersession_thresholds registry row (per-model supersession calibration); +1 C4: models.standing_questions key row; +1 search.entity_anchoring key registration (default off; search/entity-anchor.ts); +1 search.query_facts_arm key registration (default off; search/facts-arm.ts); re-summed at the master 6ccf30c3e merge (1871 integration + 1868 master - 1865 base); +1 search.temporal_fact_reserve key registration (default off; search/facts-arm.ts); +1 fix wave 13 PR2: persistence.publication_ceiling_ms (P2.1/P2.3); v0.60.165.0 merge: W14 PR4 +7 and master +2 compose (1947 measured); +1 memory proof wave 2 W1: the recall.question_admission KNOWN_CONFIG_KEYS row (values validated in facts/question-recall.ts); +2 Cat 40 Hard fix wave (#6271) on top: mentions.alias_deny/multiword_aliases/sibling_merge and search.alias_fanout_max/demote_generated KNOWN_CONFIG_KEYS rows (1950 measured); +1 wave 15 P7.1 #5213: cycle.propose_takes.types KNOWN_CONFIG_KEYS row (parse + filter live in cycle/propose-takes.ts); +1 wave 15 P7.2 #6451: autopilot.git_pull KNOWN_CONFIG_KEYS row (read in persistence/automatic-sync-policy.ts); +1 wave 15 P7.3 #6369: cycle.lint.enabled KNOWN_CONFIG_KEYS row (read in cycle/lint-fix-setting.ts); +2 wave 15 P7.4 #5461: think.pages_budget_chars / think.excerpt_ceiling_chars KNOWN_CONFIG_KEYS rows (validation in think/pages-budget.ts); +6 wave 16 G5.1 (#6495): search.keyword_statement_timeout_ms type field, DB merge and KNOWN_CONFIG_KEYS row, toEngineConfig carries it (range + resolver live in postgres-engine/keyword-statement-timeout.ts); +1 GBRA-81 item 1: search.mode_source registered; +1 GBRA-60 S1: search.diverse_pool_depth in the known search keys; +3 #6643: sync.knock_on_refreeze_limit / sync.knock_on_run_limit KNOWN_CONFIG_KEYS rows (read by persistence/sync-run.ts knockOnLimits); +3 #6696: KNOWN_CONFIG_KEYS rows for persistence.maintenance.compaction_stale_hours and refusal_breaker_threshold; +1 wave 5 D5: context.proactive_brief KNOWN_CONFIG_KEYS row (read in context/proactive-brief.ts); +3 Cat 40 next wave part 1: KNOWN_CONFIG_KEYS rows for entity.names_references + entity.record_types + entity.row_page_status (one line), mcp.instructions_governing_rule and search.long_page_unit (re-summed at the 0.60.242.0 merge: master 1975 + 3); +1 wave 17 (#6667): cycle.consolidate.enabled KNOWN_CONFIG_KEYS row (read in cycle/phases/consolidate.ts); +2 Wave B PR 1: pages.segmented_storage and the segmented ceiling/retention keys (page-body/limits.ts); merge v0.60.249.0: Wave B PR 1 and master growth compose at 1981; +1 #6297: dream.patterns.min_interval_hours / child_read_budget_kb known keys; +1 #5012: loops.updates_require_reciprocity known key; +1 wave 18b lane 2 (#6495): search.keyword_timeout_negative_cache_seconds KNOWN_CONFIG_KEYS row; integrated at wave 18b: master 1981 + 4 (lanes 2, 3, 5 known keys); +1 #6948: sync.origin_twins.auto_resolve KNOWN_CONFIG_KEYS row (read in repair/origin-twins-heal.ts); +1 #6948 sweep C-9: facts.absorb_retry.max_resubmits KNOWN_CONFIG_KEYS row (read in facts/dead-absorb-retry.ts); +1 #6907: backup.remote_timeout_ms KNOWN_CONFIG_KEYS row (resolver in backup/repository.ts); +1 at the #6712 PR 4b merge onto master v0.60.310.0 (both sides added a key); +3 #7130: sync.max_deletes / sync.max_delete_ratio / purge.retention_hours KNOWN_CONFIG_KEYS rows and the two per-source cap prefixes (parsers live in core/sync-reconcile.ts); +2 GBRA-154: search.collapse / search.rank_priors KNOWN_CONFIG_KEYS rows (read in search/mode.ts); +1 GBRA-150: sync.metafile_pages KNOWN_CONFIG_KEYS row (read in core/sync.ts); +1 GBRA-159: visibility.honor_aliases KNOWN_CONFIG_KEYS row (read in search/private-visibility.ts); +4 GBRA-156 warm CLI socket: GBrainConfig.serve_cli_socket slot and the published-config.ts import/re-export (snapshot-only merge and MERGED_CONFIG_BY_ENGINE live in core/published-config.ts); re-summed at the GBRA-159 hotfix merge (2000 measured); +2 #7242 GBrainConfig.minions.terminal_hook (interface field); #7252 merge of master v0.60.343.0: both sides grew the file, re-summed (2002 measured); +1 GBRA-155: entity.name_variants KNOWN_CONFIG_KEYS row (read in verbs/entity-variants.ts); +2 GBRA-161: the generations.* KNOWN_CONFIG_KEYS rows and their comment (bounds and reader in generations/config.ts); +1 GBRA-156: search.evidence_tail_trim KNOWN_CONFIG_KEYS row (read in search/evidence-tail-trim.ts); +2 GBRA-175: self_upgrade.channel (the GBrainConfig field and its KNOWN_CONFIG_KEYS row; resolved in core/self-upgrade.ts); re-summed at the master 440eeef6 merge (2009 measured); +2 GBRA-156 vector prewarm: GBrainConfig.serve_vector_prewarm slot (snapshot merge lives in core/published-config.ts); +1 GBRA-95 G7a: storage.git_lfs KNOWN_CONFIG_KEYS row (read in persistence/git-declared.ts); re-summed at the v0.60.449.0 merge (2012 measured); +1 GBRA-224 W3: dream.write_deferral.enabled / embed.restamp.enabled KNOWN_CONFIG_KEYS row (read through heal-audit.ts healEnabled)
src/core/persistence/sync-run.ts 1686 ratchet new row: crossed the 1500 unlisted cap in #6643 (knock-on re-freeze, checkpoint revival, root cause and the truthful --retry-failed wait all drive the private cursor/gate machinery: holdUnderGate, freezeEntry, saveCursor); classification lives in sync-knock-on.ts, the checkpoint clause in checkpoint-validation.ts; peel the settle path (settleFailedRequest and its recoveries) into a sibling module next; +3 #6722: committed pages' size_state tallied into the cursor and the sync receipt size_states (logic in page-embedding-budget.ts addSizeState); merge v0.60.240.0: large pages and master growth compose at 1687; +2 #6694: the slug-mode checkpoint revival import and its doc line (predicate lives in persistence/sync-slug-mode.ts); +11 #6712 PR 3 (L7): a plain sync retries the recorded failure --retry-failed used to (retryRecordedFailure; the unchanged-refusal replay lives in persistence/sync-stop-class.ts replaysUnchangedRefusal), the moved-checkpoint and company content-refusal exceptions; #6712 PR 3 integration: lanes L7 (retryRecordedFailure, +19) and L8 (#6727 legacy-slug refusal line, #6735 timeout revival, +6) compose at 1762; +2 wave 18a integration: #6729 (lane 2, written against the 1745 ceiling) records identity downgrades in performManagedPass through noteIdentityDowngrades (logic in core/sync-identity-downgrades.ts), composed with master 1762; +14 Wave B PR 2: freezeEntry freezes a Markdown file over the read bound by reference (body_ref) and holdFailedFenceRequest holds a streamed refusal; both set freezeEntry/holdFailedFenceRequest locals (blob, oversize, rawHash) so they stay here, the hashing and preparation live in persistence/sync-streamed.ts and the hold in sync-screen.ts streamedRefusalHold; integrated at the master 4e29d0904 merge: master 1764 + Wave B PR 2 14 = 1778 measured; +4 #6948: freezeEntry holds an entry several live pages claim (hold in sync-screen.ts originConflictHold, verdict in persistence/origin-twins.ts); +1 #7167: managedDryRun reports the writer state (the import of persistence/sync-dry-run-writer.ts, where the read lives); +4 G3 git-canonical: freezeEntry reads a strict source's entry from its commit (pinnedBlob) and carries committedOnly to publication; both use freezeEntry locals (rule in persistence/sync-classify.ts)
src/core/bootstrap/harness.ts 2592 ratchet +29 live-PGLite-serve lane: LIVE_SERVE refusal ahead of source resolution + unpinned --token hooks (CI e2e fix); +46 wave review: resolveHookSource dep (serve-parity resolver + federated grant), --source shape validation, loud SOURCE_UNRESOLVED instead of a silent 'default'; +10: #4574 parseCodexBlockBearer http_headers shape + legacy bearer_token fallback; +4 at megawave/wave-k merge; +codex hooks lane: step-7 codex hooks.json + config.toml trust pair, removeHarness arm; +234 ambient-writeback WP3: kind:'instructions' targets (plan/apply/converge-off/remove/status probes, OV-A4 override pre-check) — splice/render mechanics live in instructions-block.ts; +59 adversarial fix wave: registrar-mode block suppression, converge-failure receipt tracking, MCP-confirmed guard before block install; +26 round-3 fixes: codex-lane MCP-confirmed guard + smoke-rollback block strip; master: | merged v0.48.1.0 true-up; +41 #4897 resolveImplicitSource dep + defaultResolveImplicitSource: hooks/token/receipt bind to the serve's implicit default source when --source is omitted; +23 #4586 statusHarness live claude-code mcp verdict (URL mismatch or same-scope non-HTTP registration reads failed, receipt untouched); shared-skills integration on company-ingestion base; +18 #5671: logAmbientPostureNotes helper (registrar note moved out of applyHarness + pre-consent warning when an explicit private facts default meets the HTTP harness; text shared with doctor in facts/writeback-config.ts); +24 #5893: rotation grant carry wiring and its rotationCarry/withheldOperationsNote helpers (carry rules live in token-mint.ts carryLegacyGrant); +6 #5878: --refresh-skills flag and status epoch line (refresh logic lives in harness-skills.ts); +7 #4618 seat: HarnessFlags.seat field, --seat/--no-seat parse via hooks.ts parseSeatFlags, GBRAIN_SEAT in the hook env; -119 #6082: plugin-lane detectors moved to plugin-lanes.ts (re-exported); +18 #6092/#6171: hook ownership identity on write/remove/converge, permission ownership carry, --remove --dry-run and the --status hook census (logic in hooks.ts + harness-hooks.ts); +5 D8 Codex slice: the Codex SessionEnd capture hook obeys the recorded consent (wireCodexCapture: hooks on, capture accepted, never registrar mode) and is disclosed in the consent block; -31 #6743: cleanup gate moved to harness-cleanup.ts; +8 #6798: supersededEnrollments dep (interface field + default) and the --status epoch hint printed only for a superseded enrollment (the brain read lives in harness-skills.ts brainSupersededEnrollments)
src/core/oauth-provider.ts 1236 ratchet new row: crossed the 1500 unlisted cap absorbing #3819 (DCR 400 invalid_client_metadata + scope filtering + custom-scheme redirect_uris + pseudo-scheme guard); merged v0.49: transactional grant enforcement shared with hosted grant policies; +1 #5222 resourceUrl option
@@ -47,4 +47,4 @@ src/commands/doctor/checks/extraction-sync.ts 1500 ratchet +7 GBRA-130 A-1: link
src/core/search/evidence-delivery.ts 1733 ratchet +5 W5: EvidencePlan.rankCut resolved with the plan (logic in search/page-rank-cut.ts); +20 W5 whole_pages: wholeCost prices a block as delivery would emit it whole (needs the private Block/enrichBlock internals) and the cut is wired before allocate (cutWholePages lives in search/page-rank-cut.ts); new row: crossed the 1500 unlisted cap at the #6367 merge (master 1479, its explicit-budget cap) by the C1 date header threaded through every block path, cap included; pagePlanHits (search/page-plan-hits.ts) and the header loader (evidence-date.ts blockDateHeaders) were peeled first; peel candidate: allocateCapped; +8 at the #6396 merge: page evidence text cut through the fence-chunk trust overlay and the caller minTrust floor (re-summed: our 1504 + master +8); +119 Cat 40 next wave F2: the search.long_page_unit policy (withLongPagePolicy, selectLongPages size preflight with page/byte/deadline limits) and the long-page fetch and fallback in deliverEvidence, kept in the shared seam the plan names (gbrain-evals docs/plans/2026-10-11-cat40-next-wave, F2); +17 F2 rework to the frozen-comparison policy: search.long_page_min_chars (rendered-body characters, default 20,000) read in withLongPagePolicy, a character count in the preflight, the rendered-body confirmation in deliverEvidence, and the long-page row exemption in capDeliveredSnippets (re-summed at the 0.60.225.0 merge: master 1537 + F2 136); +39 Wave B PR 2 lane 2b: planSegmentedBlock joins the windows search/segmented-evidence.ts reads around a segmented page's hits into one run-marked document (needs the private Doc/Piece/buildDoc/locateAnchor internals), planBlock's unit cut split into blockFromDoc for both, sections bounded by their run, selectionCost counts a gap between runs, and the fetch skips the whole-body fence overlay for a segmented page; +4 segmented pages read at once before planning (segmentedReads; the read is search/segmented-evidence.ts, the statements page-body/read-range.ts); +17 GBRA-156: tail trim plan flag, DeliverOptions.query, DeliveryMeta.tail_trim, the trim call and the frozen-hit score/query library fields (logic in search/evidence-tail-trim.ts; interface fields cannot move)
src/commands/config.ts 1524 ratchet new row: crossed the 1500 unlisted cap in wave 15 P7.4 #5461: set-time validation of think.pages_budget_chars / think.excerpt_ceiling_chars (range + parser live in core/think/pages-budget.ts), mirroring the cycle.consolidate.cluster_threshold hook; +1 wave 16 G5.1 (#6495): set-time refusal hook for search.keyword_statement_timeout_ms (check lives in commands/config/keyword-timeout-value.ts); +1 wave 18b lane 5 (#5012 item 6): search.contextual_retrieval prints the existing-pages hint after the write (text lives in commands/config/contextual-mode-hint.ts); +1 #6712 PR 2: retired/rollback sync key dispatch line (logic in core/sync-config-keys.ts handleSyncKeyConfig); +1 #6865: sync.slug_conflicts.auto_remove boolean validation at set time (refusal text in repair/slug-autoheal.ts); +1 #6948: sync.origin_twins.auto_resolve boolean validation at set time (refusal text in repair/origin-twins-heal.ts); +2 #6795: config set chat_model/expansion_model help line and the model-pin import (shadow report and file-pin unset live in commands/config/model-pin-shadow.ts); +1 #6712 PR 4b: sync.admission set-time hook (value logic in commands/config/sync-admission-value.ts); +4 #7130: set-time refusal hook for sync.max_deletes / sync.max_delete_ratio (and .source.<id>) / purge.retention_hours (check lives in core/sync-reconcile.ts deleteSafetyConfigRefusal); +1 GBRA-150: sync.metafile_pages set-time route (body in config/sync-metafile-pages-value.ts); re-summed at the v0.60.330.0 merge (1520 measured); +2 #7242 minions.terminal_hook file-plane key and its set branch (logic in minions/terminal-hook.ts); +1 GBRA-161: generations.* set-time route (refusal in commands/config/generations-values.ts); +1 GBRA-207 #7630: sync.repo_path set-time refusal hook (refusal in core/sync-config-keys.ts syncRepoPathRefusal)
src/commands/mcp-expose.ts 1512 ratchet hosted_option: Session carries the gbrain.io coaching notice on the first-receipt run and Tailscale/service friction exits (copy, refs and gating live in core/onboard/hosted-option.ts)
-src/core/behavior-change-notice.ts 1518 ratchet the BEHAVIOR_CHANGES table grows by one row per disclosed change: +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2); the behavior-change table split (#7607) retires this row
+src/core/behavior-change-notice.ts 1522 ratchet the BEHAVIOR_CHANGES table grows by one row per disclosed change: +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2), +4 the GBRA-224 W3 self-heal rows and their comment; the behavior-change table split (#7607) retires this row
diff --git a/src/commands/doctor/checks/dream-write-deferred.ts b/src/commands/doctor/checks/dream-write-deferred.ts
new file mode 100644
index 0000000000..38d66a71b5
--- /dev/null
+++ b/src/commands/doctor/checks/dream-write-deferred.ts
@@ -0,0 +1,32 @@
+/**
+ * dream_write_deferred (W3, GBRA-224, #7587): read-only view of the dream
+ * write deferrals (cycle/dream-write-deferral.ts). A deferral is an accepted
+ * consolidate or purge write that was still pending after its publish wait;
+ * the next passes reconcile it. Under the replay bound it is ok (the details
+ * list it); one that is still pending after the bound warns, naming the
+ * receipt and its read-only status command. Page class for doctor --alert.
+ */
+import type { BrainEngine } from '../../../core/engine.ts';
+import { DREAM_WRITE_DEFERRAL_ENABLED_KEY, DREAM_WRITE_DEFERRAL_MAX_REPLAYS, dreamWriteDeferralEnabled, readDreamWriteDeferrals, writeStatusCommand } from '../../../core/cycle/dream-write-deferral.ts';
+import type { Check } from '../../doctor.ts';
+import { agentFix } from '../check-fix.ts';
+
+export async function dreamWriteDeferredCheck(engine: BrainEngine): Promise<Check> {
+ const deferrals = await readDreamWriteDeferrals(engine);
+ const items = deferrals.map(entry => ({ phase: entry.phase, source_id: entry.source_id, request_id: entry.request_id,
+ replays: entry.replays, bound: DREAM_WRITE_DEFERRAL_MAX_REPLAYS, deferred_at: entry.deferred_at, status_command: writeStatusCommand(entry.request_id) }));
+ const escalated = items.filter(item => item.replays >= DREAM_WRITE_DEFERRAL_MAX_REPLAYS);
+ const details = { enabled: await dreamWriteDeferralEnabled(engine), bound: DREAM_WRITE_DEFERRAL_MAX_REPLAYS, pending: items.length, items };
+ if (escalated.length === 0) {
+ return { name: 'dream_write_deferred', status: 'ok',
+ message: items.length ? `${items.length} dream write(s) deferred and still reconciling (under the ${DREAM_WRITE_DEFERRAL_MAX_REPLAYS}-pass bound)` : 'No deferred dream writes', details };
+ }
+ const first = escalated[0]!;
+ return { name: 'dream_write_deferred', status: 'warn',
+ message: `${escalated.length} dream write(s) still pending after ${DREAM_WRITE_DEFERRAL_MAX_REPLAYS} passes: `
+ + escalated.slice(0, 3).map(item => `${item.phase} in ${item.source_id} (request_id ${item.request_id})`).join('; ')
+ + `. The phase submits nothing more for that source until the receipt ends. Read it with ${first.status_command}; `
+ + `if the writer is stuck, gbrain sources writer status --source ${first.source_id} --json names why. `
+ + `(${DREAM_WRITE_DEFERRAL_ENABLED_KEY}=false turns deferral off.)`,
+ details, fix: agentFix(['gbrain', 'write-request', '--', first.request_id], 'Read-only: the deferred write\'s receipt and why it has not committed.', 'dream_write_deferred') };
+}
diff --git a/src/commands/doctor/checks/embedding-restamp.ts b/src/commands/doctor/checks/embedding-restamp.ts
new file mode 100644
index 0000000000..96612418e0
--- /dev/null
+++ b/src/commands/doctor/checks/embedding-restamp.ts
@@ -0,0 +1,27 @@
+/**
+ * embedding_restamp_stalled (W3, GBRA-224): the free signature restamp
+ * (core/embedding-restamp.ts) failed EMBEDDING_RESTAMP_FAILURE_BOUND runs in a
+ * row. Read-only, from the heal audit; page class for doctor --alert. Pages
+ * whose vectors already match the current model keep reading as another
+ * model's space until it runs clean.
+ */
+import type { BrainEngine } from '../../../core/engine.ts';
+import { EMBEDDING_RESTAMP_ENABLED_KEY, EMBEDDING_RESTAMP_FAILURE_BOUND, restampEscalation } from '../../../core/embedding-restamp.ts';
+import { healEnabled } from '../../../core/heal-audit.ts';
+import type { Check } from '../../doctor.ts';
+import { agentFix } from '../check-fix.ts';
+
+export async function embeddingRestampStalledCheck(engine: BrainEngine): Promise<Check> {
+ const enabled = await healEnabled(engine, EMBEDDING_RESTAMP_ENABLED_KEY);
+ const escalation = enabled ? await restampEscalation(engine) : null;
+ const details = { enabled, bound: EMBEDDING_RESTAMP_FAILURE_BOUND, ...(escalation ? { last: escalation } : {}) };
+ if (!escalation) {
+ return { name: 'embedding_restamp_stalled', status: 'ok',
+ message: enabled ? 'The embedding signature restamp is running clean' : `The embedding signature restamp is off (${EMBEDDING_RESTAMP_ENABLED_KEY}=false)`, details };
+ }
+ return { name: 'embedding_restamp_stalled', status: 'warn',
+ message: `The free embedding signature restamp failed ${escalation.attempt} maintenance runs in a row (bound ${EMBEDDING_RESTAMP_FAILURE_BOUND}); last error: ${escalation.detail ?? 'unknown'}. `
+ + `Pages whose vectors already match ${escalation.subject} keep reading as another model's space until it runs clean. Fix the error, then run the embed phase once; `
+ + `${EMBEDDING_RESTAMP_ENABLED_KEY}=false turns the restamp off.`,
+ details, fix: agentFix(['gbrain', 'dream', '--phase', 'embed', '--json'], 'Runs the embed phase, which restamps first; free for the restamp itself, and embeds any stale chunks with the configured provider.', 'embedding_restamp_stalled') };
+}
diff --git a/src/commands/doctor/wave-checks.ts b/src/commands/doctor/wave-checks.ts
index 3cd61938dc..23dda1e7dc 100644
--- a/src/commands/doctor/wave-checks.ts
+++ b/src/commands/doctor/wave-checks.ts
@@ -244,6 +244,20 @@ export const WAVE_CHECKS: readonly WaveCheckSpec[] = [
instruction: 'Fix the cause, then reset the breaker with the command doctor prints.',
run: async engine => (await import('./checks/dream-breaker.ts')).dreamPaidLoopCheck(engine),
},
+ {
+ id: 'dream_write_deferred', resolution: 'operator', registration: 'wave',
+ count: d => (d.items ?? []).filter((item: { replays: number; bound: number }) => item.replays >= item.bound).length,
+ impact: 'A dream phase write is still pending after its replay bound, so the phase submits nothing more for that source',
+ instruction: 'Read the receipt with the `gbrain write-request` command doctor prints; if the writer is stuck, `gbrain sources writer status --source <id> --json` names why.',
+ run: async engine => (await import('./checks/dream-write-deferred.ts')).dreamWriteDeferredCheck(engine),
+ },
+ {
+ id: 'embedding_restamp_stalled', resolution: 'operator', registration: 'wave',
+ count: d => (d.last ? 1 : 0),
+ impact: 'The free embedding signature restamp keeps failing, so current vectors still read as another model\'s space',
+ instruction: 'Fix the error doctor prints, then run `gbrain dream --phase embed` once.',
+ run: async engine => (await import('./checks/embedding-restamp.ts')).embeddingRestampStalledCheck(engine),
+ },
{
id: 'writer_version', resolution: 'operator', registration: 'wave',
impact: 'A writer older than this release admitted or published a recent write',
diff --git a/src/commands/dream-reset-key.ts b/src/commands/dream-reset-key.ts
index 44fb4e2c3b..e0dd3a0a14 100644
--- a/src/commands/dream-reset-key.ts
+++ b/src/commands/dream-reset-key.ts
@@ -5,7 +5,8 @@
import type { BrainEngine } from '../core/engine.ts';
import {
countDeadDreamSubmissions, dreamBreakerBaseKey, dreamBreakerResetCommand, loadDreamBreakerThreshold,
- resetDreamBreakerKey, DREAM_BREAKER_CONFIG_KEY, DREAM_BREAKER_KEY_PREFIXES, DREAM_PATTERNS_SOURCE_KEY_PREFIX,
+ resetDreamBreakerKey, DREAM_BREAKER_CONFIG_KEY, DREAM_PATTERNS_SOURCE_KEY_PREFIX, DREAM_PHASE_KEY_PREFIX,
+ DREAM_RESETTABLE_KEY_PREFIXES, DREAM_SYNTH_FILE_KEY_PREFIX,
} from '../core/cycle/dream-breaker.ts';
import { setCliExitVerdict, writeJsonDocument } from '../core/cli-force-exit.ts';
import { opError } from '../core/ops/contract.ts';
@@ -19,6 +20,10 @@ whose submissions died ${'`'}${DREAM_BREAKER_CONFIG_KEY}${'`'} times (default 3)
Patterns deaths (and patterns runs cancelled at their timeout after paid work)
count under ${'`'}${DREAM_PATTERNS_SOURCE_KEY_PREFIX}<source id>${'`'}, whatever reflections each
run read; a completed run resets it, so only consecutive deaths trip it.
+Synthesize deaths also count per transcript under
+${'`'}${DREAM_SYNTH_FILE_KEY_PREFIX}<source id>:<file>${'`'}, so a transcript that grows between
+dying runs still trips it. ${'`'}${DREAM_PHASE_KEY_PREFIX}<phase>:<source id>${'`'} keys count cycle
+phases that failed after paid model calls.
<base-key> Re-enable one key (without any :c<i>of<n> chunk suffix). The reset
is stored in the brain and survives restarts; deaths after it
@@ -57,8 +62,8 @@ export async function runDreamResetKey(engine: BrainEngine | null, args: string[
return;
}
const baseKey = dreamBreakerBaseKey(positional[0]!);
- if (!DREAM_BREAKER_KEY_PREFIXES.some(prefix => baseKey.startsWith(prefix))) {
- setCliExitVerdict(writeCliRefusal(usageError(`Not a dream breaker key: ${baseKey}. Keys start with ${DREAM_BREAKER_KEY_PREFIXES.join(' or ')}; run gbrain dream reset-key --list.`,
+ if (!DREAM_RESETTABLE_KEY_PREFIXES.some(prefix => baseKey.startsWith(prefix))) {
+ setCliExitVerdict(writeCliRefusal(usageError(`Not a dream breaker key: ${baseKey}. Keys start with ${DREAM_RESETTABLE_KEY_PREFIXES.join(', ')}; run gbrain dream reset-key --list.`,
'Run `gbrain dream reset-key --list --json` for the tripped keys and their reset commands.'), 'dream', { json }));
return;
}
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 59b8c1aa07..536b0a8a75 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1319,6 +1319,10 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
// #7705 (strict door planned state). `since` is stamped at the merge slot.
{ since: '0.60.471.0', id: 'door_planned_state', text: 'On a source with `canonical: git`, a page write now commits exactly the bytes it published, or nothing. A file edited on disk while the write was publishing refuses `git_target_changed`: nothing is committed, the edit stays on disk and the source\'s writes pause until `gbrain repair stuck-recovery` resolves it (before, Git committed the edit while the database recorded the write\'s content). A staged change of the page\'s file refuses `git_index_conflict`, with the index untouched; commit or unstage it, then retry (before, the write replaced the staged change in the index). When the index still holds the version from before an earlier gbrain commit whose index update failed, the next write restores it and says so with a `git_index_restored` notice.' },
// #7679 / #7685 orphaned worktree refresh. `since` is stamped at the merge slot.
+ // GBRA-224 W3 (bounded self-heals). `since` is stamped at the merge slot.
+ { since: 'TBD', id: 'dream_write_deferral_w3', text: 'A dream purge or consolidate write that was accepted but is still pending after its publish wait no longer fails the phase: the phase warns `dream_write_deferred` with the receipt id, and the next pass reads that receipt before it submits anything for the source (committed clears it; a failure is reported with its real code). After 3 passes still pending, doctor `dream_write_deferred` warns with `gbrain write-request -- <id>`. `gbrain config set dream.write_deferral.enabled false` restores the failing phase.' },
+ { since: 'TBD', id: 'synthesize_no_candidates_w3', text: 'A dream synthesize window where every transcript is already synthesized now returns before triage, the manifest context and the child queue, with `details.reason: no_candidates` and the cooldown stamped. Synthesize deaths also count per transcript under `dream:synth-v2:@file:<source>:<file>` once they span two content keys, so a transcript that grows between dying runs is refused after 3 deaths in 24 hours like any other key, and `gbrain dream reset-key` now accepts every key `--list` prints, `dream:phase:` keys included.' },
+ { since: 'TBD', id: 'embedding_restamp_w3', text: 'The maintenance cycle\'s embed phase now first stamps the current embedding signature on pages whose every chunk already holds a current-model vector, up to 500 pages a run, with no provider call; a page edited or re-embedded during the stamp is left for the next run. Three failed runs in a row warn as doctor `embedding_restamp_stalled`. `gbrain config set embed.restamp.enabled false` turns it off. Health\'s embedding coverage now counts live pages only, so chunks kept on a soft-deleted page no longer lower it.' },
{ since: '0.60.472.0', id: 'refresh_orphan_7679', text: 'A managed `gbrain sources refresh` whose process died (for example a container replaced mid-refresh) no longer wedges the checkout: the next plain `gbrain sources refresh` on the owner host finishes the orphaned refresh through the `--resume` path before its own refresh and reports it as `recovered`, and the owner completes an orphaned `syncing` refresh once every member has synced to its target. A refresh whose holder is still running, or is recorded on another host, is never taken over. `gbrain sources writer status` and `gbrain sync status` now name the holder and its `liveness` (`live`, `orphaned`, `unknown`) with a fix naming `--resume`. With `--json`, a refusal that carries a structured fix (`refresh_in_progress`, `refresh_diverged`, a git read failure) now prints `fix` as an object (argv, actor, next) instead of a string; the prose stays in `suggestion`, so read that when a script needs text. A plain refresh of a checkout whose interrupted refresh needs a reset decision now refuses `refresh_recovery_required` (it refused `refresh_in_progress`).' },
];
diff --git a/src/core/config.ts b/src/core/config.ts
index 0a95052dce..da6908d251 100644
--- a/src/core/config.ts
+++ b/src/core/config.ts
@@ -1603,6 +1603,7 @@ export const KNOWN_CONFIG_KEYS: readonly string[] = [
// Paid-loop breaker: dead submissions of one dream key within 24h before
// it is refused (default 3; 0 disables). `gbrain dream reset-key` clears one.
'dream.breaker.max_dead_submissions',
+ 'dream.write_deferral.enabled', 'embed.restamp.enabled', // GBRA-224 W3 self-heal switches, default on (heal-audit.ts healEnabled)
// Emotional weight (v0.29)
'emotional_weight.high_tags',
'emotional_weight.user_holder',
diff --git a/src/core/cycle.ts b/src/core/cycle.ts
index e9c66d22a1..5f8c4a2849 100644
--- a/src/core/cycle.ts
+++ b/src/core/cycle.ts
@@ -1663,7 +1663,7 @@ async function runPhaseEmbed(engine: BrainEngine, dryRun: boolean, signal?: Abor
if (!dryRun && (loadConfig()?.embedding_disabled === true || await engine.getConfig('embedding_disabled') === 'true')) {
return { phase: 'embed', status: 'skipped', duration_ms: 0, summary: 'embeddings disabled; no provider call made', details: { reason: 'embedding_disabled' } };
}
- const { runEmbedCore } = await import('../commands/embed.ts');
+ const [{ runEmbedCore }, restamp] = await Promise.all([import('../commands/embed.ts'), dryRun ? null : import('./embedding-restamp.ts').then(m => m.restampCycleSignatures(engine, signal))]);
// #1737: thread the cycle's abort signal so the embed phase (the long,
// 10-15 min one) bails within a batch instead of running to completion
// after the job was killed — which left gbrain_cycle_locks held and
@@ -1674,7 +1674,7 @@ async function runPhaseEmbed(engine: BrainEngine, dryRun: boolean, signal?: Abor
assertEmbedNotStalled(result); // #4599: a watchdog-aborted drain is a failed phase, not 'ok'
const embeddedCount = dryRun ? result.would_embed : result.embedded;
const failed = result.failures > 0 && !result.lock_skipped; // E-A: blocked pages are a warn; another backfill's lock is not
- const counts = dryRun ? `${result.would_embed} chunk(s) would be embedded (dry-run)` : `${result.embedded} chunk(s) newly embedded (${result.skipped} already had embeddings)`;
+ const counts = (dryRun ? `${result.would_embed} chunk(s) would be embedded (dry-run)` : `${result.embedded} chunk(s) newly embedded (${result.skipped} already had embeddings)`) + (restamp?.pages ? `; restamped ${restamp.pages} page(s) already in the current model's space (no provider call)` : '');
return {
phase: 'embed', status: failed ? 'warn' : 'ok', duration_ms: 0,
summary: failed ? `${counts}; ${result.failures} chunk(s) could not be embedded this run` : counts,
@@ -1689,7 +1689,7 @@ async function runPhaseEmbed(engine: BrainEngine, dryRun: boolean, signal?: Abor
// In dry-run, this counts pages with stale chunks that would
// have been processed (same semantic as a real run).
pages_embedded_count: dryRun ? result.pages_processed : embeddedCount > 0 ? result.pages_processed : 0,
- failures: result.failures, ...(result.content_drift ? { content_drift: result.content_drift } : {}),
+ failures: result.failures, ...(result.content_drift ? { content_drift: result.content_drift } : {}), ...(restamp ? { restamp } : {}),
...(failed ? { failure_samples: result.failure_samples, fix: embedBackfillFix({ backlog: result.failures, verifyCheck: 'embeddings' }) } : {}),
},
};
@@ -1835,7 +1835,7 @@ async function runPhasePurge(engine: BrainEngine, dryRun: boolean): Promise<Phas
details: {
purged_sources_count: purgedSources.length,
purged_sources_blocked: purgeResult.blocked,
- purged_pages_count: purgedPages.count, purged_pages_blocked: purgedPages.blocked, purged_pages_deferred: purgedPages.deferred, purged_pages_capacity_deferred: purgedPages.capacity_deferred,
+ purged_pages_count: purgedPages.count, purged_pages_blocked: purgedPages.blocked, purged_pages_deferred: purgedPages.deferred, purged_pages_capacity_deferred: purgedPages.capacity_deferred, ...purgedPages.deferral?.detailFields('purged_pages_write_deferred'),
purged_orphan_clones_count: purgedClones.count,
purged_orphan_clone_names: purgedClones.names,
purged_sources: purgedSources,
diff --git a/src/core/cycle/dream-breaker.ts b/src/core/cycle/dream-breaker.ts
index 184c1d1675..1967c9cf13 100644
--- a/src/core/cycle/dream-breaker.ts
+++ b/src/core/cycle/dream-breaker.ts
@@ -18,9 +18,22 @@
* before any work does not. A completed patterns run resets its source key,
* so only consecutive deaths trip it.
*
- * Not covered: content-hashed synthesize keys change whenever a transcript
- * grows, and patterns runs outside maintenance carry no key.
+ * Content-hashed synthesize keys (W3, #6753/#6924): a synth-v2 key digests
+ * the transcript, so a growing transcript gets a new key on every pass and
+ * its deaths never meet on one key. Each synthesize death therefore also
+ * counts under the stable per-transcript key
+ * `dream:synth-v2:@file:<source id>:<encoded basename>` (the job's
+ * `source_id`, not its incarnation, so a brain that went managed keeps its
+ * count). The same work is "this transcript file in this source", whatever
+ * its length or chunking; the rule stays 3 dead runs in 24 h, and only the
+ * window or `gbrain dream reset-key` clears it ('@' cannot occur in an
+ * encoded identity, so the prefix never collides with a job key). The
+ * per-transcript row exists only once its deaths span two content keys, so a
+ * loop on one unchanged transcript still reports under its own key.
+ *
+ * Not covered: patterns runs outside maintenance carry no key.
*/
+import { basename } from 'node:path';
import type { BrainEngine } from '../engine.ts';
import type { PhaseResult } from '../cycle.ts';
@@ -34,6 +47,15 @@ export function dreamPatternsSourceKey(sourceId: string): string {
}
/** Base-key prefix of a contained cycle-phase failure after paid model calls. */
export const DREAM_PHASE_KEY_PREFIX = 'dream:phase:';
+/** Base-key prefix of the per-transcript synthesize count, whatever each pass's content hash. */
+export const DREAM_SYNTH_FILE_KEY_PREFIX = 'dream:synth-v2:@file:';
+/** Every key family `gbrain dream reset-key` accepts: the ones `--list` and the breaker refusals print. */
+export const DREAM_RESETTABLE_KEY_PREFIXES = [...DREAM_BREAKER_KEY_PREFIXES, DREAM_PHASE_KEY_PREFIX] as const;
+
+/** The stable key every synthesize death of this transcript counts under (W3). */
+export function dreamSynthFileKey(sourceId: string, transcriptBasename: string): string {
+ return `${DREAM_SYNTH_FILE_KEY_PREFIX}${sourceId}:${encodeURIComponent(transcriptBasename)}`;
+}
export const DREAM_BREAKER_CONFIG_KEY = 'dream.breaker.max_dead_submissions';
export const DREAM_BREAKER_RESETS_KEY = 'dream.breaker.resets';
/** Contained paid phase failures: `{ [base key]: ISO finish times }`, pruned to the 24 h window. */
@@ -84,18 +106,23 @@ export async function countDeadDreamSubmissions(engine: BrainEngine): Promise<De
WHERE name = 'subagent' AND finished_at > now() - interval '24 hours'
AND (status = 'dead' OR (status = 'cancelled' AND tokens_input + tokens_output > 0))
), counted AS (
- SELECT base_key, queue, finished_at FROM ended
+ SELECT base_key, queue, finished_at, base_key AS content_key FROM ended
WHERE status = 'dead' AND left(base_key, ${DREAM_BREAKER_KEY_PREFIXES[0].length}) = $1
UNION ALL
- SELECT $4::text || source_id, queue, finished_at FROM ended
+ SELECT $4::text || source_id, queue, finished_at, NULL FROM ended
WHERE left(base_key, ${DREAM_BREAKER_KEY_PREFIXES[1].length}) = $2
+ UNION ALL
+ SELECT $5::text || source_id || ':' || substring(base_key from ':filename:([^:]*):[^:]*$'), queue, finished_at, base_key FROM ended
+ WHERE status = 'dead' AND left(base_key, ${DREAM_BREAKER_KEY_PREFIXES[0].length}) = $1 AND base_key ~ ':filename:[^:]*:[^:]*$'
)
SELECT base_key, COUNT(DISTINCT queue)::int AS dead_submissions, MAX(finished_at)::text AS last_dead_at
FROM counted
WHERE finished_at > COALESCE(($3::text::jsonb ->> base_key)::timestamptz, '-infinity'::timestamptz)
GROUP BY base_key
+ -- A per-transcript count is its own row only once its deaths span two content keys; one key already counts itself.
+ HAVING left(base_key, length($5::text)) <> $5::text OR COUNT(DISTINCT content_key) > 1
ORDER BY dead_submissions DESC, base_key`,
- [DREAM_BREAKER_KEY_PREFIXES[0], DREAM_BREAKER_KEY_PREFIXES[1], JSON.stringify(resets), DREAM_PATTERNS_SOURCE_KEY_PREFIX],
+ [DREAM_BREAKER_KEY_PREFIXES[0], DREAM_BREAKER_KEY_PREFIXES[1], JSON.stringify(resets), DREAM_PATTERNS_SOURCE_KEY_PREFIX, DREAM_SYNTH_FILE_KEY_PREFIX],
);
const cutoff = Date.now() - 24 * 3_600_000;
for (const [baseKey, times] of Object.entries(await loadContained(engine))) {
@@ -197,6 +224,16 @@ export async function clearPatternsSourceDeaths(engine: BrainEngine, sourceId: s
}
/** Refusal line for the cycle summary and the autopilot log. */
+/**
+ * The synthesize refusal for one transcript: its content key first, then (W3) its per-transcript key, which catches a
+ * transcript that grew (a new content key) between dying runs.
+ */
+export function synthBreakerRefusal(breaker: DreamBreaker, t: { synthesisIdentity: string; sourceId: string; filePath: string; hash16: string }): string | null {
+ const file = basename(t.filePath);
+ return dreamBreakerRefusal(breaker, `dream:synth-v2:${encodeURIComponent(t.synthesisIdentity)}:filename:${encodeURIComponent(file)}:${t.hash16}`)
+ ?? dreamBreakerRefusal(breaker, dreamSynthFileKey(t.sourceId, file));
+}
+
export function dreamBreakerRefusal(breaker: DreamBreaker, baseKey: string): string | null {
const count = breaker.tripped.get(baseKey);
if (count === undefined) return null;
diff --git a/src/core/cycle/dream-write-deferral.ts b/src/core/cycle/dream-write-deferral.ts
new file mode 100644
index 0000000000..cdadcf6e06
--- /dev/null
+++ b/src/core/cycle/dream-write-deferral.ts
@@ -0,0 +1,223 @@
+/**
+ * W3 (GBRA-224, #7587, extending #5474): a dream phase that publishes a
+ * coordinated write (consolidate, purge) and finds it accepted but still
+ * pending after its publish wait records a deferral instead of failing. The
+ * deferral keeps the receipt's request id, one per (phase, source); the phase
+ * stops submitting for that source and reports `deferred` (status warn), so
+ * the cycle is not failed for a write that is merely slow.
+ *
+ * The next pass of the phase reconciles its deferrals before it submits
+ * anything: a committed receipt is done, a failed one is reported as that
+ * failure, a receipt that is gone (compacted) clears and the phase re-plans
+ * from current state. One still pending keeps its source held and counts a
+ * replay; at DREAM_WRITE_DEFERRAL_MAX_REPLAYS the deferral stops counting and
+ * escalates: doctor's `dream_write_deferred` check (page class) names the
+ * receipt and its status command. The receipt is still read every pass, so a
+ * late commit clears it on its own. Every step writes a heal audit row
+ * (heal-audit.ts) in the same transaction as the deferral state.
+ *
+ * `dream.write_deferral.enabled=false` turns this off: a pending write fails
+ * the phase as before. State lives in the config table, so it works the same
+ * on a repo-less brain.
+ */
+import type { BrainEngine } from '../engine.ts';
+import { acceptedPendingReceipt } from '../persistence/accepted-pending.ts';
+import { getWriteRequest } from '../persistence/journal.ts';
+import type { Principal } from '../persistence/model.ts';
+import { healEnabled, recordHealAudit, type HealAuditInput } from '../heal-audit.ts';
+
+export const DREAM_WRITE_DEFERRALS_KEY = 'dream.write_deferral.pending';
+export const DREAM_WRITE_DEFERRAL_ENABLED_KEY = 'dream.write_deferral.enabled';
+export const DREAM_WRITE_DEFERRAL_MAX_REPLAYS = 3;
+export const DREAM_WRITE_DEFERRED_CODE = 'dream_write_deferred';
+
+export interface DreamWriteDeferral {
+ phase: string;
+ source_id: string;
+ /** What the write was for, e.g. `<source>/<slug>` for purge, `<source>/<entity>` for consolidate. */
+ subject: string;
+ request_id: string;
+ /** The receipt row's primary key (resolved through the principal's request index), so reconciling never scans the journal. */
+ receipt_id: string | null;
+ /** Later passes that found the receipt still pending, capped at the bound. */
+ replays: number;
+ deferred_at: string;
+}
+
+export interface DreamWriteReconcile {
+ committed: DreamWriteDeferral[];
+ failed: Array<DreamWriteDeferral & { code: string; message: string }>;
+ /** Receipt no longer readable (compacted): cleared; the phase re-plans from current state. */
+ cleared: DreamWriteDeferral[];
+ /** Still pending: the phase submits nothing for these sources this pass. */
+ held: DreamWriteDeferral[];
+ /** Held deferrals at the replay bound. */
+ escalated: DreamWriteDeferral[];
+}
+
+export function writeStatusCommand(requestId: string): string {
+ return `gbrain write-request -- ${requestId}`;
+}
+
+export function dreamWriteDeferralEnabled(engine: Pick<BrainEngine, 'getConfig'>): Promise<boolean> {
+ return healEnabled(engine, DREAM_WRITE_DEFERRAL_ENABLED_KEY);
+}
+
+/** The accepted, still-pending receipt's request id an error carries, or null. */
+export function pendingRequestId(error: unknown): string | null {
+ return acceptedPendingReceipt(error)?.request_id ?? null;
+}
+
+function parseDeferrals(raw: string | null | undefined): Record<string, DreamWriteDeferral> {
+ if (!raw) return {};
+ try {
+ const parsed = JSON.parse(raw) as unknown;
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+ return Object.fromEntries(Object.entries(parsed).filter(([, entry]) => !!entry && typeof entry === 'object'
+ && typeof (entry as DreamWriteDeferral).request_id === 'string' && typeof (entry as DreamWriteDeferral).phase === 'string'));
+ } catch { return {}; }
+}
+
+const entryKey = (phase: string, sourceId: string) => `${phase}:${sourceId}`;
+
+export async function readDreamWriteDeferrals(engine: Pick<BrainEngine, 'getConfig'>): Promise<DreamWriteDeferral[]> {
+ return Object.values(parseDeferrals(await engine.getConfig(DREAM_WRITE_DEFERRALS_KEY)));
+}
+
+/** Lock the deferral map for one read-modify-write; `mutate` returns the audit rows to write with it. */
+async function withDeferrals<T>(engine: BrainEngine,
+ mutate: (map: Record<string, DreamWriteDeferral>, now: string, tx: BrainEngine) => Promise<{ result: T; audit: HealAuditInput[] }>): Promise<T> {
+ return engine.transaction(async tx => {
+ await tx.executeRaw("INSERT INTO config (key, value) VALUES ($1, '{}') ON CONFLICT (key) DO NOTHING", [DREAM_WRITE_DEFERRALS_KEY]);
+ const [row] = await tx.executeRaw<{ value: string; now: string }>(
+ `SELECT value, to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS now FROM config WHERE key=$1 FOR UPDATE`,
+ [DREAM_WRITE_DEFERRALS_KEY]);
+ const map = parseDeferrals(row?.value);
+ const { result, audit } = await mutate(map, row!.now, tx);
+ await tx.executeRaw('UPDATE config SET value=$2 WHERE key=$1', [DREAM_WRITE_DEFERRALS_KEY, JSON.stringify(map)]);
+ await recordHealAudit(tx, audit);
+ return result;
+ });
+}
+
+const auditRow = (entry: DreamWriteDeferral, outcome: string, detail?: string): HealAuditInput => ({
+ code: DREAM_WRITE_DEFERRED_CODE, outcome, attempt: entry.replays, bound: DREAM_WRITE_DEFERRAL_MAX_REPLAYS,
+ subject: `${entry.phase}:${entry.subject}`, request_id: entry.request_id, ...(detail ? { detail } : {}),
+});
+
+/**
+ * Reconcile this phase's deferrals against their receipts before the phase
+ * submits anything. Reads each receipt by request id; never resubmits.
+ */
+export async function reconcileDreamWriteDeferrals(engine: BrainEngine, phase: string): Promise<DreamWriteReconcile> {
+ return withDeferrals(engine, async (map, _now, tx) => {
+ const out: DreamWriteReconcile = { committed: [], failed: [], cleared: [], held: [], escalated: [] };
+ const audit: HealAuditInput[] = [];
+ for (const [key, entry] of Object.entries(map)) {
+ if (entry.phase !== phase) continue;
+ const [receipt] = entry.receipt_id ? await tx.executeRaw<{ state: string; error_code: string | null; error_message: string | null }>(
+ 'SELECT state, error_code, error_message FROM persistence_requests WHERE id=$1::uuid', [entry.receipt_id]) : [];
+ if (!receipt) {
+ delete map[key];
+ out.cleared.push(entry);
+ audit.push(auditRow(entry, 'receipt_missing'));
+ } else if (receipt.state === 'committed') {
+ delete map[key];
+ out.committed.push(entry);
+ audit.push(auditRow(entry, 'committed'));
+ } else if (['failed', 'conflict', 'cancelled'].includes(receipt.state)) {
+ delete map[key];
+ const code = receipt.error_code ?? (receipt.state === 'cancelled' ? 'cancelled' : receipt.state === 'conflict' ? 'revision_conflict' : 'storage_error');
+ const message = receipt.error_message ?? `The deferred ${phase} write (request_id ${entry.request_id}) ended ${receipt.state}.`;
+ out.failed.push({ ...entry, code, message });
+ audit.push(auditRow(entry, 'failed', code));
+ } else {
+ if (entry.replays < DREAM_WRITE_DEFERRAL_MAX_REPLAYS) {
+ entry.replays += 1;
+ audit.push(auditRow(entry, entry.replays >= DREAM_WRITE_DEFERRAL_MAX_REPLAYS ? 'escalated' : 'replayed'));
+ }
+ out.held.push(entry);
+ if (entry.replays >= DREAM_WRITE_DEFERRAL_MAX_REPLAYS) out.escalated.push(entry);
+ }
+ }
+ return { result: out, audit };
+ });
+}
+
+/** Record an accepted write still pending after its wait. One deferral per (phase, source): an existing one is kept. */
+export async function deferDreamWrite(engine: BrainEngine,
+ input: { phase: string; sourceId: string; subject: string; requestId: string; principal: Principal }): Promise<DreamWriteDeferral> {
+ return withDeferrals(engine, async (map, now, tx) => {
+ const key = entryKey(input.phase, input.sourceId);
+ const existing = map[key];
+ if (existing) return { result: existing, audit: [] };
+ const receipt = await getWriteRequest(tx, input.principal, input.requestId);
+ const entry: DreamWriteDeferral = { phase: input.phase, source_id: input.sourceId, subject: input.subject,
+ request_id: input.requestId, receipt_id: receipt?.id ?? null, replays: 0, deferred_at: now };
+ map[key] = entry;
+ return { result: entry, audit: [auditRow(entry, 'deferred')] };
+ });
+}
+
+/**
+ * One pass of a deferring phase: reconciles first (`start`), then answers whether a source is held, records a
+ * pending write as a deferral, and reports. Null from `start` when deferral is off for this run.
+ */
+export class DreamWriteDeferralPass {
+ readonly deferredNow: DreamWriteDeferral[] = [];
+ /** Items this pass did not submit: held behind a pending receipt, or deferred themselves. */
+ skipped = 0;
+ private readonly holding: Map<string, DreamWriteDeferral>;
+ private constructor(private readonly engine: BrainEngine, private readonly phase: string, readonly reconcile: DreamWriteReconcile) {
+ this.holding = new Map(reconcile.held.map(entry => [entry.source_id, entry]));
+ }
+
+ static async start(engine: BrainEngine, phase: string, applies: boolean): Promise<DreamWriteDeferralPass | null> {
+ if (!applies || !await dreamWriteDeferralEnabled(engine)) return null;
+ return new DreamWriteDeferralPass(engine, phase, await reconcileDreamWriteDeferrals(engine, phase));
+ }
+
+ /** The pending deferral holding `sourceId`, counted as one skipped item; undefined when the source may submit. */
+ hold(sourceId: string): DreamWriteDeferral | undefined {
+ const entry = this.holding.get(sourceId);
+ if (entry) this.skipped++;
+ return entry;
+ }
+
+ /** The new deferral when `error` is an accepted write still pending after its wait; null for any other error. */
+ async defer(error: unknown, input: { sourceId: string; subject: string; principal: Principal }): Promise<DreamWriteDeferral | null> {
+ const requestId = pendingRequestId(error);
+ if (!requestId) return null;
+ const entry = await deferDreamWrite(this.engine, { phase: this.phase, requestId, ...input });
+ this.deferredNow.push(entry);
+ this.holding.set(input.sourceId, entry);
+ this.skipped++;
+ return entry;
+ }
+
+ details(): Record<string, unknown> | null { return deferralDetails(this.reconcile, this.deferredNow); }
+
+ /** The phase details fields: the skipped count and, when there is anything to say, `write_deferral`. */
+ detailFields(countKey: string): Record<string, unknown> {
+ const details = this.details();
+ return { [countKey]: this.skipped, ...(details ? { write_deferral: details } : {}) };
+ }
+}
+
+/** The phase details block every deferring phase reports. */
+export function deferralDetails(reconcile: DreamWriteReconcile | null, deferredNow: DreamWriteDeferral[]): Record<string, unknown> | null {
+ const held = reconcile?.held ?? [];
+ if (!reconcile && deferredNow.length === 0) return null;
+ const pending = [...held, ...deferredNow.filter(entry => !held.some(h => h.request_id === entry.request_id))];
+ if (pending.length === 0 && !reconcile?.committed.length && !reconcile?.failed.length && !reconcile?.cleared.length) return null;
+ return {
+ code: DREAM_WRITE_DEFERRED_CODE,
+ bound: DREAM_WRITE_DEFERRAL_MAX_REPLAYS,
+ pending: pending.map(entry => ({ source_id: entry.source_id, subject: entry.subject, request_id: entry.request_id,
+ replays: entry.replays, status_command: writeStatusCommand(entry.request_id) })),
+ escalated: (reconcile?.escalated ?? []).map(entry => entry.request_id),
+ reconciled_committed: (reconcile?.committed ?? []).map(entry => entry.request_id),
+ reconciled_failed: (reconcile?.failed ?? []).map(entry => ({ request_id: entry.request_id, code: entry.code })),
+ reconciled_cleared: (reconcile?.cleared ?? []).map(entry => entry.request_id),
+ };
+}
diff --git a/src/core/cycle/phases/consolidate.ts b/src/core/cycle/phases/consolidate.ts
index 106e4d7b64..c03406827d 100644
--- a/src/core/cycle/phases/consolidate.ts
+++ b/src/core/cycle/phases/consolidate.ts
@@ -32,9 +32,10 @@ import { sameInstantTies, type SameInstantTie } from '../../facts/claim-ties.ts'
import { createHash } from 'node:crypto';
import { isAborted } from '../../abort-check.ts';
import { classifyItemFailure, ItemRun } from '../../item-failure.ts';
-import { maintenancePreflight, submitMaintenanceConsolidation } from '../../persistence/prepared-maintenance.ts';
+import { maintenancePreflight, submitMaintenanceConsolidation, type MaintenanceAuthority } from '../../persistence/prepared-maintenance.ts';
import { clearConsolidationTies, consolidationRestored, factPreimages, holdConsolidationTie, recordConsolidationGeneration } from '../../generations/adapters/fact-rows.ts';
import { managedPersistenceEnabled } from '../../persistence/ownership.ts';
+import { DreamWriteDeferralPass } from '../dream-write-deferral.ts';
import { declareDerivation, derivedMaintenanceTransaction, derivedWriteTrust, isExternalTier, readTaintInputs } from '../../trust/taint.ts';
import { DEFAULT_WRITE_GATE_CONFIG, type WriteGateConfig } from '../../write-gate.ts';
import { loadImportSanityConfig } from '../../import-screen.ts';
@@ -87,6 +88,24 @@ async function disabledSkip(engine: BrainEngine, opts: ConsolidatePhaseOpts): Pr
/** At most this many failed buckets are listed in `details.bucket_failures`; `buckets_failed` counts them all. */
const BUCKET_FAILURE_SAMPLES = 10;
+type BucketFailure = { source_id: string; entity_slug: string; code: string; message: string; fix: Action };
+
+const rerunFix = (sourceId: string): Action => ({ argv: ['gbrain', 'dream', '--phase', 'consolidate', '--source', sourceId], consent: [], actor: 'agent',
+ requires_exclusive: false, why: 'Reruns consolidate for this source; the bucket consolidates once its entity and evidence pages are readable again.' });
+
+/**
+ * W3 (#7587): consolidations an earlier pass left pending that ended failed, as bucket failures (samples pushed onto
+ * `failures`); returns how many. A source whose receipt is still pending submits nothing this pass (`hold`), and a
+ * write still pending after its wait defers the rest of its source (`defer`); deferral off restores the failing phase.
+ */
+function reconciledBucketFailures(deferral: DreamWriteDeferralPass | null, failures: BucketFailure[]): number {
+ const failed = deferral?.reconcile.failed ?? [];
+ for (const entry of failed.slice(0, Math.max(0, BUCKET_FAILURE_SAMPLES - failures.length))) {
+ failures.push({ source_id: entry.source_id, entity_slug: entry.subject.slice(entry.source_id.length + 1), code: entry.code,
+ message: `The consolidation an earlier pass left pending (request_id ${entry.request_id}) ended with ${entry.code}: ${entry.message}`.slice(0, 300), fix: rerunFix(entry.source_id) });
+ }
+ return failed.length;
+}
export const CLUSTER_THRESHOLD_KEY = 'cycle.consolidate.cluster_threshold';
export const DEFAULT_CLUSTER_THRESHOLD = 0.85;
@@ -202,8 +221,9 @@ export async function runPhaseConsolidate(
}
const run = new ItemRun('consolidate.buckets');
- let bucketsFailed = 0;
- const bucketFailures: Array<{ source_id: string; entity_slug: string; code: string; message: string; fix: Action }> = [];
+ const bucketFailures: BucketFailure[] = [];
+ const deferral = await DreamWriteDeferralPass.start(engine, 'consolidate', managed && !dryRun);
+ let bucketsFailed = reconciledBucketFailures(deferral, bucketFailures);
for (const b of buckets) {
// #1972: bail at the top of the bucket loop on abort. Each prior bucket's
// per-row INSERT/consolidate is already committed, so breaking returns a
@@ -216,9 +236,11 @@ export async function runPhaseConsolidate(
// One bucket the writer refuses (an entity or evidence page made private or deleted while its world facts
// stay active) is counted and sampled; later buckets still consolidate. Abort, budget and lost-connection
- // errors stay run-scoped, and an accepted write still publishing keeps ending the phase as before.
+ // errors stay run-scoped; an accepted write still publishing defers its source (W3), or ends the phase with deferral off.
+ if (deferral?.hold(b.source_id)) continue;
+ let maintenance: MaintenanceAuthority | null = null;
try {
- const maintenance = managed && !dryRun ? await maintenancePreflight(engine, b.source_id) : null;
+ maintenance = managed && !dryRun ? await maintenancePreflight(engine, b.source_id) : null;
const candidates = await engine.listFactsByEntity(b.source_id, b.entity_slug, {
activeOnly: true,
unconsolidatedOnly: true,
@@ -394,20 +416,18 @@ export async function runPhaseConsolidate(
}
run.succeed();
} catch (error) {
- if (classifyItemFailure(error).scope === 'pending') throw error;
+ if (classifyItemFailure(error).scope === 'pending') { if (maintenance && await deferral?.defer(error, { sourceId: b.source_id, subject: `${b.source_id}/${b.entity_slug}`, principal: maintenance.writer.principal })) continue; throw error; }
const failure = run.fail(`${b.source_id}:${b.entity_slug}`, error);
bucketsFailed += 1;
if (bucketFailures.length < BUCKET_FAILURE_SAMPLES) {
- bucketFailures.push({ source_id: b.source_id, entity_slug: b.entity_slug, code: failure.code, message: failure.message.slice(0, 300),
- fix: { argv: ['gbrain', 'dream', '--phase', 'consolidate', '--source', b.source_id], consent: [], actor: 'agent', requires_exclusive: false,
- why: 'Reruns consolidate for this source; the bucket consolidates once its entity and evidence pages are readable again.' } });
+ bucketFailures.push({ source_id: b.source_id, entity_slug: b.entity_slug, code: failure.code, message: failure.message.slice(0, 300), fix: rerunFix(b.source_id) });
}
}
}
return {
phase: 'consolidate',
- status: bucketsFailed > 0 || clustersHeldSameInstant > 0 ? 'warn' : factsConsolidated === 0 && clustersSkippedRetired > 0 ? 'skipped' : 'ok',
+ status: bucketsFailed > 0 || clustersHeldSameInstant > 0 || deferral?.skipped ? 'warn' : factsConsolidated === 0 && clustersSkippedRetired > 0 ? 'skipped' : 'ok',
duration_ms: 0,
summary: (dryRun
? `(dry-run) would promote ${factsConsolidated} facts into ${takesWritten} takes across ${bucketsProcessed} buckets`
@@ -415,7 +435,7 @@ export async function runPhaseConsolidate(
(clustersSkippedRetired ? `; skipped ${clustersSkippedRetired} clusters with retired takes` : '') +
(clustersGateHeld ? `; held ${clustersGateHeld} takes for write-gate review` : '') +
(clustersGateRejected ? `; write gate rejected ${clustersGateRejected} takes` : '') +
- (bucketsFailed ? `; ${bucketsFailed} bucket(s) failed (details.bucket_failures)` : '')) +
+ (bucketsFailed ? `; ${bucketsFailed} bucket(s) failed (details.bucket_failures)` : '') + (deferral?.skipped ? `; deferred ${deferral.skipped} bucket(s): an accepted write is still publishing (details.write_deferral)` : '')) +
(clustersHeldSameInstant ? `; held ${clustersHeldSameInstant} cluster(s) whose typed claims state one metric for the same effective time (details.same_instant_clusters)` : ''),
details: {
dryRun,
@@ -433,7 +453,7 @@ export async function runPhaseConsolidate(
clusters_held_same_instant: clustersHeldSameInstant,
same_instant_clusters: sameInstantClusters,
buckets_failed: bucketsFailed,
- bucket_failures: bucketFailures,
+ bucket_failures: bucketFailures, ...deferral?.detailFields('buckets_deferred'),
...(factsConsolidated === 0 && clustersSkippedRetired > 0 ? { reason: 'retired_take' } : {}),
},
};
diff --git a/src/core/cycle/synthesize-completion.ts b/src/core/cycle/synthesize-completion.ts
index 7847cbca0b..fbae2437aa 100644
--- a/src/core/cycle/synthesize-completion.ts
+++ b/src/core/cycle/synthesize-completion.ts
@@ -10,6 +10,7 @@ import type { BrainEngine } from '../engine.ts';
import type { MaintenanceAuthority } from '../persistence/prepared-maintenance.ts';
import { managedPersistenceEnabled } from '../persistence/ownership.ts';
import type { DiscoveredTranscript } from './transcript-discovery.ts';
+import type { PhaseResult } from '../cycle.ts';
/**
* #5145: split transcripts into already-synthesized and candidates BEFORE the
@@ -212,3 +213,26 @@ export function findLegacyCompletion(
}
return null;
}
+
+/**
+ * #5848: the synthesize result for a window with zero candidates: no model call, no queue, no budget spend. Status
+ * stays ok (not skipped) so finishDeferredPostprocess still finishes outputs an earlier pass deferred (#6757).
+ */
+export function noCandidates(summary: string, details: Record<string, unknown>): PhaseResult {
+ return { phase: 'synthesize', status: 'ok', duration_ms: 0, summary, details: { reason: 'no_candidates', transcripts_processed: 0, pages_written: 0, ...details } };
+}
+
+/**
+ * #5848: a classic real run whose every discovered transcript is already synthesized returns here, before triage,
+ * the manifest context and the fan-out; it stamps the cooldown as a fully completed run would and reports each
+ * transcript's skip reason. A managed run never comes here: it re-attaches completed children for publication.
+ */
+export async function noNewTranscripts(engine: BrainEngine, transcripts: DiscoveredTranscript[],
+ partition: Pick<Awaited<ReturnType<typeof partitionCompletedSynthesis>>, 'retainedSkips' | 'successfulV2Keys' | 'synthesisIdentity'>): Promise<PhaseResult> {
+ await engine.setConfig('dream.synthesize.last_completion_ts', new Date().toISOString());
+ const skips = transcripts.map(t => ({ filePath: t.filePath, reason: partition.retainedSkips.get(t.filePath)
+ ?? (findSynthV2Completion(partition.successfulV2Keys, t.filePath, t.contentHash.slice(0, 16), partition.synthesisIdentity) === 'chunked'
+ ? 'already_synthesized_v2_chunked' : 'already_synthesized_v2_single_chunk') }));
+ return noCandidates(`no new transcripts to synthesize (${transcripts.length} already synthesized)`, { transcripts_discovered: transcripts.length,
+ synthesis_state: { candidates: 0, already_synthesized: transcripts.length }, children_submitted: 0, skips });
+}
diff --git a/src/core/cycle/synthesize.ts b/src/core/cycle/synthesize.ts
index 6dae09a4fe..7831a8ccbb 100644
--- a/src/core/cycle/synthesize.ts
+++ b/src/core/cycle/synthesize.ts
@@ -79,7 +79,7 @@ import { stampDreamProvenance, summaryProvenanceLines } from './dream-provenance
import { activateSynthesisGenerations } from './synthesize-generations.ts';
import { summaryDerivation, withTranscriptTaint } from './dream-taint.ts';
import { DREAM_SUMMARY_KIND, publishSinglePage } from '../generations/adapters/single-page.ts';
-import { findSynthV2Completion, partitionCompletedSynthesis } from './synthesize-completion.ts';
+import { findSynthV2Completion, noCandidates, noNewTranscripts, partitionCompletedSynthesis } from './synthesize-completion.ts';
// Re-exports: the drain was peeled to inline-drain.ts (dream-wave C7), the
// allow-list loader to filing-rules.ts (#2397); patterns.ts and the
@@ -95,7 +95,7 @@ import { safeSplitIndex, truncateUtf8 } from '../text-safe.ts';
import { PAGE_SLUG_SEG } from '../cjk.ts';
import { withChatPhase, estimateChatCostUsd } from '../ai/chat-usage.ts';
import { verifyAndRepairDreamPages, normForGrounding, readVerifyEpoch, loadChildWriteEpochs, isDreamOwnedPage, type QuoteVerifyStats, type TranscriptForVerify } from './synthesize-verify.ts';
-import { dreamBreakerRefusal, loadDreamBreaker } from './dream-breaker.ts';
+import { loadDreamBreaker, synthBreakerRefusal } from './dream-breaker.ts';
import { resolveTriageDecide, type TriageDecide, type TriageDecideStats } from './triage-decide.ts';
import { OperationError } from '../ops/contract.ts';
import { isRetryableConnError } from '../retry-matcher.ts';
@@ -527,7 +527,7 @@ async function runPhaseSynthesizeInner(
}));
if (transcripts.length === 0) {
- return ok('no transcripts to process', { transcripts_processed: 0, pages_written: 0 });
+ return noCandidates('no transcripts to process', { transcripts_discovered: 0 });
}
// Best-effort housekeeping (#4069): expiry is enforced on reads
@@ -542,6 +542,7 @@ async function runPhaseSynthesizeInner(
const { completed, retainedSkips, successfulV2Keys, synthesisIdentity } = await partitionCompletedSynthesis(engine, transcripts, opts.sourceId ?? 'default', maintenance, opts.dryRun);
const synthesisState = { candidates: transcripts.length - completed.size, already_synthesized: completed.size };
+ if (synthesisState.candidates === 0 && !maintenance && !opts.dryRun) return noNewTranscripts(engine, transcripts, { retainedSkips, successfulV2Keys, synthesisIdentity });
const pass = await runTriagePass(engine, transcripts.filter(t => !completed.has(t.filePath)), {
model: config.triage.model,
maxChars: config.triage.maxChars,
@@ -791,8 +792,7 @@ async function runPhaseSynthesizeInner(
continue;
}
- const refusal = breaker && dreamBreakerRefusal(breaker,
- `dream:synth-v2:${encodeURIComponent(synthesisIdentity)}:filename:${encodeURIComponent(basename(t.filePath))}:${hash16}`);
+ const refusal = breaker && synthBreakerRefusal(breaker, { synthesisIdentity, sourceId: cycleSourceId, filePath: t.filePath, hash16 });
if (refusal) { process.stderr.write(`[dream] ${t.basename}: ${refusal}\n`); skipReports.push({ filePath: t.filePath, reason: refusal }); continue; }
const chunks = splitTranscriptByBudget(t.content, t.contentHash, maxCharsPerChunk);
diff --git a/src/core/doctor-categories.ts b/src/core/doctor-categories.ts
index d1204d1e0a..148d8f4939 100644
--- a/src/core/doctor-categories.ts
+++ b/src/core/doctor-categories.ts
@@ -309,6 +309,9 @@ export const OPS_CHECK_NAMES: ReadonlySet<string> = new Set([
'brainstorm_health',
'connectors',
'dream_paid_loop',
+ // W3 (GBRA-224): self-heals that reached their bound (doctor/checks/dream-write-deferred.ts, embedding-restamp.ts).
+ 'dream_write_deferred',
+ 'embedding_restamp_stalled',
'connection',
'db_only_collector_collision',
'federation_health',
diff --git a/src/core/embedding-restamp.ts b/src/core/embedding-restamp.ts
new file mode 100644
index 0000000000..b1fb26e3ee
--- /dev/null
+++ b/src/core/embedding-restamp.ts
@@ -0,0 +1,132 @@
+/**
+ * W3 (GBRA-224, #5527 class): free signature restamp in the maintenance
+ * cycle's embed phase (never on upgrade). A page whose stored signature is
+ * missing or names another model, while every one of its chunks already holds
+ * a vector of the current model (model column, embedded text hash, width, in
+ * the registry-active column), is only missing its stamp. The restamp sets
+ * `pages.embedding_signature` without a provider call, so those vectors stop
+ * reading as "a previous model's space" and stop costing a paid re-embed.
+ *
+ * Each page is stamped in its own transaction under the shared page-write
+ * guard (`lockPageKeys`, the lock installPageEmbeddings and every chunk
+ * writer takes), and the UPDATE re-checks, after the lock, the revision and
+ * old signature read at selection, the projection seal (text projection at
+ * the knowledge revision), the active column, and that every chunk is still
+ * current. A concurrent re-embed, chunk rewrite or content change between the
+ * read and the stamp makes the UPDATE match nothing; that page is retried on
+ * a later run. It never touches content or vectors.
+ *
+ * Bounded: at most EMBEDDING_RESTAMP_MAX_PAGES pages per run. A run that
+ * throws counts a failed attempt in the heal audit; after
+ * EMBEDDING_RESTAMP_FAILURE_BOUND consecutive failed runs doctor's
+ * `embedding_restamp_stalled` check (page class) reports it. A run that
+ * completes resets the count. `embed.restamp.enabled=false` turns it off.
+ */
+import type { BrainEngine } from './engine.ts';
+import { resolveActiveEmbeddingColumnFromEngine, quoteIdentifier } from './search/embedding-column.ts';
+import { pageBudgetLimitedFilter } from './page-size-policy.ts';
+import { chunkGenerationFilter } from './search/safe-chunks.ts';
+import { currentSpaceChunkPredicate, splitEmbeddingSignature } from './embedding-invalidation.ts';
+import { healEnabled, readHealAudit, recordHealAudit } from './heal-audit.ts';
+
+export const EMBEDDING_RESTAMP_ENABLED_KEY = 'embed.restamp.enabled';
+export const EMBEDDING_RESTAMP_CODE = 'embedding_restamp';
+export const EMBEDDING_RESTAMP_MAX_PAGES = 500;
+export const EMBEDDING_RESTAMP_FAILURE_BOUND = 3;
+
+export interface EmbeddingRestampResult {
+ /** Pages stamped this run. */
+ pages: number;
+ chunks: number;
+ /** Pages the guarded UPDATE no longer matched (changed between read and stamp); retried next run. */
+ rejected: number;
+ /** More candidates remain past the per-run bound. */
+ capped: boolean;
+ max_pages: number;
+ /** Consecutive failed runs including this one (0 after a completed run). */
+ failed_runs: number;
+ error?: string;
+}
+
+/** The page rule every stamp re-checks under the guard: $1 signature, $2 model, $3 dims. */
+function restampablePage(colId: string): string {
+ return `(p.embedding_signature IS NULL OR p.embedding_signature <> $1)
+ AND p.deleted_at IS NULL
+ AND p.text_projection_revision = p.knowledge_revision
+ AND NOT (COALESCE(p.frontmatter, '{}'::jsonb) ? 'embed_skip')
+ AND NOT ${pageBudgetLimitedFilter('p')}
+ AND EXISTS (SELECT 1 FROM sources s WHERE s.id = p.source_id AND NOT s.archived)
+ AND EXISTS (SELECT 1 FROM content_chunks cc WHERE cc.page_id = p.id AND ${chunkGenerationFilter('p', 'cc')})
+ AND NOT EXISTS (SELECT 1 FROM content_chunks cc WHERE cc.page_id = p.id AND ${chunkGenerationFilter('p', 'cc')} AND NOT ${currentSpaceChunkPredicate(colId, 2, 3)})`;
+}
+
+let beforeStampForTests: ((pageId: number) => Promise<void>) | null = null;
+/** Test seam: runs after selection and before each page's guarded stamp (a concurrent writer's window). */
+export function __setRestampBeforeStampForTests(fn: ((pageId: number) => Promise<void>) | null): void { beforeStampForTests = fn; }
+
+async function lastFailedRuns(engine: BrainEngine): Promise<number> {
+ const last = (await readHealAudit(engine, EMBEDDING_RESTAMP_CODE)).at(-1);
+ return last?.outcome === 'failed' || last?.outcome === 'escalated' ? last.attempt : 0;
+}
+
+/**
+ * Restamp up to `maxPages` current-space pages under `signature`. Returns null
+ * when the heal is off or the signature carries no width. Never calls a provider.
+ */
+export async function restampCurrentSpaceSignatures(engine: BrainEngine, signature: string,
+ opts: { maxPages?: number; signal?: AbortSignal } = {}): Promise<EmbeddingRestampResult | null> {
+ if (!await healEnabled(engine, EMBEDDING_RESTAMP_ENABLED_KEY)) return null;
+ const { model, dims } = splitEmbeddingSignature(signature);
+ if (dims === null) return null;
+ const maxPages = opts.maxPages ?? EMBEDDING_RESTAMP_MAX_PAGES;
+ const result: EmbeddingRestampResult = { pages: 0, chunks: 0, rejected: 0, capped: false, max_pages: maxPages, failed_runs: 0 };
+ try {
+ const colId = quoteIdentifier((await resolveActiveEmbeddingColumnFromEngine(engine, { fallbackToLegacy: true })).name);
+ const candidates = await engine.executeRaw<{ id: number; source_id: string; slug: string; revision: string; signature: string | null; chunks: number }>(
+ `SELECT p.id, p.source_id, p.slug, p.knowledge_revision::text AS revision, p.embedding_signature AS signature,
+ (SELECT count(*)::int FROM content_chunks cc WHERE cc.page_id = p.id AND ${chunkGenerationFilter('p', 'cc')}) AS chunks
+ FROM pages p WHERE ${restampablePage(colId)}
+ ORDER BY p.id LIMIT ${maxPages + 1}`, [signature, model, dims]);
+ result.capped = candidates.length > maxPages;
+ for (const page of candidates.slice(0, maxPages)) {
+ if (opts.signal?.aborted) break;
+ await beforeStampForTests?.(page.id);
+ const stamped = await engine.transaction(async tx => {
+ await tx.lockPageKeys([{ sourceId: page.source_id, slug: page.slug }]);
+ const active = quoteIdentifier((await resolveActiveEmbeddingColumnFromEngine(tx, { fallbackToLegacy: true })).name);
+ if (active !== colId) return false;
+ const rows = await tx.executeRaw<{ id: number }>(
+ `UPDATE pages p SET embedding_signature = $1
+ WHERE p.id = $4 AND p.knowledge_revision = $5::uuid AND p.embedding_signature IS NOT DISTINCT FROM $6::text
+ AND ${restampablePage(active)}
+ RETURNING p.id`, [signature, model, dims, page.id, page.revision, page.signature]);
+ return rows.length === 1;
+ });
+ if (stamped) { result.pages++; result.chunks += Number(page.chunks); } else result.rejected++;
+ }
+ if (result.pages > 0 || await lastFailedRuns(engine) > 0) {
+ await recordHealAudit(engine, [{ code: EMBEDDING_RESTAMP_CODE, outcome: 'restamped', attempt: 0, bound: EMBEDDING_RESTAMP_FAILURE_BOUND,
+ subject: signature, detail: `${result.pages} page(s), ${result.chunks} chunk(s); ${result.rejected} changed under the stamp${result.capped ? `; more remain past the ${maxPages}-page bound` : ''}` }]);
+ }
+ return result;
+ } catch (error) {
+ result.error = error instanceof Error ? error.message : String(error);
+ result.failed_runs = await lastFailedRuns(engine).catch(() => 0) + 1;
+ await recordHealAudit(engine, [{ code: EMBEDDING_RESTAMP_CODE, outcome: result.failed_runs >= EMBEDDING_RESTAMP_FAILURE_BOUND ? 'escalated' : 'failed',
+ attempt: result.failed_runs, bound: EMBEDDING_RESTAMP_FAILURE_BOUND, subject: signature, detail: result.error.slice(0, 300) }]).catch(() => undefined);
+ return result;
+ }
+}
+
+/** The cycle embed phase's entry: restamp under the configured model's signature (W3; never on upgrade, never in a dry run). */
+export async function restampCycleSignatures(engine: BrainEngine, signal?: AbortSignal): Promise<EmbeddingRestampResult | null> {
+ const { currentEmbeddingSignature } = await import('./embedding.ts');
+ const signature = currentEmbeddingSignature();
+ return signature ? restampCurrentSpaceSignatures(engine, signature, { signal }) : null;
+}
+
+/** The latest restamp audit row when consecutive failed runs reached the bound, else null (doctor's embedding_restamp_stalled). */
+export async function restampEscalation(engine: BrainEngine) {
+ const last = (await readHealAudit(engine, EMBEDDING_RESTAMP_CODE)).at(-1);
+ return last && last.attempt >= EMBEDDING_RESTAMP_FAILURE_BOUND && (last.outcome === 'failed' || last.outcome === 'escalated') ? last : null;
+}
diff --git a/src/core/engine-sql/health.ts b/src/core/engine-sql/health.ts
index 1d0b90f9eb..30ca8b30f6 100644
--- a/src/core/engine-sql/health.ts
+++ b/src/core/engine-sql/health.ts
@@ -137,8 +137,9 @@ export async function getHealth(
GROUP BY cc.page_id
),
chunk_totals AS (
- SELECT COALESCE(sum(c.chunks) FILTER (WHERE f.eligible), 0) AS eligible,
- COALESCE(sum(c.embedded) FILTER (WHERE f.eligible), 0) AS eligible_embedded,
+ -- #7212: coverage counts the same live, eligible chunks as missing_embeddings; a soft-deleted page's retained chunks count in neither.
+ SELECT COALESCE(sum(c.chunks) FILTER (WHERE f.eligible AND f.live), 0) AS eligible,
+ COALESCE(sum(c.embedded) FILTER (WHERE f.eligible AND f.live), 0) AS eligible_embedded,
COALESCE(sum(c.chunks - c.embedded) FILTER (WHERE f.eligible AND f.live), 0) AS missing
FROM chunk_pages c
CROSS JOIN LATERAL (
diff --git a/src/core/heal-audit.ts b/src/core/heal-audit.ts
new file mode 100644
index 0000000000..bdfabc2bb5
--- /dev/null
+++ b/src/core/heal-audit.ts
@@ -0,0 +1,62 @@
+/**
+ * W3 (GBRA-224): the audit trail of the free self-heals (dream write deferral,
+ * embedding signature restamp). Each heal step appends one row with a stable
+ * code, the attempt number and the bound it is counted against. Rows live in
+ * the brain's config table (`heal.audit`), newest last, capped at
+ * HEAL_AUDIT_MAX_ROWS and pruned after 30 days, so every brain (repo-less
+ * included) keeps the trail without a migration. A heal that writes state
+ * passes its own transaction so the state change and its row commit together.
+ */
+import type { BrainEngine } from './engine.ts';
+
+export const HEAL_AUDIT_KEY = 'heal.audit';
+export const HEAL_AUDIT_MAX_ROWS = 200;
+const HEAL_AUDIT_RETENTION_MS = 30 * 24 * 3_600_000;
+
+export interface HealAuditRow {
+ at: string;
+ /** Stable heal code, e.g. `dream_write_deferred`, `embedding_restamp`. */
+ code: string;
+ /** What this step did: deferred, replayed, committed, failed, escalated, restamped, ... */
+ outcome: string;
+ /** Attempt number within the heal's bound (0 for a first deferral). */
+ attempt: number;
+ bound: number;
+ subject: string;
+ request_id?: string;
+ detail?: string;
+}
+
+export type HealAuditInput = Omit<HealAuditRow, 'at'>;
+
+/** Whether a heal is on: its config key is unset or anything but `false`/`0`/`off`. */
+export async function healEnabled(engine: Pick<BrainEngine, 'getConfig'>, key: string): Promise<boolean> {
+ const raw = (await engine.getConfig(key))?.trim().toLowerCase();
+ return raw !== 'false' && raw !== '0' && raw !== 'off';
+}
+
+function parseRows(raw: string | null | undefined): HealAuditRow[] {
+ if (!raw) return [];
+ try {
+ const parsed = JSON.parse(raw) as unknown;
+ return Array.isArray(parsed) ? parsed.filter((row): row is HealAuditRow => !!row && typeof row === 'object'
+ && typeof (row as HealAuditRow).code === 'string' && typeof (row as HealAuditRow).at === 'string') : [];
+ } catch { return []; }
+}
+
+export async function readHealAudit(engine: Pick<BrainEngine, 'getConfig'>, code?: string): Promise<HealAuditRow[]> {
+ const rows = parseRows(await engine.getConfig(HEAL_AUDIT_KEY));
+ return code ? rows.filter(row => row.code === code) : rows;
+}
+
+/** Append rows (database clock), serialized on the config row. Pass the heal's transaction to commit with its state. */
+export async function recordHealAudit(tx: Pick<BrainEngine, 'executeRaw'>, rows: HealAuditInput[]): Promise<void> {
+ if (rows.length === 0) return;
+ await tx.executeRaw("INSERT INTO config (key, value) VALUES ($1, '[]') ON CONFLICT (key) DO NOTHING", [HEAL_AUDIT_KEY]);
+ const [row] = await tx.executeRaw<{ value: string; now: string }>(
+ `SELECT value, to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS now FROM config WHERE key=$1 FOR UPDATE`, [HEAL_AUDIT_KEY]);
+ const cutoff = Date.parse(row!.now) - HEAL_AUDIT_RETENTION_MS;
+ const kept = parseRows(row?.value).filter(entry => Date.parse(entry.at) > cutoff);
+ const next = [...kept, ...rows.map(entry => ({ at: row!.now, ...entry }))].slice(-HEAL_AUDIT_MAX_ROWS);
+ await tx.executeRaw('UPDATE config SET value=$2 WHERE key=$1', [HEAL_AUDIT_KEY, JSON.stringify(next)]);
+}
diff --git a/src/core/persistence/purge-deleted.ts b/src/core/persistence/purge-deleted.ts
index 66ca381397..d53e088fdd 100644
--- a/src/core/persistence/purge-deleted.ts
+++ b/src/core/persistence/purge-deleted.ts
@@ -18,6 +18,8 @@ import { writerOnboardingPreflight } from './onboarding.ts';
import { clearPurgePark, isParked, notePurgeSourceWriter, PURGE_PARK_LIMIT, purgeParkKey, prunePurgeParks, readPurgeParks, recordPurgeFailure, type PurgePark } from './purge-parks.ts';
import { ItemRun, type ItemFailure } from '../item-failure.ts';
import { readUnreviewedSyncTombstones, syncDeleteHeld } from './sync-delete-tombstones.ts';
+import { maintenancePublishWaitMs } from './maintenance-wait.ts';
+import { DreamWriteDeferralPass, writeStatusCommand, DREAM_WRITE_DEFERRED_CODE } from '../cycle/dream-write-deferral.ts';
/** A tombstone that moved under a concurrent writer; the next run retries it. */
const DEFERRAL_CODES = new Set(['revision_conflict', 'page_not_found', 'page_identity_changed']);
@@ -42,6 +44,12 @@ export interface DeletedPagePurge {
capacity_deferred: number;
/** #7130: managed sync tombstones with no live twin an automatic purge kept (in `blocked`, code `sync_delete_unreviewed`). */
held: number;
+ /**
+ * W3 (#7587): automatic runs only. Tombstones not purged because an accepted purge of their source was still
+ * pending after its wait (in `blocked`, code `dream_write_deferred`); never a failure. `deferral` names the receipts.
+ */
+ write_deferred?: number;
+ deferral?: DreamWriteDeferralPass;
/** Present when `failed > 0`, so the caller cannot report success. */
error?: { class: string; code: string; message: string };
}
@@ -252,7 +260,7 @@ export async function selectPurgeCandidates(engine: BrainEngine, olderThanHours:
* and so does an unmanaged recorded tombstone whose delete failed (GBRA-130 A-49: `failed` without `error`).
*/
export function purgePhaseStatus(result: DeletedPagePurge): 'ok' | 'warn' | 'fail' {
- return result.error ? 'fail' : result.inactive || result.parked || result.capacity_deferred || result.failed || result.held ? 'warn' : 'ok';
+ return result.error ? 'fail' : result.inactive || result.parked || result.capacity_deferred || result.failed || result.held || result.write_deferred ? 'warn' : 'ok';
}
/** The purge phase summary's note on the pages it did not submit (empty when there are none). */
@@ -260,7 +268,8 @@ export function purgePhaseNote(result: DeletedPagePurge): string {
const parts = [result.inactive ? `${result.inactive} waiting on a writer in recovery` : '', !result.error && result.failed ? `${result.failed} failed (see details)` : '',
result.parked ? `${result.parked} parked (gbrain doctor: purge_parked_pages)` : '',
result.capacity_deferred ? `${result.capacity_deferred} deferred to the next run (write capacity in use)` : '',
- result.held ? `${result.held} deleted by a managed sync held for review (gbrain pages purge-deleted --dry-run; purge with --yes or restore each)` : ''].filter(Boolean);
+ result.held ? `${result.held} deleted by a managed sync held for review (gbrain pages purge-deleted --dry-run; purge with --yes or restore each)` : '',
+ result.write_deferred ? `${result.write_deferred} deferred: an accepted purge is still publishing (gbrain doctor: dream_write_deferred)` : ''].filter(Boolean);
return parts.length ? ` (${parts.join(', ')})` : '';
}
@@ -298,6 +307,8 @@ export async function purgeDeletedPagesCoordinated(engine: BrainEngine, olderTha
return { slugs: [...recorded.slugs, ...result.slugs], count: recorded.slugs.length + result.count, blocked: [...recorded.blocked, ...held.map(row => syncDeleteHeld(row, olderThanHours))],
deferred: 0, failed: recorded.failed, inactive: 0, parked: recorded.parked, capacity_deferred: 0, held: held.length };
}
+ // W3 (#7587): an automatic run reconciles the purges an earlier run left pending before it selects or submits anything.
+ const deferral = await DreamWriteDeferralPass.start(engine, 'purge', opts.automatic === true);
const selection = await selectPurgeCandidates(engine, olderThanHours, opts);
for (const [sourceId, active] of Object.entries(selection.writers)) await notePurgeSourceWriter(engine, sourceId, active);
await prunePurgeParks(engine);
@@ -305,6 +316,17 @@ export async function purgeDeletedPagesCoordinated(engine: BrainEngine, olderTha
const slugs: string[] = [];
const blocked: DeletedPagePurge['blocked'] = [...selection.blocked];
let deferred = 0, failed = 0, capacityDeferred = 0;
+ const reconciledFailures = new Set<string>();
+ for (const entry of deferral?.reconcile.failed ?? []) {
+ const [source_id, ...rest] = entry.subject.split('/');
+ const slug = rest.join('/');
+ reconciledFailures.add(entry.subject);
+ const candidate = selection.candidates.find(row => row.source_id === source_id && row.slug === slug);
+ blocked.push({ source_id: source_id!, slug, code: entry.code, reason: `The purge an earlier run left pending (request_id ${entry.request_id}) ended with ${entry.code}: ${entry.message}` });
+ if (DEFERRAL_CODES.has(entry.code)) { deferred++; continue; }
+ failed++;
+ if (candidate) await recordPurgeFailure(engine, { source_id: candidate.source_id, slug: candidate.slug, deleted_us: candidate.deleted_us, code: entry.code, reason: entry.message });
+ }
const share = resolveAdmissionOrigin() === 'background' ? await readBackgroundPauseShare(engine) : 1;
let principal: Awaited<ReturnType<typeof requestPrincipalForContext>> | undefined;
for (const [index, row] of selection.candidates.entries()) {
@@ -312,6 +334,14 @@ export async function purgeDeletedPagesCoordinated(engine: BrainEngine, olderTha
for (const rest of selection.candidates.slice(index)) blocked.push({ source_id: rest.source_id, slug: rest.slug, code: 'write_capacity_deferred', reason });
capacityDeferred = selection.candidates.length - index;
};
+ const held = deferral?.hold(row.source_id);
+ if (held) {
+ blocked.push({ source_id: row.source_id, slug: row.slug, code: DREAM_WRITE_DEFERRED_CODE,
+ reason: `Not submitted: an accepted purge in source ${row.source_id} (request_id ${held.request_id}) is still pending; the next run reconciles it first (${writeStatusCommand(held.request_id)}).` });
+ continue;
+ }
+ // Reported above with its receipt's failure; the next run re-validates and submits it again.
+ if (reconciledFailures.has(`${row.source_id}/${row.slug}`)) continue;
try {
const ctx: OperationContext = { engine, config, remote: false, sourceId: row.source_id, dryRun: false,
logger: { info() {}, warn() {}, error() {} } };
@@ -325,12 +355,18 @@ export async function purgeDeletedPagesCoordinated(engine: BrainEngine, olderTha
if (!snapshot?.page.deleted_at) continue;
// Restored and deleted again since the scan: its recovery window restarted.
if (new Date(snapshot.page.deleted_at).getTime() >= new Date(row.cutoff).getTime()) { deferred++; continue; }
- await submitPageMutation(ctx, { operation: 'delete_page', params: { slug: row.slug, source_id: row.source_id,
+ await submitPageMutation(ctx, { operation: 'delete_page', waitMs: maintenancePublishWaitMs(), params: { slug: row.slug, source_id: row.source_id,
purge: true, retention: true, expected_revision: snapshot.revision, request_id: randomUUID() } });
slugs.push(row.slug);
if (row.park) await clearPurgePark(engine, row.key);
} catch (error) {
if (isWriteCapacityWait(error)) { deferRest(`Not submitted: ${error.message}; the next run submits it.`); break; }
+ const entry = principal ? await deferral?.defer(error, { sourceId: row.source_id, subject: `${row.source_id}/${row.slug}`, principal }) : null;
+ if (entry) {
+ blocked.push({ source_id: row.source_id, slug: row.slug, code: DREAM_WRITE_DEFERRED_CODE,
+ reason: `Accepted and still pending after the publish wait (request_id ${entry.request_id}); the next run reconciles it before submitting more in this source (${writeStatusCommand(entry.request_id)}).` });
+ continue;
+ }
const code = typeof (error as { code?: unknown })?.code === 'string' ? (error as { code: string }).code : null;
const reason = error instanceof Error ? error.message : String(error);
if (code && DEFERRAL_CODES.has(code)) deferred++;
@@ -338,10 +374,11 @@ export async function purgeDeletedPagesCoordinated(engine: BrainEngine, olderTha
blocked.push({ source_id: row.source_id, slug: row.slug, code, reason });
}
}
- const failures = blocked.filter(b => !b.code || !DEFERRAL_CODES.has(b.code) && b.code !== 'writer_not_active' && b.code !== 'purge_parked' && b.code !== 'write_capacity_deferred' && b.code !== 'sync_delete_unreviewed');
+ const failures = blocked.filter(b => !b.code || !DEFERRAL_CODES.has(b.code) && b.code !== 'writer_not_active' && b.code !== 'purge_parked' && b.code !== 'write_capacity_deferred' && b.code !== 'sync_delete_unreviewed' && b.code !== DREAM_WRITE_DEFERRED_CODE);
const error = failed > 0 ? { class: 'ManagedPurgeFailed', code: 'managed_purge_failed',
message: `${failed} expired page(s) could not be purged through the coordinator: ${failures.slice(0, 3)
.map(b => `${b.source_id}/${b.slug}: ${b.reason}`).join('; ')}` } : undefined;
const parked = selection.parked.filter(park => !park.retried).length;
- return { slugs, count: slugs.length, blocked, deferred, failed, inactive: selection.inactive, parked, capacity_deferred: capacityDeferred, held: selection.held, ...(error ? { error } : {}) };
+ return { slugs, count: slugs.length, blocked, deferred, failed, inactive: selection.inactive, parked, capacity_deferred: capacityDeferred, held: selection.held,
+ ...(deferral ? { write_deferred: deferral.skipped, deferral } : {}), ...(error ? { error } : {}) };
}
diff --git a/test/cycle-synthesize-breaker.test.ts b/test/cycle-synthesize-breaker.test.ts
index baae269942..270041b5c1 100644
--- a/test/cycle-synthesize-breaker.test.ts
+++ b/test/cycle-synthesize-breaker.test.ts
@@ -211,6 +211,27 @@ describe('synthesize paid-loop breaker', () => {
} finally { await rig.cleanup(); }
}, 90_000);
+ test('W3: a transcript that grew between dying runs (a new content key each time) trips its per-transcript key', async () => {
+ const rig = await setupRig();
+ try {
+ const growing = await seedPassingFile(rig, '2026-08-14-growing.txt');
+ // Three dead runs, each on an earlier, shorter edition of the same file: no single content key reached the bound.
+ for (const [i, hash] of ['00000000000000a1', '00000000000000a2', '00000000000000a3'].entries()) {
+ await seedDead(rig, `dream:synth-v2:default:filename:2026-08-14-growing.txt:${hash}`, `dream-inline-${i + 1}`);
+ }
+ const fileKey = 'dream:synth-v2:@file:default:2026-08-14-growing.txt';
+ const details = await runPhase(rig);
+ expect(details.children_submitted).toBe(0);
+ expect(await liveRows(rig, keyFor('2026-08-14-growing.txt'))).toBe(0);
+ const refusal = details.skips.find(s => s.filePath === growing)!;
+ expect(refusal.reason).toStartWith('dream_breaker_tripped: 3 dead submissions');
+ expect(refusal.reason).toContain(`gbrain dream reset-key '${fileKey}'`);
+ const { resetDreamBreakerKey } = await import('../src/core/cycle/dream-breaker.ts');
+ await resetDreamBreakerKey(rig.engine, fileKey);
+ expect((await runPhase(rig)).children_submitted).toBe(1);
+ } finally { await rig.cleanup(); }
+ }, 90_000);
+
test('the daily cap counts dead rows whose key the queue released', async () => {
const rig = await setupRig();
try {
diff --git a/test/cycle-synthesize-no-candidates-w3.test.ts b/test/cycle-synthesize-no-candidates-w3.test.ts
new file mode 100644
index 0000000000..a65ed4c1a5
--- /dev/null
+++ b/test/cycle-synthesize-no-candidates-w3.test.ts
@@ -0,0 +1,111 @@
+/**
+ * W3 (GBRA-224, #5848): a synthesize window with zero candidates returns before
+ * triage, the manifest context and the fan-out: no model call, no embedding
+ * call, no job row. Every discovered transcript already synthesized is the
+ * real-world shape (a collector outage leaves only old files in the corpus).
+ * The status stays ok so outputs an earlier pass deferred still finish (#6757).
+ * The brain dir here is a plain directory with no git repository (repo-less).
+ */
+import { describe, test, expect, beforeAll, afterAll, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { createHash } from 'node:crypto';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { resetPgliteState } from './helpers/reset-pglite.ts';
+import { runPhaseSynthesize } from '../src/core/cycle/synthesize.ts';
+import { __setChatTransportForTests, __setEmbedTransportForTests, __setGenerateObjectTransportForTests, __setGenerateTextTransportForTests } from '../src/core/ai/gateway.ts';
+import { withEnv } from './helpers/with-env.ts';
+
+let engine: PGLiteEngine;
+let schemaVersion: string;
+let brainDir: string;
+let corpusDir: string;
+let providerCalls: string[];
+
+beforeAll(async () => {
+ engine = new PGLiteEngine();
+ await engine.connect({ engine: 'pglite' } as never);
+ await engine.initSchema();
+ schemaVersion = (await engine.getConfig('version')) ?? '7';
+}, 60_000);
+
+afterAll(async () => { await engine.disconnect(); });
+
+beforeEach(async () => {
+ await resetPgliteState(engine);
+ await engine.setConfig('version', schemaVersion);
+ brainDir = mkdtempSync(join(tmpdir(), 'gbrain-w3-nocand-brain-'));
+ corpusDir = mkdtempSync(join(tmpdir(), 'gbrain-w3-nocand-corpus-'));
+ await engine.setConfig('dream.synthesize.enabled', 'true');
+ await engine.setConfig('dream.synthesize.session_corpus_dir', corpusDir);
+ providerCalls = [];
+ const refuse = (kind: string) => async () => { providerCalls.push(kind); throw new Error(`no provider call expected (${kind})`); };
+ __setChatTransportForTests(refuse('chat') as never);
+ __setEmbedTransportForTests(refuse('embed') as never);
+ __setGenerateObjectTransportForTests(refuse('object') as never);
+ __setGenerateTextTransportForTests(refuse('text') as never);
+});
+
+afterEach(() => {
+ __setChatTransportForTests(null as never);
+ __setEmbedTransportForTests(null);
+ __setGenerateObjectTransportForTests(null);
+ __setGenerateTextTransportForTests(null);
+ rmSync(brainDir, { recursive: true, force: true });
+ rmSync(corpusDir, { recursive: true, force: true });
+});
+
+function writeTranscript(name: string): string {
+ const content = `conversation in ${name}\n`.repeat(200);
+ writeFileSync(join(corpusDir, name), content);
+ return createHash('sha256').update(content, 'utf8').digest('hex').slice(0, 16);
+}
+
+async function seedCompleted(key: string): Promise<void> {
+ await engine.executeRaw(
+ `INSERT INTO minion_jobs (submission_authority, name, queue, status, data, idempotency_key, finished_at)
+ VALUES ('{"version":1,"kind":"application"}'::jsonb, 'subagent', 'dream-inline-done', 'completed', jsonb_build_object('source_id', 'default'), $1, now())`,
+ [key]);
+}
+
+const jobRows = async () => (await engine.executeRaw<{ n: number }>('SELECT count(*)::int AS n FROM minion_jobs'))[0]!.n;
+const run = () => withEnv({ ANTHROPIC_API_KEY: 'sk-test-not-used', OPENAI_API_KEY: 'sk-test-not-used' },
+ () => runPhaseSynthesize(engine, { brainDir, dryRun: false }));
+
+describe('#5848 zero-candidate synthesize windows are free', () => {
+ test('every transcript already synthesized: returns before triage with reason no_candidates, no provider call, no job row', async () => {
+ for (const name of ['2026-09-10-old.txt', '2026-09-11-old.txt']) {
+ await seedCompleted(`dream:synth-v2:default:filename:${encodeURIComponent(name)}:${writeTranscript(name)}`);
+ }
+ const before = await jobRows();
+ const result = await run();
+ expect(result.status).toBe('ok');
+ expect(result.details).toMatchObject({ reason: 'no_candidates', transcripts_processed: 0, pages_written: 0,
+ synthesis_state: { candidates: 0, already_synthesized: 2 } });
+ expect(result.details).not.toHaveProperty('triage');
+ expect((result.details as { skips: Array<{ reason: string }> }).skips.map(s => s.reason)).toEqual(['already_synthesized_v2_single_chunk', 'already_synthesized_v2_single_chunk']);
+ expect(providerCalls).toEqual([]);
+ expect(await jobRows()).toBe(before);
+ expect(await engine.getConfig('dream.synthesize.last_completion_ts')).toBeTruthy();
+ }, 60_000);
+
+ test('an empty window returns no_candidates without a provider call', async () => {
+ const result = await run();
+ expect(result.status).toBe('ok');
+ expect(result.summary).toBe('no transcripts to process');
+ expect(result.details).toMatchObject({ reason: 'no_candidates', transcripts_discovered: 0 });
+ expect(providerCalls).toEqual([]);
+ expect(await jobRows()).toBe(0);
+ }, 60_000);
+
+ test('one new transcript next to synthesized ones still goes to triage', async () => {
+ const name = '2026-09-12-done.txt';
+ await seedCompleted(`dream:synth-v2:default:filename:${encodeURIComponent(name)}:${writeTranscript(name)}`);
+ writeTranscript('2026-09-13-new.txt');
+ await engine.setConfig('models.dream.triage', 'no-such-provider:judge');
+ const result = await run();
+ expect(result.details).not.toHaveProperty('reason', 'no_candidates');
+ expect(result.details).toMatchObject({ synthesis_state: { candidates: 1, already_synthesized: 1 } });
+ }, 60_000);
+});
diff --git a/test/dream-breaker-w3.test.ts b/test/dream-breaker-w3.test.ts
new file mode 100644
index 0000000000..b2ca2c82c5
--- /dev/null
+++ b/test/dream-breaker-w3.test.ts
@@ -0,0 +1,108 @@
+/**
+ * W3 (GBRA-224): the dream breaker's per-transcript key for content-hashed
+ * synthesize keys (#6753/#6924), and `gbrain dream reset-key` accepting every
+ * key `--list` prints, `dream:phase:` included (#7505).
+ */
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { resetPgliteState } from './helpers/reset-pglite.ts';
+import { countDeadDreamSubmissions, loadDreamBreaker, recordContainedPaidFailure, dreamSynthFileKey } from '../src/core/cycle/dream-breaker.ts';
+import { dreamPaidLoopCheck } from '../src/commands/doctor/checks/dream-breaker.ts';
+import { runDreamResetKey } from '../src/commands/dream-reset-key.ts';
+import { currentExitCode, _resetCliExitVerdictForTests } from '../src/core/cli-force-exit.ts';
+
+let engine: PGLiteEngine;
+let schemaVersion: string;
+
+beforeAll(async () => {
+ engine = new PGLiteEngine();
+ await engine.connect({});
+ await engine.initSchema();
+ schemaVersion = (await engine.getConfig('version')) ?? '7';
+}, 60_000);
+
+afterAll(async () => { await engine.disconnect(); });
+
+beforeEach(async () => {
+ await resetPgliteState(engine);
+ await engine.setConfig('version', schemaVersion);
+});
+
+async function seedDead(key: string, queue: string, sourceId = 'default'): Promise<void> {
+ await engine.executeRaw(
+ `INSERT INTO minion_jobs (submission_authority, name, queue, status, data, idempotency_key, created_at, finished_at)
+ VALUES ('{"version":1,"kind":"application"}'::jsonb, 'subagent', $1, 'dead', $2::text::jsonb, NULL, now() - interval '1 hour', now() - interval '1 hour')`,
+ [queue, JSON.stringify({ source_id: sourceId, __released_idempotency_key: key })]);
+}
+
+async function captured(run: () => Promise<void>): Promise<string> {
+ const lines: string[] = [];
+ const log = console.log;
+ const write = process.stdout.write.bind(process.stdout);
+ console.log = (...args: unknown[]) => { lines.push(args.join(' ')); };
+ process.stdout.write = ((chunk: string | Uint8Array) => { lines.push(String(chunk)); return true; }) as typeof process.stdout.write;
+ try { await run(); } finally { console.log = log; process.stdout.write = write; }
+ return lines.join('\n');
+}
+
+const synthKey = (identity: string, file: string, hash: string) => `dream:synth-v2:${encodeURIComponent(identity)}:filename:${encodeURIComponent(file)}:${hash}`;
+
+describe('per-transcript synthesize key', () => {
+ test('deaths across content keys of one transcript count under its file key; one content key reports only itself', async () => {
+ await seedDead(synthKey('default', 'one key.txt', '1111111111111111'), 'q1');
+ await seedDead(synthKey('default', 'one key.txt', '1111111111111111'), 'q2');
+ expect((await countDeadDreamSubmissions(engine)).map(row => row.base_key)).toEqual([synthKey('default', 'one key.txt', '1111111111111111')]);
+
+ // A managed brain keys by source/incarnation; the per-transcript key uses the source id, so it survives the switch (#6924).
+ await seedDead(synthKey('default', 'grows.txt', 'aaaaaaaaaaaaaaaa'), 'q3');
+ await seedDead(synthKey('default/1b0e7e7a-0000-4000-8000-000000000000', 'grows.txt', 'bbbbbbbbbbbbbbbb'), 'q4');
+ await seedDead(synthKey('default', 'grows.txt', 'cccccccccccccccc'), 'q5');
+ const fileKey = dreamSynthFileKey('default', 'grows.txt');
+ expect(fileKey).toBe('dream:synth-v2:@file:default:grows.txt');
+ const rows = await countDeadDreamSubmissions(engine);
+ expect(rows.find(row => row.base_key === fileKey)?.dead_submissions).toBe(3);
+ const breaker = (await loadDreamBreaker(engine))!;
+ expect(breaker.tripped.get(fileKey)).toBe(3);
+ expect([...breaker.tripped.keys()]).toEqual([fileKey]);
+ const check = await dreamPaidLoopCheck(engine);
+ expect(check.status).toBe('warn');
+ expect(check.message).toContain(fileKey);
+ });
+
+ test('chunks of one run count once, and other sources keep their own count', async () => {
+ await seedDead(`${synthKey('default', 'big.txt', 'aaaaaaaaaaaaaaaa')}:c0of2`, 'q1');
+ await seedDead(`${synthKey('default', 'big.txt', 'aaaaaaaaaaaaaaaa')}:c1of2`, 'q1');
+ await seedDead(synthKey('default', 'big.txt', 'bbbbbbbbbbbbbbbb'), 'q2');
+ await seedDead(synthKey('other', 'big.txt', 'cccccccccccccccc'), 'q3', 'other');
+ const rows = await countDeadDreamSubmissions(engine);
+ expect(rows.find(row => row.base_key === dreamSynthFileKey('default', 'big.txt'))?.dead_submissions).toBe(2);
+ expect(rows.find(row => row.base_key === dreamSynthFileKey('other', 'big.txt'))).toBeUndefined();
+ });
+});
+
+describe('dream reset-key accepts every key --list prints (#7505)', () => {
+ test('round trip: a contained phase key and a per-transcript key reset with the printed command', async () => {
+ for (let i = 0; i < 3; i++) await recordContainedPaidFailure(engine, 'synthesize_concepts', 'default');
+ for (const [i, hash] of ['aaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbb', 'cccccccccccccccc'].entries()) await seedDead(synthKey('default', 'loop.txt', hash), `q${i}`);
+ const listed = JSON.parse(await captured(() => runDreamResetKey(engine, ['--list', '--json']))) as { tripped: Array<{ base_key: string; reset_command: string }> };
+ const keys = listed.tripped.map(row => row.base_key).sort();
+ expect(keys).toEqual(['dream:phase:synthesize_concepts:default', 'dream:synth-v2:@file:default:loop.txt']);
+ for (const row of listed.tripped) {
+ const printed = row.reset_command.match(/^gbrain dream reset-key '(.+)'$/)![1]!;
+ expect(printed).toBe(row.base_key);
+ _resetCliExitVerdictForTests();
+ const out = await captured(() => runDreamResetKey(engine, [printed]));
+ expect(currentExitCode()).toBe(0);
+ expect(out).toContain(`Reset ${row.base_key}`);
+ }
+ expect(await captured(() => runDreamResetKey(engine, ['--list']))).toContain('No tripped dream keys');
+ expect((await dreamPaidLoopCheck(engine)).status).toBe('ok');
+ });
+
+ test('an unknown key family is still refused', async () => {
+ _resetCliExitVerdictForTests();
+ await captured(() => runDreamResetKey(engine, ['dream:other:key']));
+ expect(currentExitCode()).not.toBe(0);
+ _resetCliExitVerdictForTests();
+ });
+});
diff --git a/test/dream-write-deferral-w3.test.ts b/test/dream-write-deferral-w3.test.ts
new file mode 100644
index 0000000000..d671a329ef
--- /dev/null
+++ b/test/dream-write-deferral-w3.test.ts
@@ -0,0 +1,302 @@
+/**
+ * W3 (GBRA-224, #7587): a dream phase write accepted but still pending after
+ * its publish wait is a deferral, not a failure. The next pass reconciles the
+ * receipt before it submits anything (committed: done; failed: its real
+ * failure), a source with a pending receipt submits nothing, and after
+ * DREAM_WRITE_DEFERRAL_MAX_REPLAYS passes doctor's dream_write_deferred check
+ * names the receipt. Real PGLite and, with DATABASE_URL, Postgres; repo and
+ * repo-less brains.
+ */
+import { afterAll, beforeAll, expect, test } from 'bun:test';
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { BrainEngine } from '../src/core/engine.ts';
+import type { OperationContext } from '../src/core/operations.ts';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { runCycle } from '../src/core/cycle.ts';
+import { runPhaseConsolidate } from '../src/core/cycle/phases/consolidate.ts';
+import { purgeDeletedPagesCoordinated, purgePhaseStatus } from '../src/core/persistence/purge-deleted.ts';
+import { acquireWorktree, claimWorktree, getWorktreeBinding } from '../src/core/persistence/ownership.ts';
+import { requestPrincipalForContext, submitPageMutation } from '../src/core/persistence/page-mutations.ts';
+import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
+import { __setMaintenanceWriteWaitForTests } from '../src/core/persistence/maintenance-wait.ts';
+import { deferDreamWrite, readDreamWriteDeferrals, reconcileDreamWriteDeferrals, DREAM_WRITE_DEFERRAL_ENABLED_KEY,
+ DREAM_WRITE_DEFERRAL_MAX_REPLAYS, DREAM_WRITE_DEFERRALS_KEY } from '../src/core/cycle/dream-write-deferral.ts';
+import { readHealAudit, HEAL_AUDIT_KEY } from '../src/core/heal-audit.ts';
+import { dreamWriteDeferredCheck } from '../src/commands/doctor/checks/dream-write-deferred.ts';
+import { configureGateway, resetGateway } from '../src/core/ai/gateway.ts';
+import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
+import { withEnv } from './helpers/with-env.ts';
+import { testBackends } from './helpers/test-backends.ts';
+
+const backends = testBackends();
+const engines: BrainEngine[] = [];
+const dataDir = mkdtempSync(join(tmpdir(), 'gbrain-w3-deferral-db-'));
+let closePostgres: (() => Promise<void>) | undefined;
+beforeAll(async () => {
+ configureGateway({ embedding_model: 'openai:text-embedding-3-large', embedding_dimensions: 1536, env: {} });
+ if (backends.includes('pglite')) {
+ const engine = new PGLiteEngine();
+ await engine.connect({ database_path: dataDir }); await engine.initSchema(); engines.push(engine);
+ }
+ if (backends.includes('postgres')) {
+ const pg = await isolatedPersistencePostgres(process.env.DATABASE_URL!);
+ engines.push(pg.engine); closePostgres = pg.close;
+ }
+}, 120_000);
+afterAll(async () => {
+ for (const engine of engines) { await disposePersistenceConsumer(engine); await engine.disconnect(); }
+ await closePostgres?.(); resetGateway(); rmSync(dataDir, { recursive: true, force: true });
+});
+
+const logger = { info() {}, warn() {}, error() {} };
+function ctxFor(engine: BrainEngine, sourceId: string): OperationContext {
+ return { engine, sourceId, remote: false, config: { engine: engine.kind, embedding_disabled: true } as never, dryRun: false, logger };
+}
+
+/** A source with an active local canonical owner (repo brain) or none (repo-less); managed persistence on after `seed`. */
+async function fixture(opts: { repo: boolean; managed: boolean }, seed: (engine: BrainEngine, sourceId: string) => Promise<void>,
+ run: (engine: BrainEngine, sourceId: string, root: string) => Promise<void>) {
+ for (const engine of engines) {
+ const dir = mkdtempSync(join(tmpdir(), 'gbrain-w3-deferral-'));
+ const root = join(dir, 'brain'); mkdirSync(root);
+ const sourceId = `w3d-${randomUUID().slice(0, 8)}`;
+ try {
+ await withEnv({ GBRAIN_HOME: join(dir, 'home') }, async () => {
+ await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
+ await engine.executeRaw('DELETE FROM config WHERE key = ANY($1::text[])', [[DREAM_WRITE_DEFERRALS_KEY, HEAL_AUDIT_KEY, DREAM_WRITE_DEFERRAL_ENABLED_KEY]]);
+ await engine.executeRaw('INSERT INTO sources(id,name,local_path) VALUES($1,$1,$2)', [sourceId, opts.repo ? root : null]);
+ await engine.setConfig('sync.write_through', opts.repo ? 'true' : 'false');
+ if (opts.repo) await claimWorktree(engine, sourceId, root);
+ await seed(engine, sourceId);
+ if (opts.managed) await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
+ await run(engine, sourceId, root);
+ });
+ } finally {
+ __setMaintenanceWriteWaitForTests(null);
+ await disposePersistenceConsumer(engine);
+ await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
+ // Purges are brain-wide: leave no tombstone or deferral behind for the next case on this engine.
+ await engine.executeRaw('DELETE FROM pages WHERE source_id=$1', [sourceId]);
+ await engine.executeRaw('DELETE FROM config WHERE key = ANY($1::text[])', [[DREAM_WRITE_DEFERRALS_KEY, HEAL_AUDIT_KEY, DREAM_WRITE_DEFERRAL_ENABLED_KEY]]);
+ rmSync(dir, { recursive: true, force: true });
+ }
+ }
+}
+
+async function tombstone(engine: BrainEngine, sourceId: string, slug: string) {
+ const ctx = ctxFor(engine, sourceId);
+ await submitPageMutation(ctx, { operation: 'put_page', params: { slug, content: `---\ntitle: T\ntype: note\n---\nBody of ${slug}.`, request_id: randomUUID() } });
+ const snapshot = await engine.readPageSnapshot(slug, { sourceId });
+ await submitPageMutation(ctx, { operation: 'delete_page', params: { slug, expected_revision: snapshot!.revision, request_id: randomUUID() } });
+ await engine.executeRaw("UPDATE pages SET deleted_at=now() - interval '100 hours' WHERE source_id=$1 AND slug=$2", [sourceId, slug]);
+}
+
+const purgeRequests = (engine: BrainEngine, sourceId: string) => engine.executeRaw<{ request_id: string; state: string }>(
+ "SELECT request_id::text, state FROM persistence_requests WHERE source_id=$1 AND operation='delete_page' AND jsonb_path_exists(intent::jsonb, '$.** ? (@.purge == true)') ORDER BY sequence", [sourceId]);
+
+async function waitCommitted(engine: BrainEngine, requestId: string) {
+ for (let i = 0; i < 200; i++) {
+ const [row] = await engine.executeRaw<{ state: string }>('SELECT state FROM persistence_requests WHERE request_id=$1::uuid', [requestId]);
+ if (row?.state === 'committed') return;
+ await new Promise(resolve => setTimeout(resolve, 100));
+ }
+ throw new Error(`request ${requestId} did not commit`);
+}
+
+async function holdWriter(engine: BrainEngine, sourceId: string) {
+ return (await acquireWorktree((await getWorktreeBinding(engine, sourceId))!, 1000))!;
+}
+
+test('purge: a pending write defers (warn, never failed, no park), holds its source, escalates after the bound, then reconciles committed', async () => {
+ await fixture({ repo: true, managed: true }, async (engine, sourceId) => {
+ await tombstone(engine, sourceId, 'notes/old-a');
+ await tombstone(engine, sourceId, 'notes/old-b');
+ }, async (engine, sourceId) => {
+ __setMaintenanceWriteWaitForTests(300);
+ const lock = await holdWriter(engine, sourceId);
+ let requestId: string;
+ try {
+ const first = await purgeDeletedPagesCoordinated(engine, 72, { automatic: true });
+ expect(first.failed).toBe(0);
+ expect(first.error).toBeUndefined();
+ expect(first.write_deferred).toBe(2);
+ expect(purgePhaseStatus(first)).toBe('warn');
+ expect(first.blocked.map(b => b.code)).toEqual(['dream_write_deferred', 'dream_write_deferred']);
+ const submitted = await purgeRequests(engine, sourceId);
+ expect(submitted).toHaveLength(1);
+ requestId = submitted[0]!.request_id;
+ expect(await engine.executeRaw("SELECT 1 FROM op_checkpoints WHERE op='purge-deleted-park'")).toHaveLength(0);
+ const [deferral] = await readDreamWriteDeferrals(engine);
+ expect(deferral).toMatchObject({ phase: 'purge', source_id: sourceId, subject: `${sourceId}/notes/old-a`, request_id: requestId, replays: 0 });
+ expect(deferral!.receipt_id).toBeTruthy();
+ expect((await dreamWriteDeferredCheck(engine)).status).toBe('ok');
+
+ for (let pass = 1; pass <= DREAM_WRITE_DEFERRAL_MAX_REPLAYS; pass++) {
+ const held = await purgeDeletedPagesCoordinated(engine, 72, { automatic: true });
+ expect(held).toMatchObject({ failed: 0, write_deferred: 2, count: 0 });
+ expect((await readDreamWriteDeferrals(engine))[0]!.replays).toBe(pass);
+ }
+ // Held passes never resubmit.
+ expect(await purgeRequests(engine, sourceId)).toHaveLength(1);
+ const check = await dreamWriteDeferredCheck(engine);
+ expect(check.status).toBe('warn');
+ expect(check.message).toContain(requestId);
+ expect(check.message).toContain(`gbrain write-request -- ${requestId}`);
+ expect(check.fix).toMatchObject({ argv: ['gbrain', 'write-request', '--', requestId] });
+ // Stops counting at the bound.
+ await purgeDeletedPagesCoordinated(engine, 72, { automatic: true });
+ expect((await readDreamWriteDeferrals(engine))[0]!.replays).toBe(DREAM_WRITE_DEFERRAL_MAX_REPLAYS);
+ const audit = await readHealAudit(engine, 'dream_write_deferred');
+ expect(audit.map(row => [row.outcome, row.attempt, row.bound])).toEqual([
+ ['deferred', 0, 3], ['replayed', 1, 3], ['replayed', 2, 3], ['escalated', 3, 3]]);
+ } finally { await lock.release(); }
+
+ await waitCommitted(engine, requestId!);
+ const after = await purgeDeletedPagesCoordinated(engine, 72, { automatic: true });
+ expect(after).toMatchObject({ failed: 0, write_deferred: 0, count: 1, slugs: ['notes/old-b'] });
+ expect(after.deferral?.reconcile?.committed.map(entry => entry.request_id)).toEqual([requestId!]);
+ expect(await readDreamWriteDeferrals(engine)).toEqual([]);
+ expect((await dreamWriteDeferredCheck(engine)).status).toBe('ok');
+ // The committed purge was not resubmitted: one request for old-a, one new for old-b.
+ expect(await purgeRequests(engine, sourceId)).toHaveLength(2);
+ expect(await engine.readPageSnapshot('notes/old-a', { sourceId, includeDeleted: true })).toBeNull();
+ expect((await readHealAudit(engine, 'dream_write_deferred')).at(-1)?.outcome).toBe('committed');
+ });
+}, 120_000);
+
+test('purge through runCycle: a deferred write is a warn phase, the cycle is partial and never failed', async () => {
+ await fixture({ repo: true, managed: true }, async (engine, sourceId) => {
+ await tombstone(engine, sourceId, 'notes/old-c');
+ }, async (engine, sourceId, root) => {
+ __setMaintenanceWriteWaitForTests(300);
+ const lock = await holdWriter(engine, sourceId);
+ try {
+ const report = await runCycle(engine, { brainDir: root, phases: ['purge'] });
+ const phase = report.phases.find(p => p.phase === 'purge')!;
+ expect(phase.status).toBe('warn');
+ expect(phase.error).toBeUndefined();
+ expect(phase.details.purged_pages_write_deferred).toBe(1);
+ expect((phase.details.write_deferral as { pending: Array<{ status_command: string }> }).pending[0]!.status_command).toMatch(/^gbrain write-request -- /);
+ expect(report.status).not.toBe('failed');
+ } finally { await lock.release(); }
+ });
+}, 120_000);
+
+test('purge: a deferred receipt that ended failed is reported as its real failure; the candidate is re-validated, not resubmitted that pass', async () => {
+ await fixture({ repo: true, managed: true }, async (engine, sourceId) => {
+ await tombstone(engine, sourceId, 'notes/old-d');
+ }, async (engine, sourceId) => {
+ const ctx = ctxFor(engine, sourceId);
+ // A real terminal receipt: a purge bound to a revision the tombstone no longer has.
+ const requestId = randomUUID();
+ await submitPageMutation(ctx, { operation: 'delete_page', params: { slug: 'notes/old-d', source_id: sourceId, purge: true,
+ expected_revision: randomUUID(), request_id: requestId } }).catch(() => undefined);
+ const [receipt] = await engine.executeRaw<{ state: string; error_code: string | null }>('SELECT state, error_code FROM persistence_requests WHERE request_id=$1::uuid', [requestId]);
+ expect(['failed', 'conflict', 'cancelled']).toContain(receipt!.state);
+ await deferDreamWrite(engine, { phase: 'purge', sourceId, subject: `${sourceId}/notes/old-d`, requestId, principal: await requestPrincipalForContext(ctx) });
+ const before = (await purgeRequests(engine, sourceId)).length;
+ const result = await purgeDeletedPagesCoordinated(engine, 72, { automatic: true });
+ expect(result.deferral?.reconcile?.failed.map(entry => entry.request_id)).toEqual([requestId]);
+ const reported = result.blocked.find(b => b.slug === 'notes/old-d')!;
+ expect(reported.reason).toContain(requestId);
+ expect(reported.code).toBe(result.deferral!.reconcile!.failed[0]!.code);
+ expect(await purgeRequests(engine, sourceId)).toHaveLength(before);
+ expect(await readDreamWriteDeferrals(engine)).toEqual([]);
+ expect((await engine.readPageSnapshot('notes/old-d', { sourceId, includeDeleted: true }))?.page.deleted_at).toBeTruthy();
+ });
+}, 120_000);
+
+test('consolidate: a pending publication defers its source; the next pass reconciles it before submitting and writes the take once', async () => {
+ const vector = `[${[1, ...Array(1535).fill(0)].join(',')}]`;
+ await fixture({ repo: true, managed: true }, async (engine, sourceId) => {
+ await submitPageMutation(ctxFor(engine, sourceId), { operation: 'put_page', params: {
+ slug: 'people/example', content: '---\ntitle: Example\ntype: note\n---\nExample evidence.', request_id: randomUUID() } });
+ for (const [i, word] of ['alpha', 'beta', 'gamma'].entries()) {
+ await engine.executeRaw(`INSERT INTO facts(source_id,entity_slug,fact,kind,source,visibility,confidence,valid_from,embedding,embedding_model,embedded_text_hash)
+ VALUES($1,'people/example',$2,'fact','test','world',0.9,$3::timestamptz,$4::vector,'openai:text-embedding-3-large',md5($2))`,
+ [sourceId, `Example claim ${word}`, `2026-01-0${i + 1}T00:00:00Z`, vector]);
+ }
+ }, async (engine, sourceId) => {
+ __setMaintenanceWriteWaitForTests(300);
+ const lock = await holdWriter(engine, sourceId);
+ let requestId: string;
+ try {
+ const first = await runPhaseConsolidate(engine, { sourceId, minOldestAgeMs: 0 });
+ expect(first.status).toBe('warn');
+ expect(first.error).toBeUndefined();
+ expect(first.details.buckets_deferred).toBe(1);
+ expect(first.details.buckets_failed).toBe(0);
+ const [deferral] = await readDreamWriteDeferrals(engine);
+ expect(deferral).toMatchObject({ phase: 'consolidate', source_id: sourceId, subject: `${sourceId}/people/example` });
+ requestId = deferral!.request_id;
+ const held = await runPhaseConsolidate(engine, { sourceId, minOldestAgeMs: 0 });
+ expect(held.details).toMatchObject({ buckets_deferred: 1, facts_consolidated: 0 });
+ } finally { await lock.release(); }
+ await waitCommitted(engine, requestId!);
+ const requestsBefore = await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1', [sourceId]);
+ const after = await runPhaseConsolidate(engine, { sourceId, minOldestAgeMs: 0 });
+ expect(after.status).toBe('ok');
+ expect((after.details.write_deferral as { reconciled_committed: string[] }).reconciled_committed).toEqual([requestId!]);
+ expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1', [sourceId])).toHaveLength(requestsBefore.length);
+ const page = (await engine.readPageSnapshot('people/example', { sourceId }))!;
+ expect(await engine.executeRaw('SELECT id FROM takes WHERE page_id=$1', [page.page.id])).toHaveLength(1);
+ expect(await readDreamWriteDeferrals(engine)).toEqual([]);
+ });
+}, 120_000);
+
+test('dream.write_deferral.enabled=false keeps the old behavior: a pending purge fails the run', async () => {
+ await fixture({ repo: true, managed: true }, async (engine, sourceId) => {
+ await tombstone(engine, sourceId, 'notes/old-e');
+ }, async (engine, sourceId) => {
+ await engine.setConfig(DREAM_WRITE_DEFERRAL_ENABLED_KEY, 'false');
+ __setMaintenanceWriteWaitForTests(300);
+ const lock = await holdWriter(engine, sourceId);
+ try {
+ const result = await purgeDeletedPagesCoordinated(engine, 72, { automatic: true });
+ expect(result.failed).toBe(1);
+ expect(result.error?.code).toBe('managed_purge_failed');
+ expect(result.write_deferred).toBeUndefined();
+ expect(await readDreamWriteDeferrals(engine)).toEqual([]);
+ } finally { await lock.release(); }
+ });
+}, 120_000);
+
+test('repo-less managed source: a deferred write is reconciled from database state alone', async () => {
+ await fixture({ repo: false, managed: true }, async (engine, sourceId) => {
+ await tombstone(engine, sourceId, 'notes/old-f');
+ }, async (engine, sourceId) => {
+ __setMaintenanceWriteWaitForTests(0);
+ const first = await purgeDeletedPagesCoordinated(engine, 72, { automatic: true });
+ expect(first.failed).toBe(0);
+ expect(first.error).toBeUndefined();
+ const submitted = await purgeRequests(engine, sourceId);
+ expect(submitted).toHaveLength(1);
+ // A zero publish wait returns before the consumer can publish, so the write is accepted and pending.
+ expect(first.write_deferred).toBe(1);
+ expect((await readDreamWriteDeferrals(engine))[0]).toMatchObject({ phase: 'purge', source_id: sourceId });
+ await waitCommitted(engine, submitted[0]!.request_id);
+ const next = await reconcileDreamWriteDeferrals(engine, 'purge');
+ expect(next.committed.map(entry => entry.request_id)).toEqual([submitted[0]!.request_id]);
+ expect(await readDreamWriteDeferrals(engine)).toEqual([]);
+ expect(await engine.readPageSnapshot('notes/old-f', { sourceId, includeDeleted: true })).toBeNull();
+ });
+}, 120_000);
+
+test('repo-less unmanaged brain: purge and consolidate run as before and record no deferral', async () => {
+ await fixture({ repo: false, managed: false }, async (engine, sourceId) => {
+ await engine.executeRaw(`INSERT INTO pages(source_id,slug,type,title,compiled_truth,deleted_at) VALUES($1,'notes/gone','note','Gone','Body',now() - interval '100 hours')`, [sourceId]);
+ }, async (engine, sourceId) => {
+ const purged = await purgeDeletedPagesCoordinated(engine, 72, { automatic: true });
+ expect(purged.failed).toBe(0);
+ expect(purged.slugs).toContain('notes/gone');
+ expect(purged.write_deferred).toBeUndefined();
+ const consolidated = await runPhaseConsolidate(engine, { sourceId, minOldestAgeMs: 0 });
+ expect(consolidated.status).not.toBe('fail');
+ expect(consolidated.details.write_deferral).toBeUndefined();
+ expect(await readDreamWriteDeferrals(engine)).toEqual([]);
+ expect((await dreamWriteDeferredCheck(engine)).status).toBe('ok');
+ });
+}, 120_000);
diff --git a/test/e2e/dream-write-deferral-w3-postgres.test.ts b/test/e2e/dream-write-deferral-w3-postgres.test.ts
new file mode 100644
index 0000000000..343602b2f5
--- /dev/null
+++ b/test/e2e/dream-write-deferral-w3-postgres.test.ts
@@ -0,0 +1,3 @@
+import { registerPostgresTests } from '../helpers/test-backends.ts';
+
+await registerPostgresTests(() => import('../dream-write-deferral-w3.test.ts'));
diff --git a/test/e2e/embedding-restamp-w3-postgres.test.ts b/test/e2e/embedding-restamp-w3-postgres.test.ts
new file mode 100644
index 0000000000..e4a05b8f2b
--- /dev/null
+++ b/test/e2e/embedding-restamp-w3-postgres.test.ts
@@ -0,0 +1,3 @@
+import { registerPostgresTests } from '../helpers/test-backends.ts';
+
+await registerPostgresTests(() => import('../embedding-restamp-w3.test.ts'));
diff --git a/test/e2e/health-coverage-soft-deleted-w3-postgres.test.ts b/test/e2e/health-coverage-soft-deleted-w3-postgres.test.ts
new file mode 100644
index 0000000000..17e285ac63
--- /dev/null
+++ b/test/e2e/health-coverage-soft-deleted-w3-postgres.test.ts
@@ -0,0 +1,3 @@
+import { registerPostgresTests } from '../helpers/test-backends.ts';
+
+await registerPostgresTests(() => import('../health-coverage-soft-deleted-w3.test.ts'));
diff --git a/test/embedding-restamp-w3.test.ts b/test/embedding-restamp-w3.test.ts
new file mode 100644
index 0000000000..51820197a5
--- /dev/null
+++ b/test/embedding-restamp-w3.test.ts
@@ -0,0 +1,170 @@
+/**
+ * W3 (GBRA-224, #5527 class): the free signature restamp. A page whose chunks
+ * all hold current-model vectors but whose stored signature is missing or
+ * names another model gets the current signature with no provider call. The
+ * stamp is guarded: a content edit or chunk rewrite between the read and the
+ * stamp makes it match nothing (round-2 T16), and content and vectors never
+ * change. Bounded per run, switchable, audited; repeated failures escalate to
+ * doctor's embedding_restamp_stalled. Real PGLite and, with DATABASE_URL,
+ * Postgres. These brains have no git repository (repo-less).
+ */
+import { afterAll, afterEach, beforeAll, expect, test } from 'bun:test';
+import type { BrainEngine } from '../src/core/engine.ts';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { resetPgliteState } from './helpers/reset-pglite.ts';
+import { installFixtureChunks } from './helpers/page-projection.ts';
+import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
+import { testBackends } from './helpers/test-backends.ts';
+import { resolveActiveEmbeddingColumnFromEngine } from '../src/core/search/embedding-column.ts';
+import { __setEmbedTransportForTests } from '../src/core/ai/gateway.ts';
+import { restampCurrentSpaceSignatures, __setRestampBeforeStampForTests, EMBEDDING_RESTAMP_ENABLED_KEY,
+ EMBEDDING_RESTAMP_FAILURE_BOUND, EMBEDDING_RESTAMP_CODE } from '../src/core/embedding-restamp.ts';
+import { readHealAudit } from '../src/core/heal-audit.ts';
+import { embeddingRestampStalledCheck } from '../src/commands/doctor/checks/embedding-restamp.ts';
+
+const backends = testBackends();
+const engines: Array<{ name: string; engine: BrainEngine; reset: () => Promise<void> }> = [];
+let closePostgres: (() => Promise<void>) | undefined;
+let embedCalls = 0;
+const MODEL = 'openai:example-embedding';
+
+beforeAll(async () => {
+ if (backends.includes('pglite')) {
+ const engine = new PGLiteEngine();
+ await engine.connect({}); await engine.initSchema();
+ const version = await engine.getConfig('version');
+ engines.push({ name: 'pglite', engine, reset: async () => { await resetPgliteState(engine); if (version) await engine.setConfig('version', version); } });
+ }
+ if (backends.includes('postgres')) {
+ const pg = await isolatedPersistencePostgres(process.env.DATABASE_URL!);
+ closePostgres = pg.close;
+ engines.push({ name: 'postgres', engine: pg.engine, reset: async () => {
+ await pg.engine.executeRaw('DELETE FROM pages');
+ await pg.engine.executeRaw('DELETE FROM config WHERE key = ANY($1::text[])', [['heal.audit', EMBEDDING_RESTAMP_ENABLED_KEY]]);
+ } });
+ }
+ __setEmbedTransportForTests((async () => { embedCalls++; throw new Error('no provider call expected'); }) as never);
+}, 120_000);
+
+afterEach(() => { __setRestampBeforeStampForTests(null); });
+afterAll(async () => {
+ __setEmbedTransportForTests(null);
+ for (const { engine, name } of engines) if (name === 'pglite') await engine.disconnect();
+ await closePostgres?.();
+});
+
+async function activeDims(engine: BrainEngine): Promise<{ column: string; dims: number }> {
+ const column = (await resolveActiveEmbeddingColumnFromEngine(engine, { fallbackToLegacy: true })).name;
+ const [row] = await engine.executeRaw<{ dim: number }>(
+ `SELECT atttypmod AS dim FROM pg_attribute WHERE attrelid = 'content_chunks'::regclass AND attname = $1 AND attnum > 0`, [column]);
+ return { column, dims: Number(row!.dim) };
+}
+
+async function seedPage(engine: BrainEngine, slug: string, dims: number, opts: { signature?: string; chunks?: number } = {}): Promise<void> {
+ await engine.putPage(slug, { type: 'note', title: slug, compiled_truth: `# ${slug}\n\nbody of ${slug}` });
+ await installFixtureChunks(engine, slug, Array.from({ length: opts.chunks ?? 2 }, (_, i) => ({
+ chunk_index: i, chunk_text: `${slug} chunk ${i}`, chunk_source: 'compiled_truth' as const,
+ embedding: new Float32Array(dims).fill(0.25), model: MODEL })));
+ if (opts.signature) await engine.setPageEmbeddingSignature(slug, { signature: opts.signature });
+}
+
+const signatureOf = async (engine: BrainEngine, slug: string) => (await engine.executeRaw<{ s: string | null }>(
+ `SELECT embedding_signature AS s FROM pages WHERE slug = $1 AND source_id = 'default'`, [slug]))[0]?.s ?? null;
+
+async function vectorsAndContent(engine: BrainEngine, column: string): Promise<string> {
+ const rows = await engine.executeRaw<{ v: string }>(
+ `SELECT string_agg(p.slug || ':' || p.knowledge_revision::text || ':' || md5(cc.chunk_text) || ':' || md5(cc."${column}"::text) || ':' || COALESCE(cc.embedded_text_hash, ''), '|' ORDER BY p.slug, cc.chunk_index) AS v
+ FROM pages p JOIN content_chunks cc ON cc.page_id = p.id`);
+ return rows[0]!.v;
+}
+
+for (const backend of backends) {
+ const ctx = () => engines.find(e => e.name === backend)!;
+
+ test(`[${backend}] stamps only pages whose every chunk is current, with zero provider requests and no content or vector change`, async () => {
+ const { engine, reset } = ctx(); await reset();
+ const { column, dims } = await activeDims(engine);
+ const signature = `${MODEL}:${dims}`;
+ await seedPage(engine, 'notes/unstamped', dims);
+ await seedPage(engine, 'notes/old-signature', dims, { signature: 'openai:retired-model:1536' });
+ await seedPage(engine, 'notes/already-current', dims, { signature });
+ await seedPage(engine, 'notes/foreign-chunk', dims, { signature: 'openai:retired-model:1536' });
+ await engine.executeRaw(`UPDATE content_chunks SET model = 'openai:retired-model' WHERE chunk_index = 1
+ AND page_id = (SELECT id FROM pages WHERE slug = 'notes/foreign-chunk')`);
+ await seedPage(engine, 'notes/skipped', dims);
+ await engine.executeRaw(`UPDATE pages SET frontmatter = COALESCE(frontmatter, '{}'::jsonb) || '{"embed_skip": true}'::jsonb WHERE slug = 'notes/skipped'`);
+ await seedPage(engine, 'notes/deleted', dims);
+ await engine.executeRaw(`UPDATE pages SET deleted_at = now() WHERE slug = 'notes/deleted'`);
+ const before = await vectorsAndContent(engine, column);
+ embedCalls = 0;
+
+ const result = (await restampCurrentSpaceSignatures(engine, signature))!;
+ expect(result).toMatchObject({ pages: 2, chunks: 4, rejected: 0, capped: false, failed_runs: 0 });
+ expect(embedCalls).toBe(0);
+ expect(await signatureOf(engine, 'notes/unstamped')).toBe(signature);
+ expect(await signatureOf(engine, 'notes/old-signature')).toBe(signature);
+ expect(await signatureOf(engine, 'notes/foreign-chunk')).toBe('openai:retired-model:1536');
+ expect(await signatureOf(engine, 'notes/skipped')).toBeNull();
+ expect(await signatureOf(engine, 'notes/deleted')).toBeNull();
+ expect(await vectorsAndContent(engine, column)).toBe(before);
+ expect((await readHealAudit(engine, EMBEDDING_RESTAMP_CODE)).at(-1)).toMatchObject({ outcome: 'restamped', attempt: 0 });
+ expect((await restampCurrentSpaceSignatures(engine, signature))!.pages).toBe(0);
+ }, 60_000);
+
+ test(`[${backend}] a content edit or chunk rewrite between the read and the stamp makes the stamp match nothing (T16)`, async () => {
+ const { engine, reset } = ctx(); await reset();
+ const { column, dims } = await activeDims(engine);
+ const signature = `${MODEL}:${dims}`;
+ await seedPage(engine, 'notes/edited', dims, { signature: 'openai:retired-model:1536' });
+ await seedPage(engine, 'notes/rewritten', dims, { signature: 'openai:retired-model:1536' });
+ const ids = Object.fromEntries((await engine.executeRaw<{ id: number; slug: string }>(`SELECT id, slug FROM pages`)).map(r => [r.slug, Number(r.id)]));
+ __setRestampBeforeStampForTests(async pageId => {
+ // The signature stays the same in both cases: only the content generation moves.
+ if (pageId === ids['notes/edited']) await engine.putPage('notes/edited', { type: 'note', title: 'notes/edited', compiled_truth: '# edited\n\nnew body' });
+ if (pageId === ids['notes/rewritten']) await engine.executeRaw(`UPDATE content_chunks SET chunk_text = chunk_text || ' (rewritten)' WHERE page_id = $1 AND chunk_index = 0`, [pageId]);
+ });
+ const before = await vectorsAndContent(engine, column);
+ const result = (await restampCurrentSpaceSignatures(engine, signature))!;
+ expect(result).toMatchObject({ pages: 0, rejected: 2 });
+ expect(await signatureOf(engine, 'notes/edited')).toBe('openai:retired-model:1536');
+ expect(await signatureOf(engine, 'notes/rewritten')).toBe('openai:retired-model:1536');
+ __setRestampBeforeStampForTests(null);
+ expect(await vectorsAndContent(engine, column)).not.toBe(before);
+ const after = await vectorsAndContent(engine, column);
+ await restampCurrentSpaceSignatures(engine, signature);
+ expect(await vectorsAndContent(engine, column)).toBe(after);
+ expect(await signatureOf(engine, 'notes/rewritten')).toBe('openai:retired-model:1536');
+ }, 60_000);
+
+ test(`[${backend}] bounded per run, off by switch, and repeated failures escalate to doctor then clear`, async () => {
+ const { engine, reset } = ctx(); await reset();
+ const { dims } = await activeDims(engine);
+ const signature = `${MODEL}:${dims}`;
+ for (const slug of ['notes/a', 'notes/b', 'notes/c']) await seedPage(engine, slug, dims, { chunks: 1 });
+
+ await engine.setConfig(EMBEDDING_RESTAMP_ENABLED_KEY, 'false');
+ expect(await restampCurrentSpaceSignatures(engine, signature)).toBeNull();
+ expect(await signatureOf(engine, 'notes/a')).toBeNull();
+ expect((await embeddingRestampStalledCheck(engine)).status).toBe('ok');
+ await engine.setConfig(EMBEDDING_RESTAMP_ENABLED_KEY, 'true');
+
+ expect(await restampCurrentSpaceSignatures(engine, signature, { maxPages: 2 })).toMatchObject({ pages: 2, capped: true, max_pages: 2 });
+ expect(await signatureOf(engine, 'notes/c')).toBeNull();
+
+ __setRestampBeforeStampForTests(async () => { throw new Error('simulated stamp failure'); });
+ for (let attempt = 1; attempt <= EMBEDDING_RESTAMP_FAILURE_BOUND; attempt++) {
+ expect((await embeddingRestampStalledCheck(engine)).status).toBe('ok');
+ expect(await restampCurrentSpaceSignatures(engine, signature)).toMatchObject({ failed_runs: attempt, error: 'simulated stamp failure' });
+ }
+ const stalled = await embeddingRestampStalledCheck(engine);
+ expect(stalled.status).toBe('warn');
+ expect(stalled.message).toContain('simulated stamp failure');
+ expect((await readHealAudit(engine, EMBEDDING_RESTAMP_CODE)).at(-1)).toMatchObject({ outcome: 'escalated', attempt: EMBEDDING_RESTAMP_FAILURE_BOUND });
+
+ __setRestampBeforeStampForTests(null);
+ expect(await restampCurrentSpaceSignatures(engine, signature)).toMatchObject({ pages: 1, capped: false, failed_runs: 0 });
+ expect(await signatureOf(engine, 'notes/c')).toBe(signature);
+ expect((await embeddingRestampStalledCheck(engine)).status).toBe('ok');
+ expect(embedCalls).toBe(0);
+ }, 60_000);
+}
diff --git a/test/fixtures/goldens/doctor/content-pglite-human.json b/test/fixtures/goldens/doctor/content-pglite-human.json
index 0f008293f0..49aaeb8a9e 100644
--- a/test/fixtures/goldens/doctor/content-pglite-human.json
+++ b/test/fixtures/goldens/doctor/content-pglite-human.json
@@ -117,6 +117,8 @@
" [OK] foreign_ownership_marker: Every ownership marker beside a source checkout belongs to this brain.",
" [OK] coordination_lock_location: Every checkout's recorded coordination lock agrees with GBRAIN_COORDINATION_HOME, or the variable does not apply.",
" [OK] unbound_source: No page was written database-only to an unbound source.",
+ " [OK] dream_write_deferred: No deferred dream writes",
+ " [OK] embedding_restamp_stalled: The embedding signature restamp is running clean",
" [OK] writer_version: Every writer that admitted or published a request in the last 7 days is v0.60.5.0 or newer.",
" [OK] segmented_storage: Segmented page storage is on: pages over 1 MiB are stored in segments, up to 134217728 bytes on this PGLite brain.",
" [OK] self_capture: No session corpus is configured; nothing to classify.",
diff --git a/test/fixtures/goldens/doctor/content-pglite-json.json b/test/fixtures/goldens/doctor/content-pglite-json.json
index 42a2fbc6e3..d8ce49bbce 100644
--- a/test/fixtures/goldens/doctor/content-pglite-json.json
+++ b/test/fixtures/goldens/doctor/content-pglite-json.json
@@ -1579,6 +1579,30 @@
"name": "unbound_source",
"status": "ok"
},
+ {
+ "category": "ops",
+ "details": {
+ "bound": 3,
+ "enabled": true,
+ "items": [],
+ "pending": 0
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No deferred dream writes",
+ "name": "dream_write_deferred",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "bound": 3,
+ "enabled": true
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "The embedding signature restamp is running clean",
+ "name": "embedding_restamp_stalled",
+ "status": "ok"
+ },
{
"category": "ops",
"details": {
diff --git a/test/fixtures/goldens/doctor/hot-checks-pglite-json.json b/test/fixtures/goldens/doctor/hot-checks-pglite-json.json
index c7008ff35a..eb7f602a90 100644
--- a/test/fixtures/goldens/doctor/hot-checks-pglite-json.json
+++ b/test/fixtures/goldens/doctor/hot-checks-pglite-json.json
@@ -1758,6 +1758,30 @@
"name": "unbound_source",
"status": "ok"
},
+ {
+ "category": "ops",
+ "details": {
+ "bound": 3,
+ "enabled": true,
+ "items": [],
+ "pending": 0
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No deferred dream writes",
+ "name": "dream_write_deferred",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "bound": 3,
+ "enabled": true
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "The embedding signature restamp is running clean",
+ "name": "embedding_restamp_stalled",
+ "status": "ok"
+ },
{
"category": "ops",
"details": {
@@ -6516,6 +6540,30 @@
"name": "unbound_source",
"status": "ok"
},
+ {
+ "category": "ops",
+ "details": {
+ "bound": 3,
+ "enabled": true,
+ "items": [],
+ "pending": 0
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No deferred dream writes",
+ "name": "dream_write_deferred",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "bound": 3,
+ "enabled": true
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "The embedding signature restamp is running clean",
+ "name": "embedding_restamp_stalled",
+ "status": "ok"
+ },
{
"category": "ops",
"details": {
diff --git a/test/fixtures/goldens/doctor/hot-checks-postgres-json.json b/test/fixtures/goldens/doctor/hot-checks-postgres-json.json
index b5ca713860..8fc60037ac 100644
--- a/test/fixtures/goldens/doctor/hot-checks-postgres-json.json
+++ b/test/fixtures/goldens/doctor/hot-checks-postgres-json.json
@@ -1750,6 +1750,30 @@
"name": "unbound_source",
"status": "ok"
},
+ {
+ "category": "ops",
+ "details": {
+ "bound": 3,
+ "enabled": true,
+ "items": [],
+ "pending": 0
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No deferred dream writes",
+ "name": "dream_write_deferred",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "bound": 3,
+ "enabled": true
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "The embedding signature restamp is running clean",
+ "name": "embedding_restamp_stalled",
+ "status": "ok"
+ },
{
"category": "ops",
"details": {
@@ -6509,6 +6533,30 @@
"name": "unbound_source",
"status": "ok"
},
+ {
+ "category": "ops",
+ "details": {
+ "bound": 3,
+ "enabled": true,
+ "items": [],
+ "pending": 0
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No deferred dream writes",
+ "name": "dream_write_deferred",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "bound": 3,
+ "enabled": true
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "The embedding signature restamp is running clean",
+ "name": "embedding_restamp_stalled",
+ "status": "ok"
+ },
{
"category": "ops",
"details": {
diff --git a/test/fixtures/goldens/doctor/json-pglite-degraded.json b/test/fixtures/goldens/doctor/json-pglite-degraded.json
index 8ee2699d13..b846e1d7b0 100644
--- a/test/fixtures/goldens/doctor/json-pglite-degraded.json
+++ b/test/fixtures/goldens/doctor/json-pglite-degraded.json
@@ -1456,6 +1456,30 @@
"name": "unbound_source",
"status": "ok"
},
+ {
+ "category": "ops",
+ "details": {
+ "bound": 3,
+ "enabled": true,
+ "items": [],
+ "pending": 0
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No deferred dream writes",
+ "name": "dream_write_deferred",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "bound": 3,
+ "enabled": true
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "The embedding signature restamp is running clean",
+ "name": "embedding_restamp_stalled",
+ "status": "ok"
+ },
{
"category": "ops",
"details": {
diff --git a/test/fixtures/goldens/doctor/json-pglite-fresh.json b/test/fixtures/goldens/doctor/json-pglite-fresh.json
index 0ddea282b6..2958858d8f 100644
--- a/test/fixtures/goldens/doctor/json-pglite-fresh.json
+++ b/test/fixtures/goldens/doctor/json-pglite-fresh.json
@@ -1512,6 +1512,30 @@
"name": "unbound_source",
"status": "ok"
},
+ {
+ "category": "ops",
+ "details": {
+ "bound": 3,
+ "enabled": true,
+ "items": [],
+ "pending": 0
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No deferred dream writes",
+ "name": "dream_write_deferred",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "bound": 3,
+ "enabled": true
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "The embedding signature restamp is running clean",
+ "name": "embedding_restamp_stalled",
+ "status": "ok"
+ },
{
"category": "ops",
"details": {
diff --git a/test/fixtures/goldens/doctor/json-postgres-fresh.json b/test/fixtures/goldens/doctor/json-postgres-fresh.json
index 105b4d76eb..0cc565363d 100644
--- a/test/fixtures/goldens/doctor/json-postgres-fresh.json
+++ b/test/fixtures/goldens/doctor/json-postgres-fresh.json
@@ -1504,6 +1504,30 @@
"name": "unbound_source",
"status": "ok"
},
+ {
+ "category": "ops",
+ "details": {
+ "bound": 3,
+ "enabled": true,
+ "items": [],
+ "pending": 0
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "No deferred dream writes",
+ "name": "dream_write_deferred",
+ "status": "ok"
+ },
+ {
+ "category": "ops",
+ "details": {
+ "bound": 3,
+ "enabled": true
+ },
+ "elapsed_ms": "<volatile>",
+ "message": "The embedding signature restamp is running clean",
+ "name": "embedding_restamp_stalled",
+ "status": "ok"
+ },
{
"category": "ops",
"details": {
diff --git a/test/fixtures/goldens/doctor/registry-build-checks.json b/test/fixtures/goldens/doctor/registry-build-checks.json
index 510efd0f22..8b5229d626 100644
--- a/test/fixtures/goldens/doctor/registry-build-checks.json
+++ b/test/fixtures/goldens/doctor/registry-build-checks.json
@@ -513,6 +513,14 @@
"category": "brain",
"name": "unbound_source"
},
+ {
+ "category": "ops",
+ "name": "dream_write_deferred"
+ },
+ {
+ "category": "ops",
+ "name": "embedding_restamp_stalled"
+ },
{
"category": "ops",
"name": "writer_version"
diff --git a/test/fixtures/goldens/doctor/registry-report-remote.json b/test/fixtures/goldens/doctor/registry-report-remote.json
index 697343e2c4..fb58311692 100644
--- a/test/fixtures/goldens/doctor/registry-report-remote.json
+++ b/test/fixtures/goldens/doctor/registry-report-remote.json
@@ -249,6 +249,14 @@
"category": "ops",
"name": "dream_paid_loop"
},
+ {
+ "category": "ops",
+ "name": "dream_write_deferred"
+ },
+ {
+ "category": "ops",
+ "name": "embedding_restamp_stalled"
+ },
{
"category": "ops",
"name": "writer_version"
diff --git a/test/health-coverage-soft-deleted-w3.test.ts b/test/health-coverage-soft-deleted-w3.test.ts
new file mode 100644
index 0000000000..cebd9dea73
--- /dev/null
+++ b/test/health-coverage-soft-deleted-w3.test.ts
@@ -0,0 +1,81 @@
+/**
+ * W3 (GBRA-224, #7212): health's embed_coverage counts the same live,
+ * eligible chunks as missing_embeddings and the stale paths. Chunks retained
+ * on a soft-deleted page no longer lower coverage; a live unembedded page
+ * still does, embed_skip pages stay out, and a source scope is kept. Real
+ * PGLite and, with DATABASE_URL, Postgres; repo-less brains.
+ */
+import { afterAll, beforeAll, expect, test } from 'bun:test';
+import type { BrainEngine } from '../src/core/engine.ts';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { resetPgliteState } from './helpers/reset-pglite.ts';
+import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
+import { testBackends } from './helpers/test-backends.ts';
+import { resolveActiveEmbeddingColumnFromEngine } from '../src/core/search/embedding-column.ts';
+
+const backends = testBackends();
+const engines: Array<{ name: string; engine: BrainEngine; reset: () => Promise<void> }> = [];
+let closePostgres: (() => Promise<void>) | undefined;
+
+beforeAll(async () => {
+ if (backends.includes('pglite')) {
+ const engine = new PGLiteEngine();
+ await engine.connect({}); await engine.initSchema();
+ const version = await engine.getConfig('version');
+ engines.push({ name: 'pglite', engine, reset: async () => { await resetPgliteState(engine); if (version) await engine.setConfig('version', version); } });
+ }
+ if (backends.includes('postgres')) {
+ const pg = await isolatedPersistencePostgres(process.env.DATABASE_URL!);
+ closePostgres = pg.close;
+ engines.push({ name: 'postgres', engine: pg.engine, reset: async () => { await pg.engine.executeRaw('DELETE FROM pages'); } });
+ }
+}, 120_000);
+
+afterAll(async () => {
+ for (const { engine, name } of engines) if (name === 'pglite') await engine.disconnect();
+ await closePostgres?.();
+});
+
+async function seed(engine: BrainEngine, slug: string, embedded: boolean, sourceId = 'default'): Promise<void> {
+ if (sourceId !== 'default') await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1) ON CONFLICT (id) DO NOTHING', [sourceId]);
+ await engine.putPage(slug, { type: 'note', title: slug, compiled_truth: `# ${slug}` }, { sourceId });
+ await engine.upsertChunks(slug, [0, 1].map(i => ({ chunk_index: i, chunk_text: `${slug} chunk ${i}`, chunk_source: 'compiled_truth' as const, token_count: 4 })), { sourceId });
+ if (!embedded) return;
+ const column = (await resolveActiveEmbeddingColumnFromEngine(engine, { fallbackToLegacy: true })).name;
+ const [{ dim }] = await engine.executeRaw<{ dim: number }>(
+ `SELECT atttypmod AS dim FROM pg_attribute WHERE attrelid = 'content_chunks'::regclass AND attname = $1 AND attnum > 0`, [column]);
+ await engine.executeRaw(
+ `UPDATE content_chunks SET "${column}" = ('[' || array_to_string(array_fill(0.1::real, ARRAY[$1::int]), ',') || ']')::vector
+ WHERE page_id = (SELECT id FROM pages WHERE slug = $2 AND source_id = $3)`, [Number(dim), slug, sourceId]);
+}
+
+for (const backend of backends) {
+ test(`[${backend}] coverage excludes chunks retained on soft-deleted pages; live gaps, embed_skip and source scope still count right`, async () => {
+ const { engine, reset } = engines.find(e => e.name === backend)!;
+ await reset();
+ await seed(engine, 'notes/live-one', true);
+ await seed(engine, 'notes/live-two', true);
+ await seed(engine, 'notes/deleted-unembedded', false);
+ await engine.executeRaw(`UPDATE pages SET deleted_at = now() WHERE slug = 'notes/deleted-unembedded'`);
+ const retained = await engine.executeRaw<{ n: number }>(
+ `SELECT count(*)::int AS n FROM content_chunks WHERE page_id = (SELECT id FROM pages WHERE slug = 'notes/deleted-unembedded')`);
+ expect(retained[0]!.n).toBe(2);
+
+ let health = await engine.getHealth();
+ expect(health.missing_embeddings).toBe(0);
+ expect(health.embed_coverage).toBe(1);
+ expect(await engine.countStaleChunks()).toBe(0);
+ expect(await engine.listStaleChunks({ batchSize: 10 })).toEqual([]);
+
+ await seed(engine, 'notes/skipped-unembedded', false);
+ await engine.executeRaw(`UPDATE pages SET frontmatter = COALESCE(frontmatter, '{}'::jsonb) || '{"embed_skip": true}'::jsonb WHERE slug = 'notes/skipped-unembedded'`);
+ expect((await engine.getHealth()).embed_coverage).toBe(1);
+
+ await seed(engine, 'notes/live-gap', false, 'source-b');
+ health = await engine.getHealth();
+ expect(health.missing_embeddings).toBe(2);
+ expect(health.embed_coverage).toBeCloseTo(4 / 6, 5);
+ expect((await engine.getHealth({ sourceId: 'default' })).embed_coverage).toBe(1);
+ expect((await engine.getHealth({ sourceId: 'source-b' })).embed_coverage).toBe(0);
+ }, 60_000);
+}
diff --git a/test/helpers/legacy-get-health.ts b/test/helpers/legacy-get-health.ts
index 8ce9e181a0..2feb1df48c 100644
--- a/test/helpers/legacy-get-health.ts
+++ b/test/helpers/legacy-get-health.ts
@@ -46,7 +46,9 @@ export async function legacyGetHealth(
/ count(*) FILTER (WHERE NOT jsonb_exists(COALESCE(p.frontmatter, '{}'::jsonb), 'embed_skip'))::float
END
FROM content_chunks cc
- JOIN scoped_pages p ON p.id = cc.page_id) as embed_coverage,
+ JOIN scoped_pages p ON p.id = cc.page_id
+ -- #7212 (W3): the one intended divergence from v0.60.34.0; coverage counts live pages only, like missing_embeddings.
+ WHERE p.deleted_at IS NULL) as embed_coverage,
(SELECT count(*) FROM links l
WHERE NOT EXISTS (SELECT 1 FROM pages p WHERE p.id = l.to_page_id)
AND ($1::text[] IS NULL