Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(durability): derive the AGENTS.md filing list from the source's top-level folders when it has no filing rules (#7629, GBRA-202)

garrytan28bc1425c0aa
diff --git a/docs/architecture/key-files/files-and-sync-1.md b/docs/architecture/key-files/files-and-sync-1.md
index 4047bb892d..92687b80c6 100644
--- a/docs/architecture/key-files/files-and-sync-1.md
+++ b/docs/architecture/key-files/files-and-sync-1.md
@@ -5,7 +5,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/core/audit-week-file.ts` — single source of truth for ISO-week audit JSONL filename math. Exports `isoWeek(d)`, `isoWeekFilename(prefix, now?)`, `resolveAuditDir()` (honors `GBRAIN_AUDIT_DIR`). Year-boundary correctness pinned by tests at 2020-W53 (the 53-week year), 2025-W01 rolling in from 2024-12-30 (Monday), 2026-W01. Four call sites: `src/core/minions/handlers/shell-audit.ts`, `src/core/facts/phantom-audit.ts`, `src/core/audit-slug-fallback.ts`, `src/core/cycle/budget-meter.ts`. Each keeps its `compute<X>AuditFilename` thin wrapper.
-- `src/core/brain-repo-durability.ts` + `src/commands/sources-harden.ts` — brain-repo git durability. `hardenBrainRepo(opts)` makes a brain's working tree durable, idempotently: divergence-safe pull, a LOCAL untracked `.git/hooks/post-commit` auto-push safety net (never committed — a pulled commit can't rewrite executed code next to the token; installed into the active `core.hooksPath` dir and excluded via `.git/info/exclude` when that dir is tracked), a committed `scripts/brain-commit-push.sh` delegating to `gbrain git commit-push` (`src/core/git/commit-push.ts`, #6530; guide `docs/guides/shared-checkout-git.md`) that never exits 0 without a confirmed push, and a hook running the harden-captured CLI with `--push-only --require-clean` (both `# gbrain-protocol: 2`; harden never downgrades), durability rules patched into the active resolver file (`findResolverFile` → RESOLVER.md > AGENTS.md; taxonomy rendered from the bundled `_brain-filing-rules.json`), a minimal DB-free pull cron (launchd/crontab running `gbrain sources pull --path <dir>` so it never opens the PGLite single-writer lock), and a push-probe verify (no heartbeat commit). Credential is REPO-scoped (`acceptPat` from `--pat-file`/`GBRAIN_GITHUB_PAT`, warns on loose perms; reuses an existing repo-local `credential.helper`, else a `0600` store wired via repo-local config); the token is redacted everywhere via `redactSecretsInText` and never enters the repo, remote URL, logs, or `DurabilityReport`. `unhardenBrainRepo` removes the cron/hook/credential wiring (ownership-fingerprinted); `sources remove` runs it only AFTER the source row's DELETE commits (a refused or raced delete leaves the scaffolding intact; post-commit teardown failure is loud but non-fatal). CLI: `gbrain sources harden <id|--all>` / `pull <id>|--path <dir>` / `unharden <id>`; auto-harden fires on `sources add --url ... --pat-file` for managed clones (`--no-harden` opts out). `sources pull --path` is dispatched in `src/cli.ts` BEFORE `connectEngine` so the cron stays DB-free. CLI-only (writes executables + an OS cron + a credential helper on the host); never exposed over MCP. `isDurabilityHardened(repoPath)` (the durability hook banner is installed) and `commitWriteThroughFile(repoPath, absPath, slug, action = 'write-through')` are the shared helpers every write-through sink (page write/delete, facts fence, timeline, lint --fix) uses to best-effort commit ONE file path-limited on a hardened repo — never throws, false on any failure; `action` only labels the subject (`gbrain: <action> <slug>`; `'delete write-through'` for removals). `isDurabilityHardenedAsync(repoPath)` is the owners' non-blocking probe (#6210: rejects `git_unavailable` when unsure); it and the persistence Git runner (`effect-git.ts`) spawn through `execFileBounded` (defined in the import-free `src/core/bounded-child-exec.ts` and re-exported here; `git-remote.ts` `pullRepo` shares it), which settles at its deadline or on abort from its own timer because Bun can drop a child's pipe events and, before 1.3.14, its exit event (oven-sh/bun#30301) when bun:test `expect().resolves/.rejects` re-enters the event loop; an unbounded wait there stranded `disposePersistenceConsumer` and hung every later test in the file (test: `test/bounded-child-exec.test.ts`). Tests: `test/brain-repo-durability.serial.test.ts`, `test/git-remote-durable.serial.test.ts`, `test/brain-durability-hook.serial.test.ts`, `test/durability-cron.test.ts`. `brain_remote_contains_commit` checks the exact `refs/heads/<branch>` at every effective push URL, fetches each advertised tip without writing `FETCH_HEAD`, and proves ancestry of the captured commit; branch existence, a different fetch destination, or a stale tracking ref is not enough. Probe diagnostics are suppressed, ambiguous URL resolution fails closed, and recovery is skipped if local HEAD has moved since the failed push. This check runs after a rejected push and after retry failure, logging `ok-already-on-remote` on confirmation; `getLastPushOutcome` recognizes it as success. Existing unmanaged installations must rerun `gbrain sources harden <source-id>` to refresh both the local hook and committed helper; upgrading the CLI alone does not rewrite those scripts. Managed worktrees retain the persistence outbox as their Git writer; generated legacy helpers refuse to bypass it. Locks, waits, outcomes and the per-checkout conflict record: the guide. Tests: `test/git-commit-push-6530.serial.test.ts`.
+- `src/core/brain-repo-durability.ts` + `src/commands/sources-harden.ts` — brain-repo git durability. `hardenBrainRepo(opts)` makes a brain's working tree durable, idempotently: divergence-safe pull, a LOCAL untracked `.git/hooks/post-commit` auto-push safety net (never committed — a pulled commit can't rewrite executed code next to the token; installed into the active `core.hooksPath` dir and excluded via `.git/info/exclude` when that dir is tracked), a committed `scripts/brain-commit-push.sh` delegating to `gbrain git commit-push` (`src/core/git/commit-push.ts`, #6530; guide `docs/guides/shared-checkout-git.md`) that never exits 0 without a confirmed push, and a hook running the harden-captured CLI with `--push-only --require-clean` (both `# gbrain-protocol: 2`; harden never downgrades), durability rules patched into the active resolver file (`findResolverFile` → RESOLVER.md > AGENTS.md; taxonomy from the repo's own `_brain-filing-rules.json`, else its top-level content folders, else the bundled default, #7629), a minimal DB-free pull cron (launchd/crontab running `gbrain sources pull --path <dir>` so it never opens the PGLite single-writer lock), and a push-probe verify (no heartbeat commit). Credential is REPO-scoped (`acceptPat` from `--pat-file`/`GBRAIN_GITHUB_PAT`, warns on loose perms; reuses an existing repo-local `credential.helper`, else a `0600` store wired via repo-local config); the token is redacted everywhere via `redactSecretsInText` and never enters the repo, remote URL, logs, or `DurabilityReport`. `unhardenBrainRepo` removes the cron/hook/credential wiring (ownership-fingerprinted); `sources remove` runs it only AFTER the source row's DELETE commits (a refused or raced delete leaves the scaffolding intact; post-commit teardown failure is loud but non-fatal). CLI: `gbrain sources harden <id|--all>` / `pull <id>|--path <dir>` / `unharden <id>`; auto-harden fires on `sources add --url ... --pat-file` for managed clones (`--no-harden` opts out). `sources pull --path` is dispatched in `src/cli.ts` BEFORE `connectEngine` so the cron stays DB-free. CLI-only (writes executables + an OS cron + a credential helper on the host); never exposed over MCP. `isDurabilityHardened(repoPath)` (the durability hook banner is installed) and `commitWriteThroughFile(repoPath, absPath, slug, action = 'write-through')` are the shared helpers every write-through sink (page write/delete, facts fence, timeline, lint --fix) uses to best-effort commit ONE file path-limited on a hardened repo — never throws, false on any failure; `action` only labels the subject (`gbrain: <action> <slug>`; `'delete write-through'` for removals). `isDurabilityHardenedAsync(repoPath)` is the owners' non-blocking probe (#6210: rejects `git_unavailable` when unsure); it and the persistence Git runner (`effect-git.ts`) spawn through `execFileBounded` (defined in the import-free `src/core/bounded-child-exec.ts` and re-exported here; `git-remote.ts` `pullRepo` shares it), which settles at its deadline or on abort from its own timer because Bun can drop a child's pipe events and, before 1.3.14, its exit event (oven-sh/bun#30301) when bun:test `expect().resolves/.rejects` re-enters the event loop; an unbounded wait there stranded `disposePersistenceConsumer` and hung every later test in the file (test: `test/bounded-child-exec.test.ts`). Tests: `test/brain-repo-durability.serial.test.ts`, `test/git-remote-durable.serial.test.ts`, `test/brain-durability-hook.serial.test.ts`, `test/durability-cron.test.ts`. `brain_remote_contains_commit` checks the exact `refs/heads/<branch>` at every effective push URL, fetches each advertised tip without writing `FETCH_HEAD`, and proves ancestry of the captured commit; branch existence, a different fetch destination, or a stale tracking ref is not enough. Probe diagnostics are suppressed, ambiguous URL resolution fails closed, and recovery is skipped if local HEAD has moved since the failed push. This check runs after a rejected push and after retry failure, logging `ok-already-on-remote` on confirmation; `getLastPushOutcome` recognizes it as success. Existing unmanaged installations must rerun `gbrain sources harden <source-id>` to refresh both the local hook and committed helper; upgrading the CLI alone does not rewrite those scripts. Managed worktrees retain the persistence outbox as their Git writer; generated legacy helpers refuse to bypass it. Locks, waits, outcomes and the per-checkout conflict record: the guide. Tests: `test/git-commit-push-6530.serial.test.ts`.
- `src/core/classic-file-holds.ts` — classic sync's deterministic per-file refusals as holds in the shared hold store. `classifyClassicFile(root, relPath, gitRoot)` reads metadata only (lstat, the symlink target's realpath, an open+close of a regular file; for a missing path `git ls-tree HEAD` and `git ls-files -v` with optional locks off) and returns `file_unreadable` (`symlink_in_repo`, `symlink_outside_root`, `symlink_dangling`, `symlink_loop`, `permission_denied`, `not_regular_file`), `absent_from_worktree` (`skip_worktree`, `deleted_locally`), or null (a readable file, a directory, a path HEAD lacks, any other error, all left to the drain's existing paths). `classicFileHoldFix` is `gitHoldFix`'s builder for both codes: the user's step for a symlink or permission, `ask_user` between restore and committing the deletion for an absent file; `<checkout>` is an `inputs` placeholder. Pinned by `test/pathological/s-classic-file-holds.test.ts` (+ its Postgres wrapper).
- `src/core/classic-rename-holds.ts` — `gitHoldFix`'s builder for classic sync's two rename holds (GBRA-133): `rename_identity_unreadable` (S-51; the database refused to compare a renamed file's title or id, so the new file waits and the old page stays whole; written by `holdUnreadableRenames` in `src/commands/sync/holds.ts` and decided again by `redecideUnreadableRenames` when the file changes) and `rename_reconcile_failed` (S-67; the `renames.ts` reconcile threw something other than its unprovable verdict or a transient database error while finding stale rows, so the rename is held with the error's class and code only; a failed delete keeps the `<rename:…>` marker). Both fixes are the user's. Pinned by `test/pathological/s-51-rename-identity-unreadable.test.ts` and `test/pathological/s-70-classifier-origin.test.ts`.
diff --git a/src/core/brain-repo-durability.ts b/src/core/brain-repo-durability.ts
index 5bdc379c27..00c97f411e 100644
--- a/src/core/brain-repo-durability.ts
+++ b/src/core/brain-repo-durability.ts
@@ -29,7 +29,7 @@ import { assertManagedFilesystemWrite, hasFilesystemPublication, managedFilesyst
*/
import {
- existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, rmSync, statSync, renameSync, appendFileSync, realpathSync,
+ existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, rmSync, statSync, renameSync, appendFileSync, realpathSync, readdirSync,
} from 'fs';
import { join, dirname, relative, isAbsolute, sep } from 'path';
import { execFileSync, execSync } from './spawn.ts';
@@ -317,20 +317,39 @@ exit 4
// ── Managed AGENTS/RESOLVER block (taxonomy from filing rules; no drift) ─────
+/** Top-level folders that hold gbrain plumbing rather than filed content. */
+const NON_CONTENT_DIRS = new Set(['skills', 'scripts', 'node_modules']);
+
/**
* Resolve the filing-rules taxonomy for `repoPath`: prefer the repo's own
* `skills/_brain-filing-rules.json`, then `_brain-filing-rules.json` at the
- * repo root, else the bundled default. Fails open — a missing or malformed
+ * repo root. Without one (#7629), a repo that already keeps content in
+ * top-level folders gets those folders, each bundled rule that lives under one
+ * keeping its kind; a repo with no content folder yet gets the bundled default,
+ * the convention a new brain starts from. Fails open — a missing or malformed
* repo file must never break `sources harden`.
*/
-function resolveFilingRules(repoPath: string): FilingRulesDoc {
- for (const dir of [join(repoPath, 'skills'), repoPath]) {
+function resolveFilingRules(repoPath: string): { rules: FilingRulesDoc; from: string } {
+ for (const [dir, from] of [[join(repoPath, 'skills'), '`skills/_brain-filing-rules.json`'], [repoPath, '`_brain-filing-rules.json`']]) {
try {
const rules = loadFilingRules(dir);
- if (rules) return rules;
- } catch { /* malformed — fall through to the bundled default */ }
+ if (rules) return { rules, from };
+ } catch { /* malformed — fall through */ }
}
- return filingRulesDoc as FilingRulesDoc;
+ const bundled = filingRulesDoc as FilingRulesDoc;
+ let folders: string[] = [];
+ try {
+ folders = readdirSync(repoPath, { withFileTypes: true })
+ .filter((d) => d.isDirectory() && !d.name.startsWith('.') && !NON_CONTENT_DIRS.has(d.name))
+ .map((d) => d.name)
+ .sort();
+ } catch { /* unreadable — use the bundled default */ }
+ if (folders.length === 0) return { rules: bundled, from: "gbrain's default taxonomy" };
+ const rules = folders.flatMap((folder) => {
+ const known = (bundled.rules ?? []).filter((r) => String(r.directory || '').split('/')[0] === folder);
+ return known.length > 0 ? known : [{ kind: 'existing folder', directory: `${folder}/` }];
+ });
+ return { rules: { ...bundled, rules }, from: "this repository's top-level folders" };
}
function renderTaxonomyLines(rules: FilingRulesDoc): string {
@@ -354,7 +373,7 @@ function renderTaxonomyLines(rules: FilingRulesDoc): string {
* <source> --enable` (and `--pat-file`) regenerates it there.
*/
function renderManagedBlock(repoPath: string, managed?: { sourceId: string }): string {
- const rules = resolveFilingRules(repoPath);
+ const { rules, from } = resolveFilingRules(repoPath);
const regeneratedBy = managed ? `gbrain sources writer git-durability ${managed.sourceId} --enable` : 'gbrain sources harden';
const writeRules = managed ? `2. **Page writes go through gbrain, never through git.** This checkout is the
managed canonical worktree of gbrain source \`${managed.sourceId}\`: the persistence
@@ -395,7 +414,7 @@ function renderManagedBlock(repoPath: string, managed?: { sourceId: string }): s
## Brain durability rules (always on)
1. **Deterministic filing — never use /tmp as storage.** Every persistent output
- goes to its taxonomy path (canonical, from \`skills/_brain-filing-rules.json\`):
+ goes to its taxonomy path (from ${from}):
${renderTaxonomyLines(rules)}
Writing to /tmp, scratch dirs, or outside the repo is forbidden for anything
meant to persist.
diff --git a/test/filing-rules-resolution.serial.test.ts b/test/filing-rules-resolution.serial.test.ts
index 43a1d508c4..58f8c3c942 100644
--- a/test/filing-rules-resolution.serial.test.ts
+++ b/test/filing-rules-resolution.serial.test.ts
@@ -11,7 +11,7 @@ import { mkdtempSync, rmSync, writeFileSync, mkdirSync, readFileSync } from 'fs'
import { join } from 'path';
import { tmpdir } from 'os';
import { execFileSync } from 'child_process';
-import { hardenBrainRepo } from '../src/core/brain-repo-durability.ts';
+import { hardenBrainRepo, patchManagedDurabilityBlock } from '../src/core/brain-repo-durability.ts';
const PAT = 'ghp_TESTSECRETTOKEN0123456789abcdef';
@@ -82,6 +82,42 @@ describe('per-source filing-rules resolution', () => {
expect(agents).toContain('`people/`');
});
+ test('#7629: repo without a rules file whose content lives in its own top-level folders → those folders, not the default', async () => {
+ for (const dir of ['articles', 'atoms']) {
+ mkdirSync(join(work, dir));
+ writeFileSync(join(work, dir, 'example.md'), '# Example\n');
+ }
+ git(work, 'add', '-A'); git(work, 'commit', '-qm', 'content');
+ await harden();
+ const agents = readFileSync(join(work, 'AGENTS.md'), 'utf-8');
+ expect(agents).toContain('`articles/`');
+ expect(agents).toContain('`atoms/`');
+ expect(agents).toContain("from this repository's top-level folders");
+ expect(agents).not.toContain('`people/`');
+ expect(agents).not.toContain('`conversations/`');
+ expect(agents).not.toContain('`scripts/`');
+ });
+
+ test('#7629: a top-level folder the default taxonomy knows keeps its kind; folders the repo lacks are left out', async () => {
+ for (const dir of ['people', 'articles']) mkdirSync(join(work, dir));
+ await harden();
+ const agents = readFileSync(join(work, 'AGENTS.md'), 'utf-8');
+ expect(agents).toContain('`people/` — person');
+ expect(agents).toContain('`articles/`');
+ expect(agents).not.toContain('`companies/`');
+ });
+
+ test('#7629: git-durability --enable (managed block) derives the list the same way', () => {
+ const repo = join(root, 'managed');
+ for (const dir of ['articles', 'atoms']) mkdirSync(join(repo, dir), { recursive: true });
+ patchManagedDurabilityBlock(repo, 'source-a', false);
+ const agents = readFileSync(join(repo, 'AGENTS.md'), 'utf-8');
+ expect(agents).toContain('`articles/`');
+ expect(agents).toContain('`atoms/`');
+ expect(agents).not.toContain('`people/`');
+ expect(agents).toContain('gbrain sources writer git-durability source-a --enable');
+ });
+
test('malformed JSON in the repo file → falls back to bundled default, no throw', async () => {
writeRepoRules('{ this is not valid json');
await harden(); // must not throw