Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix: pre-landing review fixes
garrytanf6c8caf9d129
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 716b60b28d..61254cb417 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -12,15 +12,15 @@ identifiers and attribution are available in the pre-removal Git revision## [Unreleased]-**A take no longer disappears when gbrain re-creates a takes section that a page rewrite dropped.** When a page was rewritten without its takes section, its takes stayed stored, but the next `think --take --anchor <slug>` or `gbrain takes extract --from-pages` on that page built a fresh section numbered from 1: the new take replaced stored take #1 in place, with no record of the old one, and on a managed brain `takes extract --from-pages --include-covered` replaced the first stored takes and deleted the rest in the same write. These writers now render the stored takes, resolutions included, into the section they create and number their own takes after them, on repo-less, Git-backed and plain-directory brains. A take the user removed, or an explicit empty section retired, stays removed. A stored take whose resolution has no quality (recorded before takes had one) cannot be written into the section, so the write is refused (`invalid_input`) instead of clearing it. `takes extract --from-pages` skips a page whose takes markers are malformed (for example `<!-- gbrain:takes:begin -->` with two dashes) as `fence_unparsed` and goes on to the next page.+**A take no longer disappears when `think --take` or `gbrain takes extract --from-pages` re-creates a takes section that a page rewrite dropped.** When a page was rewritten without its takes section, its takes stayed stored, but the next `think --take --anchor <slug>` or `gbrain takes extract --from-pages` on that page built a fresh section numbered from 1: the new take replaced stored take #1 in place, with no record of the old one, and on a managed brain `takes extract --from-pages --include-covered` replaced the first stored takes and deleted the rest in the same write. These writers now render the stored takes, resolutions included, into the section they create and number their own takes after them, on repo-less, Git-backed and plain-directory brains. A take the user removed, or an explicit empty section retired, stays removed. A stored take whose resolution has no quality (recorded before takes had one), or whose text would not read back unchanged from the section (for example evidence holding the literal text `<br>`, which the section reads as a line break), cannot be written into the section, so the write is refused (`invalid_input`) instead of changing it. `takes_add` (`gbrain takes add` and the MCP tool) does not go through this yet. `takes extract --from-pages` skips a page whose takes markers are malformed (for example `<!-- gbrain:takes:begin -->` with two dashes) as `fence_unparsed` and goes on to the next page.### Itemized changes-- `src/core/takes-write.ts`: `withStoredTakesFence` renders a page's stored takes (resolution cells included) into a new takes section when the body has no takes fence, refusing `fence_unparsed` when the body holds malformed takes markers, `invalid_input` when a stored resolution has no quality, and `invalid_input` when the render would not read back row for row. Used by `addTakeToPage` (`think --take`) and `appendTakesToPageMdFirst` (unmanaged `takes extract --from-pages`).+- `src/core/takes-write.ts`: `withStoredTakesFence` renders a page's stored takes (resolution cells included) into a new takes section when the body has no takes fence, refusing `fence_unparsed` when the body holds malformed takes markers, `invalid_input` when a stored resolution has no quality, and `invalid_input` when the render would not read back row for row with every stored cell unchanged. Used by `addTakeToPage` (`think --take`) and `appendTakesToPageMdFirst` (unmanaged `takes extract --from-pages`).- `src/core/extract-takes-from-pages.ts`: the managed `takes extract --from-pages` put composes from the same rendered section and dedupes new claims against those takes; a page the helper refuses is skipped with the refusal's code instead of ending the run.- `src/core/behavior-change-notice.ts`: one row for the changed behavior.- Docs: `docs/architecture/key-files/hindsight.md`.-- Tests: `test/recreated-takes-section-keeps-stored-takes.test.ts` (`think --take` and `takes extract` on unmanaged brains, a plain directory and Git; managed extraction, repo-less and Git; removed takes, `takes remove` and empty sections stay removed; malformed markers skip one page; a resolution without a quality refuses; PGLite and Postgres).+- Tests: `test/recreated-takes-section-keeps-stored-takes.test.ts` (`think --take` and `takes extract` on unmanaged brains, a plain directory and Git; managed extraction, repo-less and Git; removed takes, `takes remove` and empty sections stay removed; malformed markers skip one page; a resolution without a quality, or a cell that would not read back unchanged, refuses; PGLite and Postgres).## [0.60.627.0] - 2026-11-09diff --git a/docs/architecture/key-files/hindsight.md b/docs/architecture/key-files/hindsight.mdindex 3a237363cd..460f65a3da 100644--- a/docs/architecture/key-files/hindsight.md+++ b/docs/architecture/key-files/hindsight.md@@ -35,7 +35,7 @@ unresolvable+true|false, pre-v80 NULL/NULL rows survive).- `src/commands/calibration.ts` — CLI: `gbrain calibration` (read + print), `--regenerate`, `--undo-wave <ver>`, `ab-report`. MCP op `get_calibration_profile` (scope: read) backs the same data path. Source-scoped via `sourceScopeOpts(ctx)`.- `src/core/owner-holder.ts` — single source of truth for "the brain owner" holder string. `DEFAULT_OWNER_HOLDER = 'self'` (matches the consolidate facts→takes writer + `docs/takes-vs-facts.md`); `resolveOwnerHolder({override, configValue})` returns override > `emotional_weight.user_holder` config > `'self'`. Consumed by the calibration_profile cycle phase, `gbrain calibration` CLI, the `get_calibration_profile` op, `think`'s calibration block, `emotional-weight`'s `DEFAULT_USER_HOLDER`, and doctor's `calibration_freshness`. Pure; unit-tested in `test/owner-holder.test.ts`. Does NOT unify owner-identity fragmentation (`self`/`brain`/`people-<owner>`) — tracked separately.- `src/commands/takes.ts` — the full `gbrain takes` subcommand dispatcher (list/search/embed/add/update/supersede/resolve/propose/scorecard/calibration/extract/revisit). `takes list --limit N --offset N` validates integers at the CLI; the engine clamps limit (default 100, cap 500) and floors offset at 0. `takes revisit <slug>` opens $EDITOR on the source page with a `<!-- gbrain:revisit -->` cursor marker. #5167: `takes remove <slug> --row N` goes through `takes-mutation.ts` to the local-only `takes_remove` op (persistence `takes-prepare.ts`): the row leaves the takes table and its fence row becomes a reservation row (`| N | ~~(removed)~~ | take | world | 0.0 | | removed |`, W9F item 4) in one coordinated publication, other row numbers stay, and a resolved row, a row another row cites as "superseded by" it, or a row whose DB claim disagrees with the fence is refused (the last names `takes rebuild`); thin clients are refused. Reservations: `parseTakesFence` returns them in `reservedRowNums`, never in `takes`, so no reader or projection sees a take there; `renderTakesFence(takes, reservedRowNums)` puts them back in row order, and `upsertTakeRow`, `supersedeRow` and `takesPreparation.replaceFence` keep the reservations of the body they rewrite. Every new take row number comes from GBRA-54's `nextFreeRowNum` (`fence-repair/normalize.ts`): one more than every fence row on the page (facts and takes, live, struck and reserved) and, in `takes-prepare.ts`, every stored facts/takes row (`storedFenceRows`), revalidated under the publication lock; the promise holds while the reservation row exists. #6450: `takes_add` and an explicit `takes_supersede` holder override are trimmed and checked with `isValidHolder` at the write boundary (syntax before authority: `invalid_params` naming the grammar, before `assertHolderAllowed`); the inherited supersede holder is not re-validated (the existing fence already round-tripped). Every prepared takes fence is parsed again before publication and refused `invalid_params` on any warning, so no write can leave a fence the next write would refuse. Test: `test/takes-holder-validation-6450.test.ts`. `test/takes-row-reservation.test.ts` (both engines), `test/takes-reservation-callers.test.ts` (census of `parseTakesFence` callers). `takes rebuild <slug> [--source-id]` runs the local-only `takes_rebuild` op (W9F item 8; `runTakesRebuild` in `takes-mutation.ts`, delegated to a resident `gbrain serve` owner over persistence IPC, else the local engine, with the same JSON, warnings and exit 1 on a missing page or a warning), which calls `extractTakes({source:"db", slugs:[slug], sourceId, rebuild:true})`, whose rebuild now deletes only indexed rows whose (row_num, claim) left the fence, so matching rows keep resolutions and vectors. The v0_28_0 hint names `gbrain reindex --markdown` instead of the nonexistent `extract takes --rebuild`. GBRA-130 A-25: `takes propose --failed [--source <id>] [--json]` lists pages propose_takes held with a failure tombstone (`listFailedProposals`); `takes propose --retry-failed [--slug <slug>] [--source <id>] [--json]` deletes their tombstones and ledger records (`retryFailedProposals`) so the next run re-extracts them.-- `src/core/extract-takes-from-pages.ts` — bootstrap extraction selects uncovered pages newest first. Managed pages capture their revision before classification and publish the complete appended takes fence through coordinated `put_page`, whose canonical projection commits the takes rows with the page; conflicts skip that page. Unmanaged pages take the same database path when the database is their copy of record (`sync.write_through` off, or the page in a declared `storage.db_only` directory; an unbound Postgres source skips that page `owner_unavailable`), and so does a file-backed page of a source with a canonical owner (bound before the run, or bound by the run's own first `put_page`, as PGLite does), so a mixed batch never reaches the fenced md-first writer; other unmanaged pages retain the md-first writer. When the page has no takes section but still has stored takes (a rewrite dropped the section), `withStoredTakesFence` (`src/core/takes-write.ts`, also used by `think --take`) renders them, resolutions included, into the section first, so new claims are deduped against them and number after them; a page it refuses (`fence_unparsed` for malformed takes markers in the file, `invalid_input` for a stored resolution without a quality) is skipped with that reason and the run goes on. Pinned by `test/recreated-takes-section-keeps-stored-takes.test.ts`. A file-backed page whose file is missing is skipped as `mirror_unavailable` before the classifier runs. Pinned by `test/persistence-managed-takes-extract.test.ts`, `test/extract-takes-md-first.test.ts` and `test/pathological/d19-takes-bootstrap-db-only.test.ts`. `takes extract --before <updated_at>,<id>` (CLI-only) continues strictly below a prior run's `next_before`, an `(updated_at, id)` keyset with exact timestamptz text, so zero-claim pages no longer starve older ones; a budget stop resumes at the first unclassified page, a failed page stays uncovered for the next run without `--before`, and a malformed cursor is an exit-2 `invalid_params` refusal before any page is read. Pinned by `test/extract-takes-from-pages-progression.test.ts`, `test/takes-extract-json.test.ts` and `test/e2e/takes-extract-cursor-postgres.test.ts`.+- `src/core/extract-takes-from-pages.ts` — bootstrap extraction selects uncovered pages newest first. Managed pages capture their revision before classification and publish the complete appended takes fence through coordinated `put_page`, whose canonical projection commits the takes rows with the page; conflicts skip that page. Unmanaged pages take the same database path when the database is their copy of record (`sync.write_through` off, or the page in a declared `storage.db_only` directory; an unbound Postgres source skips that page `owner_unavailable`), and so does a file-backed page of a source with a canonical owner (bound before the run, or bound by the run's own first `put_page`, as PGLite does), so a mixed batch never reaches the fenced md-first writer; other unmanaged pages retain the md-first writer. When the page has no takes section but still has stored takes (a rewrite dropped the section), `withStoredTakesFence` (`src/core/takes-write.ts`, also used by `think --take`) renders them, resolutions included, into the section first, so new claims are deduped against them and number after them; a page it refuses (`fence_unparsed` for malformed takes markers in the file, `invalid_input` for a stored resolution without a quality or a stored cell that would not read back unchanged) is skipped with that reason and the run goes on. Pinned by `test/recreated-takes-section-keeps-stored-takes.test.ts`. A file-backed page whose file is missing is skipped as `mirror_unavailable` before the classifier runs. Pinned by `test/persistence-managed-takes-extract.test.ts`, `test/extract-takes-md-first.test.ts` and `test/pathological/d19-takes-bootstrap-db-only.test.ts`. `takes extract --before <updated_at>,<id>` (CLI-only) continues strictly below a prior run's `next_before`, an `(updated_at, id)` keyset with exact timestamptz text, so zero-claim pages no longer starve older ones; a budget stop resumes at the first unclassified page, a failed page stays uncovered for the next run without `--before`, and a malformed cursor is an exit-2 `invalid_params` refusal before any page is read. Pinned by `test/extract-takes-from-pages-progression.test.ts`, `test/takes-extract-json.test.ts` and `test/e2e/takes-extract-cursor-postgres.test.ts`.- `src/core/take-proposals.ts` — owns the `take_proposals` queue's row contract. `normalizeTakeProposalRow` coerces Postgres driver BigInt/string values (`id`, `weight`, `promoted_row_num`) to numbers at the query boundary so both engines return the same numeric row shape. `acceptProposal` promotes through a coordinated `takes_add` mutation (`submitPageMutation`, the same path `gbrain takes add` uses), so accept works on a managed brain where a direct fence write is refused with `writer_coordinator_required` (`test/takes-propose-accept-managed.test.ts`). #5214: an accepted proposal's take records `take_proposals#<id>` as its source; `acceptProposal(target, id, edits)` (`takes propose --accept <id> --claim/--weight/--who/--kind`) applies the edits as a plain takes_add with source `take_proposals#<id> (edited)` while the queue row keeps the original claim text.- `admin/src/pages/Calibration.tsx` — Calibration tab. Single-column layout. `<TrustedSVG>` wrapper handles `dangerouslySetInnerHTML` for the server-rendered SVG.- `admin/src/index.css` — `--text-muted: #777` (WCAG AA contrast bump to ~5.5 on the #0a0a0f bg).diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex 7e52ac4a27..a6309eab6a 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1495,7 +1495,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;{ since: '0.60.623.0', id: 'owner_reads_private_gst2059', text: 'A brain can now name its owner: `gbrain access owner set <member>` (config `access.owner_member`, an enabled member). Every remote credential or stdio server bound to that member reads the whole brain, `visibility: private` pages, privacy-alias pages (`access: private`, ...), derived and pinned-question pages included, through `get_page`, `search`, `query`, `recall` and the other page reads in the sources its grant reads, and `recall` returns its private facts. `readable_by` and folder rules still bind it, and it is not relaxed when it speaks for a shared-room audience. A page the owner\'s credential creates in `default` through `put_page` is not kept to the owner (no `readable_by: [member:<id>]`). Other members, unbound and public callers are unchanged. `_meta.access.relaxation` reads `owner` for such a call, and `gbrain access check --token <name>` reports it. `gbrain repair private-labels` (named runs only) previews the `access: private` labels stamped on ordinary pages with counts per category, keeps real restrictions, and clears the rest in reviewed batches (`--apply --expect <hash>`), recording each change so `--class restore` can put it back. The bulk-ingestion page template no longer writes an `access:` line; what each designation means is in docs/guides/access-designations.md.' },{ since: '0.60.626.0', id: 'record_origin_checkout_lockdown_8888', text: '`gbrain sources record-origin <id>... --remote --apply` now also turns git-lfs downloads and hooks off in each recorded source\'s existing checkout (its `.git/config`: `lfs.fetchexclude=*`, `core.hooksPath=/dev/null`, `lfs.locksverify=false`), not only on later reclones, in the repository\'s shared config, and refuses `write_failed` naming the key when a worktree-scoped or included setting still overrides one; a source already recorded as remote gets the lock-down on the next `--remote --apply` when its checkout lacks it, even when its files now use git-lfs, and a key that holds several values in that config is replaced by the one clone-time value. On a managed brain it takes the same worktree locks a reclone takes, refusing the id `source_busy` while a reclone, refresh or write holds them, and a reclone reads the record under its own locks. A write that fails is reported for its own id (`write_failed`) instead of ending the run. The git-lfs check reads a committed `.gitattributes` under a directory whose name holds a tab, ignores commented-out `filter=lfs` lines, says when a committed rule only declares an LFS filter, records a clone of an empty repository instead of refusing it, and names the cause of an `lfs_unknown` refusal.' },{ since: '0.60.627.0', id: 'ingest_keeps_readers_gst2112', text: 'A webhook capture (`POST /ingest` with `X-Gbrain-Slug` and its `ingest_capture` job) is now refused `readable_by_invalid` when its body drops `readable_by` from a page that names readers, or names readers that leave out the sending token or client: the route answers 403 and queues nothing, and a job already queued refuses at write time. Before, such a capture replaced the page and its readers, and every caller could read it. Bodies that keep the readers, and pages without readers, import as before.' },- { since: 'TBD', id: 'recreated_takes_section_keeps_stored_takes_gst2228', text: 'A takes section that gbrain re-creates on a page whose section a rewrite dropped now starts with the takes still stored for that page. `think --take --anchor <slug>` and `gbrain takes extract --from-pages` (also with `--include-covered` on a managed brain) render the stored takes, resolutions included, into the section they create and number their own takes after them, instead of numbering from 1 over a stored take. A take the user removed, or an explicit empty section retired, stays removed. A page whose stored take has a resolution without a quality, which the section cannot carry, is refused (`invalid_input`) instead of losing it, and `takes extract --from-pages` skips a page whose takes markers are malformed (`fence_unparsed`) and goes on to the next page.' },+ { since: 'TBD', id: 'recreated_takes_section_keeps_stored_takes_gst2228', text: 'A takes section that gbrain re-creates on a page whose section a rewrite dropped now starts with the takes still stored for that page. `think --take --anchor <slug>` and `gbrain takes extract --from-pages` (also with `--include-covered` on a managed brain) render the stored takes, resolutions included, into the section they create and number their own takes after them, instead of numbering from 1 over a stored take. A take the user removed, or an explicit empty section retired, stays removed. A page whose stored take has a resolution without a quality, or a cell that would not read back unchanged from the section (such as the literal text `<br>`), is refused (`invalid_input`) instead of changing it, and `takes extract --from-pages` skips a page whose takes markers are malformed (`fence_unparsed`) and goes on to the next page.' },];/** The newest disclosed change's release: the notice id moves only when a release adds rows. */diff --git a/src/core/takes-write.ts b/src/core/takes-write.tsindex d1dbd6f241..b095533bca 100644--- a/src/core/takes-write.ts+++ b/src/core/takes-write.ts@@ -533,7 +533,8 @@ async function storedTakeRows(engine: BrainEngine, pageId: number): Promise<Pars* the managed `takes extract --from-pages` put) go through this, so their own rows number after the stored ones:* otherwise they number from 1, overwrite stored takes in place, and the next projection deletes the rest. A body with* a near-miss marker (`<!-- gbrain:takes:begin -->`) refuses `fence_unparsed`, as each writer refuses it without- * stored takes, and a render that would not read back row for row refuses (`invalid_input`) instead of dropping a take.+ * stored takes, and a render that would not read back row for row, every stored cell unchanged, refuses (`invalid_input`)+ * instead of dropping or changing a take.*/export async function withStoredTakesFence(engine: BrainEngine, pageId: number, body: string): Promise<string> {const { beginIdx, endIdx } = locateOutsideCode(body, TAKES_FENCE_BEGIN, TAKES_FENCE_END);@@ -550,6 +551,13 @@ export async function withStoredTakesFence(engine: BrainEngine, pageId: number,const reparsed = parseTakesFence(next);assertFenceRoundTrips(reparsed);if (reparsed.takes.length !== rows.length) throw new TakesWriteError('invalid_input', 'The takes fence lost rows while carrying the stored takes of the page.');+ const cell = (value: unknown) => (value === '' || value === null ? undefined : value);+ const fields = ['claim', 'kind', 'holder', 'sinceDate', 'untilDate', 'source', 'active', 'resolvedQuality', 'resolvedEvidence', 'resolvedValue', 'resolvedUnit', 'resolvedBy'] as const;+ const changed = rows.find(row => {+ const back = reparsed.takes.find(take => take.rowNum === row.rowNum);+ return !back || fields.some(field => cell(back[field]) !== cell(row[field]));+ });+ if (changed) throw new TakesWriteError('invalid_input', `Take row #${changed.rowNum} would not read back unchanged from the takes fence, so re-creating the section would change it.`);return next;}diff --git a/test/recreated-takes-section-keeps-stored-takes.test.ts b/test/recreated-takes-section-keeps-stored-takes.test.tsindex 004b365957..110ae48972 100644--- a/test/recreated-takes-section-keeps-stored-takes.test.ts+++ b/test/recreated-takes-section-keeps-stored-takes.test.ts@@ -76,6 +76,15 @@ const qualitylessResolution = async (engine: BrainEngine, managed = false) => {const write = (tx: BrainEngine) => tx.executeRaw("UPDATE takes SET resolved_at=now(), resolved_outcome=true, resolved_quality=NULL, resolved_by='system' WHERE page_id=$1 AND row_num=1", [id]);await (managed ? withManagedFixtureWrite(engine, ['default'], write) : write(engine));};+/** Evidence holding the literal text `<br>`, which a takes section cell reads back as a line break. */+const LOSSY_EVIDENCE = 'Evidence says use <br> tags';+const lossyResolution = async (engine: BrainEngine, managed = false) => {+ const id = await pageId(engine);+ const write = (tx: BrainEngine) => tx.executeRaw("UPDATE takes SET resolved_at=now(), resolved_outcome=true, resolved_quality='correct', resolved_source=$2, resolved_by='system' WHERE page_id=$1 AND row_num=1", [id, LOSSY_EVIDENCE]);+ await (managed ? withManagedFixtureWrite(engine, ['default'], write) : write(engine));+};+const storedEvidence = (engine: BrainEngine) => engine.executeRaw<{ row_num: number; resolved_source: string | null }>(+ "SELECT t.row_num, t.resolved_source FROM takes t JOIN pages p ON p.id=t.page_id WHERE p.source_id='default' AND p.slug=$1 ORDER BY t.row_num", [SLUG]);type Storage = 'directory' | 'git' | 'repo-less';const gitRepo = (root: string) => { writeFileSync(join(root, '.gitignore'), '\n'); durableGitRepo(root, ['.gitignore']); };@@ -191,6 +200,19 @@ for (const backend of testBackends()) {expect(await storedResolution(engine)).toEqual(stored);expect(readFileSync(path, 'utf8')).toBe(rewritten);}), 180_000);++ test('think --take refuses, and keeps the stored take, when a stored cell would not read back unchanged', () => unmanagedBrain(databaseUrl, storage, async ({ engine, path, sync }) => {+ await sync(PAGE(FENCE(ROW_A)));+ await lossyResolution(engine);+ const rewritten = PAGE('Rewritten without the takes section.\n');+ await sync(rewritten);+ expect(await storedEvidence(engine)).toEqual([{ row_num: 1, resolved_source: LOSSY_EVIDENCE }]);+ const result = await persistTakeFromSynthesis(engine, { answer: THINK_CLAIM, synthesisOk: true } as never, { anchor: SLUG, sourceId: 'default' });+ expect(result.take_row).toBeNull();+ expect(result.warnings).toEqual([expect.stringContaining('TAKE_WRITE_FAILED: invalid_input')]);+ expect(await storedEvidence(engine)).toEqual([{ row_num: 1, resolved_source: LOSSY_EVIDENCE }]);+ expect(readFileSync(path, 'utf8')).toBe(rewritten);+ }), 180_000);});}@@ -253,6 +275,17 @@ for (const backend of testBackends()) {await op(ctx, 'add_tag', { slug: SLUG, tag: 'example' });expect(await storedResolution(engine)).toEqual(stored);}, opts), 180_000);++ test('a stored cell that would not read back unchanged skips the page instead of being rewritten', () => managedBrain(async ({ engine, ctx }) => {+ await put(ctx, PAGE('First version.\n'));+ await op(ctx, 'takes_add', { slug: SLUG, claim: TAKE_A, kind: 'bet', holder: 'world' });+ await lossyResolution(engine, true);+ await put(ctx, PAGE('Rewritten without the takes section.\n'));+ expect(await storedEvidence(engine)).toEqual([{ row_num: 1, resolved_source: LOSSY_EVIDENCE }]);+ expect(await extractFromPages(engine)).toMatchObject({ claims_extracted: 0, pages_skipped: 1, skipped: [{ slug: SLUG, reason: 'invalid_input' }] });+ await op(ctx, 'add_tag', { slug: SLUG, tag: 'example' });+ expect(await storedEvidence(engine)).toEqual([{ row_num: 1, resolved_source: LOSSY_EVIDENCE }]);+ }, opts), 180_000);});}}