Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
docs+test: ship run 3 coverage tests, release refusals in the error registry, docs audit corrections
garrytand18c5bf62b71
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 33904ca34f..9d1b45f88d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -22,8 +22,9 @@ identifiers and attribution are available in the pre-removal Git revision| The hold names an existing fence row (a fence-guard hold) | the release inserted a second, database-only twin next to the file's own row | the release indexes the existing row: one row, and the file is unchanged || The hold is decided after the release was accepted | — | the release fails `preview_changed` and writes nothing; running the release again asks for the confirmation and then refuses, because the hold was decided meanwhile || A release ends without committing (for example its page was deleted while it ran) | — | once the cause is fixed, running the release again admits a new attempt; a release that committed is replayed, never written twice |-| A release runs through a resident `gbrain serve` (PGLite) and the owner's write queue is slow | — | the CLI waits 90 seconds for the owner instead of 30, past the release's own 60-second wait, so a release slowed by the write queue ends with its pending write receipt rather than a lost acknowledgment; `gbrain trust review --accept-all` lists such a release as pending with its poll command (exit 10) instead of "not applied" |-| The owner confirms a release | — | the confirmation names the page the fact is written to (`<source>/<slug>`) |+| A release runs through a resident `gbrain serve` (PGLite) and the owner's write queue is slow | — | the CLI waits 90 seconds for the owner instead of 30, past the release's own 60-second wait, so a release slowed by the write queue ends with its pending write receipt rather than a lost acknowledgment; `gbrain trust review --accept-all` lists such a release as pending with its poll command (exit 10; `--accept-pending` exits 0; a failed item still exits 1) instead of "not applied" |+| The owner confirms a release | — | the confirmation names the fact's entity page (`<source>/<slug>`) |+| The claim was forgotten (`gbrain forget`) or purged (`gbrain forget --purge`) before the owner releases its hold | — | the release refuses `fact_withdrawn` (or `purged_content` for a purged claim) and the fact stays held; a forgotten or purged claim is never written back into the page's `## Facts` table, including when it is forgotten while the release runs || The entity page is deleted or private, or the request is remote | — | the release refuses (remote: `confirmation_required`) and the fact stays held |### What to watch for after you upgradediff --git a/docs/architecture/coordinated-writes.tsv b/docs/architecture/coordinated-writes.tsvindex f1f1dde1f9..0a38f89e28 100644--- a/docs/architecture/coordinated-writes.tsv+++ b/docs/architecture/coordinated-writes.tsv@@ -40,5 +40,5 @@ src/core/timeline-extract.ts retractCoordinated 1 projection Retracts timeline rsrc/core/trust/backfill.ts relowerClaimedRows 2 metadata Lowers trust tiers a claim lifted and propagates the lowering; trust tier is metadata beside the row, never content of record.src/core/trust/backfill.ts runTrustBackfill 1 metadata Backfills trust tiers computed from page rules; trust tier is metadata beside the row, never content of record.src/core/trust/held-removals.ts acceptHeldRemoval 1 projection An accepted held removal re-derives the take from its fence row or the timeline row from the page body; the rows follow the text.-src/core/trust/owner-actions.ts publishReleasedFact 1 facts_lane A released held fact is inserted database-only today; it moves to the entity's fence through the door on GBRA-190's shared fence-row writer (G5 lane C, stacked after G4).+src/core/trust/owner-actions.ts publishReleasedFact 1 facts_lane A released held fact with no entity slug, or whose entity page is missing, is inserted database-only (G4, GBRA-190, owns that class); every other managed fact release publishes its fence row through the door as a journaled trust_release request (trust/release-publish.ts).src/core/trust/page-handlers.ts setRowTier 1 metadata An owner trust decision sets trust_tier and its owner_decision note on a fact, take or page row; trust tier is metadata, page content changes go through trust_owner_page.diff --git a/docs/architecture/key-files/commands-4-continued.md b/docs/architecture/key-files/commands-4-continued.mdindex 7fce7bbdfa..5f8a3b5d6a 100644--- a/docs/architecture/key-files/commands-4-continued.md+++ b/docs/architecture/key-files/commands-4-continued.md@@ -12,7 +12,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/commands/publish.ts` — Deterministic brain page publisher (code+skill pair, zero LLM calls)-- `src/commands/trust.ts` — `gbrain trust review|confirm|release|drop|revert|explain|allow|disable` (#5575 DX-7; `backfill` is dispatched by `src/cli/commands/trust.ts`). `runOwnerAction` previews, asks for the typed token when the action raises trust, then applies bound to the preview; `review --accept-all` needs a filter and takes one confirmation (DX-15). The backend is the local engine, or `maybeDelegateTrust` (called from `src/cli.ts` before connecting) routes through a resident PGLite owner's administration socket with the prompt in the invoking CLI (DX-2). `confirmTierCrossingAccepts` puts tier-crossing `decide proposals accept` through the same rule; `quarantine release|drop` are aliases (`src/cli/commands/quarantine.ts`). Refusals render through `writeCliError` (exit 3 for consent refusals).+- `src/commands/trust.ts` — `gbrain trust review|confirm|release|drop|revert|explain|allow|disable` (#5575 DX-7; `backfill` is dispatched by `src/cli/commands/trust.ts`). `runOwnerAction` previews, asks for the typed token when the action raises trust, then applies bound to the preview; `review --accept-all` needs a filter and takes one confirmation (DX-15); an item whose write is still pending (a managed release that outlived the door's wait) is listed under `pending` with its poll command instead of `not applied`, and the run exits 1 when any item failed, else 10 when any is pending (0 with `--accept-pending`). The backend is the local engine, or `maybeDelegateTrust` (called from `src/cli.ts` before connecting) routes through a resident PGLite owner's administration socket with the prompt in the invoking CLI (DX-2); its `trust_apply` call waits `OWNER_APPLY_TIMEOUT_MS` (90 s: the release door's 60 s `DOOR_WAIT_MS` plus 30 s, `src/core/trust/release-publish.ts`). `confirmTierCrossingAccepts` puts tier-crossing `decide proposals accept` through the same rule; `quarantine release|drop` are aliases (`src/cli/commands/quarantine.ts`). Refusals render through `writeCliError` (exit 3 for consent refusals).- `src/commands/quarantine.ts` — `gbrain quarantine <list|clear|scan>` operator surface for the content-quality gate. `list [--json] [--include-flagged]` paginates `listPages` and reports quarantined (HIDDEN) pages, optionally also `content_flag` (FLAGGED, searchable) pages. `clear <slug> [--force] [--no-embed] [--json]` drops both markers and re-imports through the normal pipeline so the page re-chunks + re-embeds and becomes searchable; the gate re-runs on import so genuinely-junk pages re-quarantine (exit 1) unless `--force` sets `GBRAIN_NO_SANITY=1` for that one import. `scan [--limit N] [--apply] [--no-embed] [--json]` re-assesses already-ingested pages so junk predating the gate gets marked (unchanged content short-circuits normal sync, so it never re-assesses otherwise); dry-run uses the SAME effective `content_sanity` config thresholds `--apply` will use, idempotent (skips already-marked pages), `--apply` re-imports with `forceRechunk` to set markers + (for quarantine) drop chunks. Dispatched in `cli.ts`. Pinned by `test/quarantine-cli.test.ts`. #6259: `clear` reads one snapshot (page, tags, revision) and, on a managed brain, publishes through `submitPageMutation` with that `expected_revision` (a concurrent edit is a `revision_conflict`, a pending receipt is reported as pending); `--force` writes a `quarantine_override` (see `src/core/quarantine-override.ts`) instead of disabling the gate, never mutation `force`. `scan --apply` refuses `writer_coordinator_required` on a managed brain. `scan` does not re-check a segmented page (it would hold the whole body as one string): it lists it in `skipped` (`page_body_segmented`) and goes on. It is a router (`QUARANTINE_SUBCOMMANDS`, `printUsage`). Tests: `test/quarantine-override.serial.test.ts`, `test/quarantine-cli.test.ts`.- `src/commands/recall.ts` — the `gbrain recall` CLI (facts-first by default; local engine or thin-client). Its help (`RECALL_HELP`, printed before the engine via `SELF_HELP_WITHOUT_ENGINE`) names `--question` for natural-language questions. Cat 41 run 4: `keylessQuestionFallback` — on a brain whose fact recall is keyword-only (`factRecallIsKeywordOnly`, `src/core/facts/keyword-only.ts`: embedding opted out or no provider), a multi-word positional that matched no entity and no fact text (#4720's fallback) is ranked as a question through `runRecallVerb`, with a stderr note; brains with embeddings keep their output and get a `--question` hint (`test/recall-keyless-question-fallback.test.ts`). `--question <q>` (or `--question=<q>`) is the question, never an entity: it routes through the recall op like `--budget-policy` (thin clients call the remote recall, an answer without `facts_order` prints a not-ranked note; it refuses the watch, cursor, rollup and context renders), and the renderer shows the ranking, each `relevance` and `facts_degraded` (`test/recall-question-cli.test.ts`). A malformed `--limit` (not a positive safe integer, or missing) throws `invalid_params` from `parseFlags`, so the CLI exits 2 through `renderCliError`: the v1 envelope under `--json` with `why` and a `fix` that reruns the same argv with `--limit 50`, and the Error/Fix/Why lines otherwise (`test/recall-limit-envelope.test.ts`). `--since` parses with `parseSinceParam` (`src/core/facts/since-parse.ts`, the parser the recall op uses); an unreadable or missing `--since` value and a `--session`/`--session-id` with no ID throw `invalid_params` from `parseFlags` (the bad value echoed, the accepted grammar in `why`) instead of dropping the bound (#6944, `test/recall-bounds-envelope.test.ts`). `--since-last-run` on a local brain pages oldest-first through `listFactsKeyset` (`fetchCursorPage`; `recallNarrowing` in `engine-sql/facts.ts` gives it the entity, session, grep and audit-row filters `listFactsSince` uses). `advanceCursor` records a full `--limit` window with `writePagedCursor` (the newest delivered row's `(created_at, id)`; `readRecallCursor` in `src/core/recall-cursor-state.ts` trusts it only when it matches `last_run_iso`; still `schema_version: 1`), so the next run resumes after it; a caught-up run writes the wall-clock start. Thin-client and `--supersessions` keep the newest-N window and warn on stderr when it is full (#6945, `test/recall-since-last-run-overflow.test.ts`, thin warning in `test/recall-budget-policy-thin-cli.test.ts`). Optional `--budget-policy facts_first|query_first` routes a one-shot read through the shared operation, forwarding fact filters and using remote recall on thin clients. Enum validation uses the shared operation definition; option order does not affect budget parsing. Only query-first with a nonblank query preserves numeric fractions until server packing; omitted/explicit facts-first keeps legacy integer parsing. The new option rejects watch/cursor/rollup/as-context combinations rather than silently ignoring them. Opt-in selector failures use stamped v1 errors; JSON mode emits structured local and remote errors on stdout with a nonzero exit, preserving remote read-error details without requiring a mutation receipt. Omitted-policy validation and fallback remain unchanged. Entity→text fallback: a bare positional without verb options is entity-first, but when the entity arm matches ZERO facts (and no `--grep`/`--supersessions`/`--session-id` narrows the read), the query retries as SQL-level fact-text grep with a stderr note. One predicate and note formatter are shared by the local path and thin-client mirror; explicit grep callers keep exact semantics. `--since` composes with entity and session in one query before LIMIT, on event time unless `--since-last-run`. Local `--grep` is passed to every engine arm (ILIKE with escaped metacharacters, before LIMIT); only `--supersessions` keeps the client-side filter. Pinned by `test/recall-grep-local-cli.test.ts`. Pinned by `test/facts-recall-since-composition.test.ts`, `test/recall-budget-policy-transports.test.ts`, `test/recall-budget-policy-thin-cli.test.ts`, and `test/recall-budget-policy-thin.serial.test.ts`.diff --git a/docs/architecture/key-files/core-persistence-facts.md b/docs/architecture/key-files/core-persistence-facts.mdindex 65905c2306..c8840d95dd 100644--- a/docs/architecture/key-files/core-persistence-facts.md+++ b/docs/architecture/key-files/core-persistence-facts.md@@ -21,4 +21,4 @@ Managed facts extraction: the entity-intent preparer and publisher, conversation- `src/commands/doctor/checks/fact-bulk-dates.ts` — `fact_bulk_dates` (wave check, #7247): `findBulkFactDays` over the scoped sources (remote callers: their permitted sources); warns per day with fact and entity counts, top source tags and `dated_claims`, says the dates record loading, not occurrence, and names the `gbrain repair fact-claim-dates --source <id>` preview. Read-only.- `src/core/repair/fact-claim-dates.ts` — `gbrain repair fact-claim-dates --source <id> [--day YYYY-MM-DD]` (#7247), explicit-only, preview-bound, destructive (`--yes`). Candidates: active facts on a bulk day (`findBulkFactDays`, or `--day`) whose claim has exactly one earlier ISO date (`claimDate`). A fence row's `valid_from` cell is rewritten in the page's one fence section and published by revision-bound `put_page` (the facts row is re-projected); a database-only fact is updated in one `maintenanceTransaction` on an unmanaged brain and counted `database_only_managed` on a managed one. Pages with an unparsed, split or segmented fence, or a rewrite that does not read back as the planned rows, are listed and kept. The hash binds revisions, row numbers and new dates; a fresh apply recomputes the plan and refuses `preview_changed` on any difference. Test: `test/repair-fact-claim-dates-7247.test.ts`.-- `src/core/facts/fence-fact-append.ts` — `prepareFenceFactAppend(engine, row, config, snapshot, { fact, pendingTier, mode?, supersede? | rowNum }, signal)`: the one way a coordinator preparer puts a single fact into the facts fence of the request's page (`row.slug`); remember uses it, and an owner release of a held fact is its next caller. It returns `{ prepared, rowNum, fencesNormalized, apply(tx) }`: `prepared` is the page write to compose (its `file`, `exclusiveSources`, `validate`; null in index-existing), and `apply` runs in the publication transaction after the coordinator published the file, writing the page row (tier kept, `trust/fence-append.ts`) and then the facts row with `row_num` and `source_markdown_slug`, so a facts row never precedes its fence row in Git. `append` (default) normalizes the stored fence (#6188), renders the row with `fenceRowOf` (`unfenced-facts.ts`, the one renderer) at one past the highest row number in the fence and among the page's facts rows (#6696 C9), strikes `supersede.rowNum` when given, and prepares the page write `unprojected` (`preparePageMutation` option: the helper writes the facts row, so the page publishes without canonical projection whatever the operation) under `withPendingFenceRows` at `pendingTier`. `index-existing` takes a row the file already holds (a fence-guard hold's `payload.row_num`): the cell must pass `fenceCellReadBackProblem` against the fact, else it refuses `fence_row_changed` (reason `row_missing` / `struck` / `empty` / `visibility` / `text`) and writes nothing; otherwise the facts row derives from the cell (`extractFactsFromFenceText`, what a re-import projects) with the caller's embedding and session, and no file changes; the caller's observedRevision is `snapshot.revision`, which the coordinator re-checks under the page lock. An occupied row number fails the insert with `storage_error` naming the occupant. Tests: `test/fence-fact-append.test.ts` (PGLite and Postgres: append, supersede, index-existing from a real fence-guard hold, each refusal, and remember's fence row byte for byte against the earlier construction).+- `src/core/facts/fence-fact-append.ts` — `prepareFenceFactAppend(engine, row, config, snapshot, { fact, pendingTier, mode?, supersede? | rowNum }, signal)`: the one way a coordinator preparer puts a single fact into the facts fence of the request's page (`row.slug`); remember uses it, and so does a managed owner release of a held fact (`trust/release-publish.ts`, the `trust_release` operation: append for a held fact with an entity slug, index-existing for a hold naming `payload.row_num`). It returns `{ prepared, rowNum, fencesNormalized, apply(tx) }`: `prepared` is the page write to compose (its `file`, `exclusiveSources`, `validate`; null in index-existing), and `apply` runs in the publication transaction after the coordinator published the file, writing the page row (tier kept, `trust/fence-append.ts`) and then the facts row with `row_num` and `source_markdown_slug`, so a facts row never precedes its fence row in Git. `append` (default) normalizes the stored fence (#6188), renders the row with `fenceRowOf` (`unfenced-facts.ts`, the one renderer) at one past the highest row number in the fence and among the page's facts rows (#6696 C9), strikes `supersede.rowNum` when given, and prepares the page write `unprojected` (`preparePageMutation` option: the helper writes the facts row, so the page publishes without canonical projection whatever the operation) under `withPendingFenceRows` at `pendingTier`. `index-existing` takes a row the file already holds (a fence-guard hold's `payload.row_num`): the cell must pass `fenceCellReadBackProblem` against the fact, else it refuses `fence_row_changed` (reason `row_missing` / `struck` / `empty` / `visibility` / `text`) and writes nothing; otherwise the facts row derives from the cell (`extractFactsFromFenceText`, what a re-import projects) with the caller's embedding and session, and no file changes; the caller's observedRevision is `snapshot.revision`, which the coordinator re-checks under the page lock. An occupied row number fails the insert with `storage_error` naming the occupant. Tests: `test/fence-fact-append.test.ts` (PGLite and Postgres: append, supersede, index-existing from a real fence-guard hold, each refusal, and remember's fence row byte for byte against the earlier construction).diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.mdindex c54608a739..4cd06885c6 100644--- a/docs/guides/error-codes.md+++ b/docs/guides/error-codes.md@@ -15,7 +15,7 @@ Under contract v1 an `error` value never changes. Where a surface sends a legacy| `error` (frozen) | `code` (canonical) | Meaning ||---|---|---|-| `invalid_params` | `fact_withdrawn` | `remember` refused a claim that was explicitly forgotten for this subject (wire `invalid_params`, message prefix `fact_withdrawn:`); nothing was saved. |+| `invalid_params` | `fact_withdrawn` | `remember`, or an owner `gbrain trust release` of a held fact, refused a claim that was explicitly forgotten for this subject (wire `invalid_params`, message prefix `fact_withdrawn:`); nothing was saved, and a refused release leaves the fact held. || `permission_denied` | `insufficient_scope` | The connection lacks the OAuth scope the operation requires. || `invalid_params` | `invalid_fence` | A facts or takes fence in the page cannot be imported without dropping or guessing rows, so the page (or the file) was not written. || `invalid_params` | `link_cursor_invalid` | A get_links / get_backlinks cursor was not one this listing returned: it belongs to another slug, direction, source scope or filter set, or is not a cursor. |@@ -1371,7 +1371,7 @@ More: [docs/guides/repair.md#rename-identity](../../docs/guides/repair.md#rename| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable ||---|---|---|---|---|---|---|-| `remember` refused a claim that was explicitly forgotten for this subject (wire `invalid_params`, message prefix `fact_withdrawn:`); nothing was saved. | A forgotten claim stays withdrawn: remembering the same normalized text does not restore it, and a claim forgotten without an entity is withdrawn for every entity. The additive `withdrawn` object (`at`, `subject`: an entity slug or `all_entities`, `visibility`) says when and how widely the exact claim was forgotten; it covers that exact claim only, and its absence carries no meaning. | Do not retry the same text. Tell the user the claim was forgotten (withdrawn.at, withdrawn.subject); if it is still true, remember it in new words. To link a fact saved without an entity, remember it with entity and replaces set to its fact id instead of forgetting it. | agent | `repeat the read that failed` | 1 | no |+| `remember`, or an owner `gbrain trust release` of a held fact, refused a claim that was explicitly forgotten for this subject (wire `invalid_params`, message prefix `fact_withdrawn:`); nothing was saved, and a refused release leaves the fact held. | A forgotten claim stays withdrawn: remembering the same normalized text does not restore it, and a claim forgotten without an entity is withdrawn for every entity. The additive `withdrawn` object (`at`, `subject`: an entity slug or `all_entities`, `visibility`) says when and how widely the exact claim was forgotten; it covers that exact claim only, and its absence carries no meaning. | Do not retry the same text. Tell the user the claim was forgotten (withdrawn.at, withdrawn.subject); if it is still true, remember it in new words. To link a fact saved without an entity, remember it with entity and replaces set to its fact id instead of forgetting it. For a refused release, do not retry it: drop the hold (gbrain trust drop h<id>) unless the user wants the claim back in new words. | agent | `repeat the read that failed` | 1 | no |### facts_absorb_write_refused@@ -1451,9 +1451,9 @@ More: [docs/guides/retrieval-feedback.md#feedback_not_authorized](../../docs/gui| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable ||---|---|---|---|---|---|---|-| A fact was not indexed from the facts fence row its request names because that row no longer reads back as the fact (removed, struck, emptied, another visibility or other text); nothing was written. | A facts row derives from its fence row, which Git holds. Indexing a fact at a row that now says something else would make the database disagree with the file, so the write stops and the file stays as it is. | Read the page (gbrain get <slug>) to see the row as it stands; if the fact is still wanted, remember it again, which writes it as a new row. | agent | `repeat the read that failed` | 1 | no |+| A fact was not indexed from the facts fence row its request names because that row no longer reads back as the fact (removed, struck, emptied, another visibility or other text), or, for an owner release of a held row, because its context or source was edited after the hold (`held_row_edited`); nothing was written, and a refused release leaves the fact held. | A facts row derives from its fence row, which Git holds. Indexing a fact at a row that now says something else would make the database disagree with the file, so the write stops and the file stays as it is. | Read the page (gbrain get <slug>) to see the row as it stands; if the fact is still wanted, remember it again, which writes it as a new row. For a refused gbrain trust release, do not remember it: run gbrain trust review, where the edited row is held separately, and release or drop the holds there. | agent | `repeat the read that failed` | 1 | no |-Reasons: `row_missing`, `struck`, `empty`, `visibility`, `text`.+Reasons: `row_missing`, `struck`, `empty`, `visibility`, `text`, `held_row_edited`.### fence_unrenderablediff --git a/docs/guides/memory-trust.md b/docs/guides/memory-trust.mdindex ec59a15a52..35e985e318 100644--- a/docs/guides/memory-trust.md+++ b/docs/guides/memory-trust.md@@ -68,6 +68,10 @@ gbrain config set trust.agent_activation suppress # keep flagged agent-wriWith quarantine, an instruction-like external write is held: it is notsearchable and not injected until you release it (`gbrain trust release`).+On a managed brain, a released fact whose entity page exists is written as a+row of that page's `## Facts` table, so the page's file holds it; a fact with+no entity page, and any fact on an unmanaged brain, is saved to the database+only.With suppress, flagged items are still returned by explicit search, recalland `get_page`, labeled, but hook context, the context engine,`context_pack` and volunteer leave them out until you confirm them indiff --git a/src/core/error-registry.ts b/src/core/error-registry.tsindex abdc64909b..82186c3b07 100644--- a/src/core/error-registry.ts+++ b/src/core/error-registry.ts@@ -278,10 +278,10 @@ export const CODES = {export_limit: { class: 'caller', summary: "This migration is bounded to 5,000 active pages per source; split or use a reviewed bulk export." },extraction_failed: { class: 'server', summary: "The accepted atom extraction failed (malformed output, or a response stopped before the end); a new attempt needs approval.", why: "The drain retries a failed managed atom batch on its own up to 3 times per content (then holds it, code held_failed); this code reports a failed explicit retry, or a failure the drain cannot attribute to a checkpoint, so the same input is not paid for again without approval." },extractor_identity_mismatch: { class: 'server', summary: "The approved extractor differs from the installed extractor; this receipt cannot resume or admit another revision." },- fact_withdrawn: { class: 'caller', summary: "`remember` refused a claim that was explicitly forgotten for this subject (wire `invalid_params`, message prefix `fact_withdrawn:`); nothing was saved.", why: "A forgotten claim stays withdrawn: remembering the same normalized text does not restore it, and a claim forgotten without an entity is withdrawn for every entity. The additive `withdrawn` object (`at`, `subject`: an entity slug or `all_entities`, `visibility`) says when and how widely the exact claim was forgotten; it covers that exact claim only, and its absence carries no meaning.", legacy_error: 'invalid_params', suggestion: 'Do not retry the same text. Tell the user the claim was forgotten (withdrawn.at, withdrawn.subject); if it is still true, remember it in new words. To link a fact saved without an entity, remember it with entity and replaces set to its fact id instead of forgetting it.' },+ fact_withdrawn: { class: 'caller', summary: "`remember`, or an owner `gbrain trust release` of a held fact, refused a claim that was explicitly forgotten for this subject (wire `invalid_params`, message prefix `fact_withdrawn:`); nothing was saved, and a refused release leaves the fact held.", why: "A forgotten claim stays withdrawn: remembering the same normalized text does not restore it, and a claim forgotten without an entity is withdrawn for every entity. The additive `withdrawn` object (`at`, `subject`: an entity slug or `all_entities`, `visibility`) says when and how widely the exact claim was forgotten; it covers that exact claim only, and its absence carries no meaning.", legacy_error: 'invalid_params', suggestion: 'Do not retry the same text. Tell the user the claim was forgotten (withdrawn.at, withdrawn.subject); if it is still true, remember it in new words. To link a fact saved without an entity, remember it with entity and replaces set to its fact id instead of forgetting it. For a refused release, do not retry it: drop the hold (gbrain trust drop h<id>) unless the user wants the claim back in new words.' },fact_rows_collide: { class: 'caller', summary: "Carrying a page's identity across a rename would drop facts: a fence row of the old page has a different claim in the new file, or the new file does not hold it.", why: "gbrain repair rename-identity merges the two pages' facts only where both say the same thing at the same fence row; anything else would lose one side, so nothing is written.", suggestion: 'Give each old claim its own row in the new file\'s facts fence (or keep the same claim at its row), commit and sync, then preview again; or keep the old page with gbrain restore, or release the hold with --close.', docs: 'docs/guides/repair.md#rename-identity' },fact_already_expired: { class: 'caller', summary: "The fact had already expired before this write." },- fence_row_changed: { class: 'caller', reasons: ['row_missing', 'struck', 'empty', 'visibility', 'text'], summary: "A fact was not indexed from the facts fence row its request names because that row no longer reads back as the fact (removed, struck, emptied, another visibility or other text); nothing was written.", why: "A facts row derives from its fence row, which Git holds. Indexing a fact at a row that now says something else would make the database disagree with the file, so the write stops and the file stays as it is.", suggestion: 'Read the page (gbrain get <slug>) to see the row as it stands; if the fact is still wanted, remember it again, which writes it as a new row.' },+ fence_row_changed: { class: 'caller', reasons: ['row_missing', 'struck', 'empty', 'visibility', 'text', 'held_row_edited'], summary: "A fact was not indexed from the facts fence row its request names because that row no longer reads back as the fact (removed, struck, emptied, another visibility or other text), or, for an owner release of a held row, because its context or source was edited after the hold (`held_row_edited`); nothing was written, and a refused release leaves the fact held.", why: "A facts row derives from its fence row, which Git holds. Indexing a fact at a row that now says something else would make the database disagree with the file, so the write stops and the file stays as it is.", suggestion: 'Read the page (gbrain get <slug>) to see the row as it stands; if the fact is still wanted, remember it again, which writes it as a new row. For a refused gbrain trust release, do not remember it: run gbrain trust review, where the edited row is held separately, and release or drop the holds there.' },fence_unrenderable: { class: 'server', summary: "A legacy fact row was not adopted into its page's facts fence because the fence codec reads the rendered row back as something other than the stored fact.", why: "The fence trims a claim, folds CRLF to LF, reads `~~x~~` as a struck row and `<br>` as a line break; a claim the codec would change by more than whitespace cannot be written into the fence without changing what it says, so the row stays a legacy row (active and searchable, nothing is lost) and is counted by doctor fence_integrity as unrenderable_legacy_facts. The same code names a planned adoption whose rendered fence does not read back as its facts; that is a gbrain planning defect, not caller input.", docs: 'docs/guides/write-refusals.md#fence_unrenderable', suggestion: 'Nothing to fix in the page: the rows stay active and searchable. Report the page slug and the reason class with the gbrain version; do not forget or expire a row to clear this count.', fix: { argv: ['gbrain', 'doctor', '--only', 'fence_integrity', '--json'], consent: [], actor: 'agent', why: 'Lists the pages whose legacy fact rows cannot be adopted into their fence and why (by fact id and reason class, never the claim text), read-only.', requires_exclusive: false } },fact_not_found: { class: 'caller', summary: "Fact not found." },facts_absorb_write_refused: { class: 'caller', summary: "Facts absorb refused the write." },diff --git a/test/trust-owner-actions.test.ts b/test/trust-owner-actions.test.tsindex 9cae3087fb..dcc6d4cbd8 100644--- a/test/trust-owner-actions.test.ts+++ b/test/trust-owner-actions.test.ts@@ -17,7 +17,8 @@* Runs on PGLite, and on Postgres when DATABASE_URL is set.*/import { _resetCliExitVerdictForTests, currentExitCode } from '../src/core/cli-force-exit.ts';-import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';+import { afterAll, afterEach, beforeAll, describe, expect, spyOn, test } from 'bun:test';+import * as cliForceExit from '../src/core/cli-force-exit.ts';import { randomUUID } from 'node:crypto';import { mkdtempSync, readFileSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';import { PassThrough } from 'node:stream';@@ -514,6 +515,32 @@ describe('review, explain and accept-all (CEO-2, DX-10, DX-15, DX-16)', () => {expect(lines.find(l => l.startsWith('h7:'))).toContain(requestId);expect(lines.find(l => l.startsWith('h8:'))).toContain(c.h8 === 'fails' ? 'not applied' : 'released');}++ // Generated by gstack /ship Step 7 coverage audit (#7511 run 3).+ // Value: protects=accept-all --json lists a release still pending in the door under `pending` (ref, request_id, poll), not under accepted or failed, and exits 10;+ // fails_when=the JSON document drops `pending` (the pending item vanishes from the agent's view) or files it under failed; why_new=the cases above read the text lines only;+ // seam=none (the same stub TrustBackend; a test spy captures writeStdoutFinal's document); no_claim=a real door write outliving its wait (the pending OperationError is hand-built)+ const backend = {+ review: async () => ({ items: [{ kind: 'hold', ref: 'h7', source_id: 'default' }, { kind: 'hold', ref: 'h8', source_id: 'default' }] }),+ explain: async () => [],+ preview: async (input: OwnerActionInput) => ({ action: 'release', ref: input.ref, token: input.ref, command: `gbrain trust release ${input.ref}`, raises: true, binding: `b-${input.ref}`, summary: `Release held fact ${input.ref}` }),+ apply: async (input: OwnerActionInput) => {+ if (input.ref === 'h7') throw pending;+ return { action: 'release', ref: 'h8', status: 'released', tier: 'user_confirmed' };+ },+ } as unknown as Parameters<typeof runTrustOwnerCommand>[0];+ const docs: string[] = [];+ const exit = await withEnv({ GBRAIN_HOME: home }, async () => {+ typesToken();+ const final = spyOn(cliForceExit, 'writeStdoutFinal').mockImplementation(async (doc: string) => { docs.push(doc); });+ try { await runTrustOwnerCommand(backend, 'review', ['--accept-all', '--from', 'default', '--json']); return currentExitCode(); }+ finally { final.mockRestore(); process.exitCode = 0; _resetCliExitVerdictForTests(); }+ });+ expect(docs).toHaveLength(1);+ const doc = JSON.parse(docs[0]!);+ expect({ exit, accepted: doc.accepted.map((a: { ref: string }) => a.ref), pending: doc.pending.map((p: { ref: string; request_id: string }) => [p.ref, p.request_id]), failed: doc.failed })+ .toEqual({ exit: 10, accepted: ['h8'], pending: [['h7', requestId]], failed: [] });+ expect(doc.pending[0].poll).toContain(requestId);}, 60_000);test('the review listing is pinned (DX-16) and explain names tier, origin, receipts and activation', async () => withEnv({ GBRAIN_HOME: home }, async () => {diff --git a/test/trust-release-fence.test.ts b/test/trust-release-fence.test.tsindex 668009269d..0add29537e 100644--- a/test/trust-release-fence.test.ts+++ b/test/trust-release-fence.test.ts@@ -354,6 +354,11 @@ for (const backend of testBackends()) {try { await operationsByName.remember.handler(ctx, { fact: CLAIM, provenance: 'email', content_origin: 'tool_output', request_id: randomUUID() }); }catch (e) { ref = JSON.parse((e as { detail: string }).detail).hold_ref; }expect(ref).toMatch(/^h\d+$/);+ // Generated by gstack /ship Step 7 coverage audit (#7511 run 3).+ // Value: protects=the release preview of a hold with no entity names no page (no "for <source>/..." clause);+ // fails_when=previewHold's entity guard is dropped and the summary reads "for default/undefined"; why_new=only the entity case was asserted;+ // seam=none; no_claim=the wording of the rest of the summary+ expect((await previewOwnerAction(engine, { action: 'release', ref })).summary).not.toContain(' for default/');expect(await release(engine, ref)).toMatchObject({ status: 'released', tier: 'user_confirmed' });expect(await holdStatus(engine, ref)).toBe('released');expect(await factRows(engine)).toEqual([expect.objectContaining({ trust_tier: 'user_confirmed', entity_slug: null, row_num: null, source_markdown_slug: null })]);