Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
docs(#7630): leak guard and --clear docs match the code; non-retry sync-fault grouping test
garrytanbf0b079abcf2
diff --git a/docs/architecture/canonical-writers.tsv b/docs/architecture/canonical-writers.tsvindex 4644cbbbd9..4d0b9c608f 100644--- a/docs/architecture/canonical-writers.tsv+++ b/docs/architecture/canonical-writers.tsv@@ -228,7 +228,7 @@ src/core/schema-migrations/v144-open-loops.ts 1 schema Schema installation and fsrc/core/schema-migrations/v189-pages-credential-projection-pending.ts 1 schema Projection-only: unseals live pages whose canonical body holds a private-key marker and queues their keyless rebuild; canonical page columns are unchanged.src/core/schema-migrations/v191-alias-source-cascade.ts 2 schema Orphan alias GC before the alias→sources FK (#5094); grants exactly the orphan rows' sources through gbrain.write_sources for its transaction.src/core/schema-migrations/v224-page-retrievals.ts 1 schema Creates page_retrievals and copies pages.last_retrieved_at (retrieval telemetry, a projection column) into it; canonical page columns are unchanged.-src/core/persistence/connector-path.ts 1 coordinator Connector path clear locks the source row, refuses filesystem sources and bound connectors, and runs as a coordinated write on managed brains.+src/core/persistence/connector-path.ts 1 coordinator Connector path clear locks the source row, refuses filesystem sources with an absolute path and bound sources (a relative path on any source clears), and runs as a coordinated write on managed brains.src/core/source-delete.ts 1 engine_guard Unmanaged source delete with its incarnation binding; managed brains route removal through source lifecycle first and the writer guard refuses a direct delete.src/core/repair/extractor-facts.ts 1 coordinator `gbrain repair extractor-facts` (#5731) clears expired_at on preview-approved conversation-extractor facts and gives each a fresh row number. On a managed brain the UPDATE runs only inside the managed_maintenance_restore_extractor_facts publication (withCoordinatedWrite, page key locked, each fact reclassified first); an unmanaged brain runs the same function in one transaction under the page lock.src/core/repair/captured-facts.ts 1 coordinator `gbrain repair captured-facts` expires preview-approved capture-lane facts that have no fence row. On a managed brain the UPDATE runs only inside the managed_maintenance_expire_captured_facts publication (owner-checked by maintenancePreflight, page key locked); an unmanaged brain runs it in one transaction. Fenced rows are never updated here: they are struck in the page and expired by the canonical projection of a revision-bound put_page.diff --git a/docs/architecture/coordinated-writes.tsv b/docs/architecture/coordinated-writes.tsvindex 0a38f89e28..0787a18a60 100644--- a/docs/architecture/coordinated-writes.tsv+++ b/docs/architecture/coordinated-writes.tsv@@ -15,7 +15,7 @@ src/core/mentions/pass.ts aliasWrite 1 projection Mention-pass alias and mentionsrc/core/ops/chronicle.ts handler 1 facts_lane ontology_propose observations are database-only until G4 (GBRA-190) gives ontology observations a page home.src/core/page-body/ingest.ts segmentWriteScope 1 projection Segment texts, manifest rows and sweeps are the stored form of a page body the door already published; they are rebuilt from that body.src/core/page-state/materialize.ts materializePageSnapshot 1 facts_lane Materializes the withdrawal overlay into the stored body; G4 (GBRA-190) turns forget into fence edits and retires the withdrawal mirror.-src/core/persistence/connector-path.ts clearConnectorLocalPath 1 operational Clears a connector source's stale local_path pointer on the sources row; source configuration, not memory content.+src/core/persistence/connector-path.ts clearConnectorLocalPath 1 operational Clears a connector source's stale local_path pointer, or any source's relative one, on the sources row; source configuration, not memory content.src/core/persistence/connector-sync.ts stampFreshness 1 operational Stamps last_sync_at/newest_content_at freshness on the sources row for a skipped checkpoint save; sync bookkeeping, not memory content.src/core/persistence/coordinator.ts publishMutation 2 door The page-mutation door itself: the prepared publication and its after-effects commit here after the file is in place.src/core/persistence/group-publish.ts publishGroup 1 door Group publication of door requests: the same prepared publications as publishMutation, committed as one group.diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.mdindex 8095c94cb3..eb41dce801 100644--- a/docs/guides/troubleshooting.md+++ b/docs/guides/troubleshooting.md@@ -137,7 +137,7 @@ Turning the `preparation_deadlines` switch off (`gbrain config set persistence.p**`gbrain doctor` warns `default_source_local_path`?** Your `default` source has no `local_path` AND that null pointer is provably breaking write-through (the repo fallback is another source's own working tree, or file-backed default pages have no resolvable root). A null `local_path` on its own is the designed fallback topology and reports ok. The repair is a pointer update, never a file move: `gbrain sources set-path default <path>` prints the prior value before changing it and refuses a path that nests inside or swallows another source's tree (exit 6; `--force` bypasses). **Say to your agent:** *"Run a brain health check and fix what you find"* — the maintain skill runs `gbrain doctor` and applies the printed repair.-**A Gmail, Calendar or GitHub connector source still has an old `local_path`?** Connector sources sync from their provider, so autopilot ignores their `local_path`: once a connector has synced (or tried to) at least once, autopilot syncs it on every interval and runs its database phases with no checkout. A connector that has never synced stays idle until you run `gbrain sync --source <id>` once; autopilot prints that command the first time it skips one. To remove the stale pointer, run `gbrain sources set-path <id> --clear` (connector sources only; it refuses a filesystem source and a connector bound to a canonical owner). `config.syncEnabled=false` still opts a source out. **Say to your agent:** *"My Gmail source points at an old folder. Clear it and keep it syncing."*+**A Gmail, Calendar or GitHub connector source still has an old `local_path`?** Connector sources sync from their provider, so autopilot ignores their `local_path`: once a connector has synced (or tried to) at least once, autopilot syncs it on every interval and runs its database phases with no checkout. A connector that has never synced stays idle until you run `gbrain sync --source <id>` once; autopilot prints that command the first time it skips one. To remove the stale pointer, run `gbrain sources set-path <id> --clear` (connector sources, or any source whose `local_path` is relative; it refuses a filesystem source with an absolute path and any source bound to a canonical owner). `config.syncEnabled=false` still opts a source out. **Say to your agent:** *"My Gmail source points at an old folder. Clear it and keep it syncing."*<a id="write-refused"></a>**A save, sync or background effect was refused with a named reason?** Reasons such as `file_database_drift`, `ambiguous_source_path`, `physical_root_device_changed`, `cursor_processing_options_conflict`, `take_row_collision`, `invalid_source_uri`, `queue_capacity` and parked effects (`targets_parked`, doctor `parked_effects`) each come with a recovery step in the error's `suggestion`. [Write refusal reasons](write-refusals.md) explains each one and its recovery. **Say to your agent:** *"My save was refused. Explain the reason and show me the fix before you run it."*@@ -855,8 +855,11 @@ no origin path, matching a folder to its source ignores the path, fence repairedits stored pages, managed activation refuses it (`source_changed`, detail`source_path_missing`), the dream, autopilot, per-phase and globalmaintenance cycles and `gbrain maintain` run only their database phases,-`sources set-path` and the write-through leak guard do not count it as-another source's tree, `gbrain autopilot+`sources set-path` does not count it as another source's tree, the+write-through leak guard counts a live source's relative path as owning any+tree (so a `default` source with no `local_path` saves its pages to the+database only, `source_repo_belongs_to_other_source`, until that path is set+or cleared), `gbrain autopilot--install` asks for `--repo`, a remote `submit_job` for the source isrefused, import does not count the folder as a configured root or stamp itfresh, and a managed brain does not record it as a managed root. A few otherdiff --git a/llms-full.txt b/llms-full.txtindex 32fcb447a1..362b861fea 100644--- a/llms-full.txt+++ b/llms-full.txt@@ -10294,7 +10294,7 @@ Turning the `preparation_deadlines` switch off (`gbrain config set persistence.p**`gbrain doctor` warns `default_source_local_path`?** Your `default` source has no `local_path` AND that null pointer is provably breaking write-through (the repo fallback is another source's own working tree, or file-backed default pages have no resolvable root). A null `local_path` on its own is the designed fallback topology and reports ok. The repair is a pointer update, never a file move: `gbrain sources set-path default <path>` prints the prior value before changing it and refuses a path that nests inside or swallows another source's tree (exit 6; `--force` bypasses). **Say to your agent:** *"Run a brain health check and fix what you find"* — the maintain skill runs `gbrain doctor` and applies the printed repair.-**A Gmail, Calendar or GitHub connector source still has an old `local_path`?** Connector sources sync from their provider, so autopilot ignores their `local_path`: once a connector has synced (or tried to) at least once, autopilot syncs it on every interval and runs its database phases with no checkout. A connector that has never synced stays idle until you run `gbrain sync --source <id>` once; autopilot prints that command the first time it skips one. To remove the stale pointer, run `gbrain sources set-path <id> --clear` (connector sources only; it refuses a filesystem source and a connector bound to a canonical owner). `config.syncEnabled=false` still opts a source out. **Say to your agent:** *"My Gmail source points at an old folder. Clear it and keep it syncing."*+**A Gmail, Calendar or GitHub connector source still has an old `local_path`?** Connector sources sync from their provider, so autopilot ignores their `local_path`: once a connector has synced (or tried to) at least once, autopilot syncs it on every interval and runs its database phases with no checkout. A connector that has never synced stays idle until you run `gbrain sync --source <id>` once; autopilot prints that command the first time it skips one. To remove the stale pointer, run `gbrain sources set-path <id> --clear` (connector sources, or any source whose `local_path` is relative; it refuses a filesystem source with an absolute path and any source bound to a canonical owner). `config.syncEnabled=false` still opts a source out. **Say to your agent:** *"My Gmail source points at an old folder. Clear it and keep it syncing."*<a id="write-refused"></a>**A save, sync or background effect was refused with a named reason?** Reasons such as `file_database_drift`, `ambiguous_source_path`, `physical_root_device_changed`, `cursor_processing_options_conflict`, `take_row_collision`, `invalid_source_uri`, `queue_capacity` and parked effects (`targets_parked`, doctor `parked_effects`) each come with a recovery step in the error's `suggestion`. [Write refusal reasons](write-refusals.md) explains each one and its recovery. **Say to your agent:** *"My save was refused. Explain the reason and show me the fix before you run it."*@@ -11012,8 +11012,11 @@ no origin path, matching a folder to its source ignores the path, fence repairedits stored pages, managed activation refuses it (`source_changed`, detail`source_path_missing`), the dream, autopilot, per-phase and globalmaintenance cycles and `gbrain maintain` run only their database phases,-`sources set-path` and the write-through leak guard do not count it as-another source's tree, `gbrain autopilot+`sources set-path` does not count it as another source's tree, the+write-through leak guard counts a live source's relative path as owning any+tree (so a `default` source with no `local_path` saves its pages to the+database only, `source_repo_belongs_to_other_source`, until that path is set+or cleared), `gbrain autopilot--install` asks for `--repo`, a remote `submit_job` for the source isrefused, import does not count the folder as a configured root or stamp itfresh, and a managed brain does not record it as a managed root. A few otherdiff --git a/test/terminal-failures-6650.test.ts b/test/terminal-failures-6650.test.tsindex 1349af6cc9..6c09969afc 100644--- a/test/terminal-failures-6650.test.ts+++ b/test/terminal-failures-6650.test.ts@@ -434,6 +434,19 @@ for (const kind of testBackends()) describe(`the aggregate, doctor and the drillexpect(rows.rows!.map(r => r.request_id)).toEqual(g.samples.map(s => s.request_id));}const table = renderWriterFailures(grouped, false).split('\n');+ await seed({ slug: 'notes/big1', operation: 'submit_job', state: 'failed', code: 'file_too_large' });+ await seed({ slug: 'notes/big2', operation: 'put_page', state: 'failed', code: 'file_too_large' });+ const regrouped = await readTerminalFailures(engine, { sourceId: SOURCE, groupBy: 'category' });+ if (regrouped.status !== 'ok') throw new Error('unknown');+ const big = regrouped.groups!.filter(g => g.code === 'file_too_large');+ expect(big.map(g => g.operation).sort()).toEqual(['put_page', 'submit_job']);+ for (const g of big) {+ expect(g.fix.argv).toEqual(['gbrain', 'sources', 'writer', 'status', '--source', SOURCE, '--json']);+ const parsed = parsePersistenceAdminArgs('writer', g.drill_down.slice(3));+ const rows = await runPersistenceAdministration(engine, parsed.operation, parsed.params) as TerminalFailureListing;+ if (rows.status !== 'ok') throw new Error('unknown');+ expect(rows.rows!.map(r => r.request_id)).toEqual(g.samples.map(s => s.request_id));+ }for (const op of ['submit_job', 'takes_supersede', 'takes_resolve']) expect(table.some(l => /^\s+\d+\s/.test(l) && l.includes(' preparation_stalled ') && l.includes(` ${op} `))).toBe(true);});