Skip to content

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.tsv
index 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 f
src/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.tsv
index 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 mention
src/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.md
index 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 repair
edits stored pages, managed activation refuses it (`source_changed`, detail
`source_path_missing`), the dream, autopilot, per-phase and global
maintenance 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 is
refused, import does not count the folder as a configured root or stamp it
fresh, and a managed brain does not record it as a managed root. A few other
diff --git a/llms-full.txt b/llms-full.txt
index 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 repair
edits stored pages, managed activation refuses it (`source_changed`, detail
`source_path_missing`), the dream, autopilot, per-phase and global
maintenance 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 is
refused, import does not count the folder as a configured root or stamp it
fresh, and a managed brain does not record it as a managed root. A few other
diff --git a/test/terminal-failures-6650.test.ts b/test/terminal-failures-6650.test.ts
index 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 drill
expect(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);
});