Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix(doctor,writer-failures): Windows-absolute sync.repo_path is not relative; grouped drill-downs keep --operation
garrytan7cb9b92ebfd6
diff --git a/docs/architecture/key-files/managed-sync-bookkeeping.md b/docs/architecture/key-files/managed-sync-bookkeeping.mdindex f630c4760a..6c26d6c43c 100644--- a/docs/architecture/key-files/managed-sync-bookkeeping.md+++ b/docs/architecture/key-files/managed-sync-bookkeeping.md@@ -37,7 +37,7 @@ run, and the supersession of a checkpoint whose cursor another run replaced. The- `src/core/persistence/sync-knock-on.ts` — #6643, shrunk by #6712 (one page, one fate): no producer is left. It keeps the legacy predicate over receipts older builds wrote (`error_detail` `{ origin: 'sync_knock_on', reason, root_request_id }`, or the pre-#6643 producers' exact messages, never an operator cancel): `isSyncKnockOn`/`syncKnockOnSql` (one predicate, never NULL) feed the terminal classifier, which renders such a receipt superseded, and `sync-run.ts` `refreezeInPlace`, which re-freezes the entry when a resumed cursor meets one (bounded by `STOPS_PER_ENTRY`, no config key). `cursorFenceCause` reads the two live causes of "cursor changed" (`run_replaced`, `outside_fence`; an older `window_dropped` still parses). `checkpoint-validation.ts` clause 3 skips converted receipts and the cursor's settled index ranges only; #6712 removed the knock-on exemption. `reviveCheckpoint` re-assesses a refused checkpoint at the cursor's end. `sync status` shows the cursor the recorded failure belongs to, `cursors`, and `checkpoint_blockers` (`listIncompleteSyncReceipts`, each with `knock_on`).- `src/core/persistence/terminal-classify.ts` — #6650: `classifyTerminal` turns one terminal receipt (`failed` / `conflict` / `cancelled`, or any row still holding `recovery`) into a `TerminalVerdict` (category, code, origin, class, `safe_actions`, `needs_human`, `defect`, `historical`, `root_request_id`, one structured `action`) at read time; nothing is persisted. A recovery record outranks the code (`recovery_pending` / `recovery_blocked`); a knock-on is read through `isSyncKnockOn` (typed marker survives compaction) or the SQL twin `terminalKnockOnSql`; `storage_error` and `source_changed` route by their recorded origin or cause, and a row whose code and origin do not say what happened is `diagnosis_required` (read-only writer status, never a guessed fix). A `source_changed` whose canonical file is missing is `canonical_file_missing` (a ghost page; its exit is the `gbrain repair ghost-pages` preview, never a sync retry), and an origin-less `fence_unrenderable` adoption refusal is its own defect category. `TERMINAL_FIXED_IN` names the release that fixed a category; a row whose build (`error_detail.attempt.consumer_version`, else `admitter_version`) is older is historical. It also owns the supersession rule `repair/failed-writes.ts` reuses (`supersessionSql`, `supersessionOrderSql`, `dispositionOf`, `PAGE_REMOVAL_OPERATIONS`). Tests: `test/terminal-failures-6650.test.ts` (TS↔SQL twin parity included), `test/terminal-classify-6696.test.ts`.- `src/core/persistence/terminal-failures.ts` — #6650: the bounded readers over that classifier. `readTerminalFailureSummary` is one set-based aggregate (GROUPING SETS per source; `TERMINAL_STATEMENT_MS` 5 s statement and `TERMINAL_ACQUIRE_MS` 2 s connection deadlines; past either it returns `status: 'unknown'`, never an empty pile) splitting active blockers (recovery records plus the passed-in `checkpoint_blockers` of `sync-status.ts`, read by `readCheckpointBlockerMap`), unresolved rows (count, distinct slugs and intents, oldest age), historical rows (a later write superseded them, or older than `TERMINAL_FIXED_IN` via the SQL twin `TERMINAL_HISTORICAL_SQL`), 24 h and 7-day daily counts, categories and defect classes; archived sources are skipped. Thresholds `persistence.terminal_failures.window_days` (clamped to `persistence.receipt_retention_days`), `spike_factor`, `spike_min` (`readTerminalThresholds`, `validateTerminalConfigValue`, refused at `config set` by `commands/config/preparation-keys.ts`); `isSpike` against `sevenDayMedian`. `readTerminalFailures` is the drill-down (batches of 200, at most 2,000 rows scanned per call, a sequence cursor, verdict filters, `--group-by category` groups with an exact `drill_down` argv each). Consumers: doctor `persistence_terminal_failures` (`commands/doctor/checks/persistence-requests.ts`), `sync status` `terminal_failures` (`sync-status.ts`, `next` falls back to a recovery blocker's action), the `writer_failures` administration operation, and the admin `/metrics` gauges (`serve-http-metrics.ts` `renderTerminalFailureMetrics`, one aggregate per engine shared by scrapes for `TERMINAL_METRICS_TTL_MS` = 60 s via `cachedTerminalSummary`; never `/health`). Each source also reports `new_last_24h_older_builds` (rows and builds older than their class's fix), and doctor's spike message says an older write owner is producing them when they are most of the spike. Tests: `test/terminal-failures-6650.test.ts`, `test/sync-status-terminal-6650.test.ts`, `test/terminal-failure-metrics-6650.test.ts`, the CLI journey `test/agent-journey-terminal-failures-6650.test.ts`.-- `src/commands/sources-writer-failures.ts` — #6650: output of `gbrain sources writer failures <source> [--state all] [--group-by category] [--since Nd] [--limit N] [--before <cursor>] [--category|--code|--origin] [--json]`, dispatched by `persistence-admin.ts` as `writer_failures` (validated in `administration.ts` `writerFailuresQuery`, locally or through the resident owner). A table by default, one JSON document with `--json`; row and group `fix` / `inspect` actions are rendered for the CLI; a full page prints `truncated` with the exact next command. The operation is advertised to clients in the owner's `administration_extensions` (`ipc.ts`, `admin-contract.ts` `PERSISTENCE_ADMIN_EXTENSIONS`), never in the `administration` list an older client validates strictly, and `local-client.ts` delegates it only to an owner that lists it (`ownerAdministers`). Tests: `test/writer-failures-cli-6650.test.ts`.+- `src/commands/sources-writer-failures.ts` — #6650: output of `gbrain sources writer failures <source> [--state all] [--group-by category] [--since Nd] [--limit N] [--before <cursor>] [--category|--code|--origin|--operation] [--json]`, dispatched by `persistence-admin.ts` as `writer_failures` (validated in `administration.ts` `writerFailuresQuery`, locally or through the resident owner). A table by default, one JSON document with `--json`; row and group `fix` / `inspect` actions are rendered for the CLI; a full page prints `truncated` with the exact next command. The operation is advertised to clients in the owner's `administration_extensions` (`ipc.ts`, `admin-contract.ts` `PERSISTENCE_ADMIN_EXTENSIONS`), never in the `administration` list an older client validates strictly, and `local-client.ts` delegates it only to an owner that lists it (`ownerAdministers`). Tests: `test/writer-failures-cli-6650.test.ts`.- `src/core/persistence/public-category.ts` — #6712 PR 2 (L5): `publicCategory({ category?, code })`, the closed public vocabulary (`drift`, `conflict`, `content_refused`, `file_missing`, `permission`, `storage`, `config`, `superseded`, `transient`, `defect`) that sits beside the unchanged diagnosis `category`. `PUBLIC_BY_TERMINAL` maps every `TerminalCategory`, `PUBLIC_BY_CODE` every `SYNC_FAULT_TABLE` code (a new fault code needs a row: `test/public-category.test.ts`), and anything else goes by its registry class (unknown codes are `defect`). `classifyTerminal` carries it as `public_category`; `classifyRecordedFault` (terminal-classify.ts) reads a hold, a managed-sync failure row or a run stop as the failed receipt it stands for, so the receipt diagnosis, `managedWrite`, sync status holds and `last_error`, the terminal summary and doctor `sync_failures` (`details.failures`) render one verdict.- Pass round phase lines and honest stalls (GBRA-133 PR 3a, #7243; `src/core/persistence/sync-pass-run.ts`, `sync-pass-status.ts`, `sync-drain.ts`) — each pass round emits `managed_sync.round_level` (paths, target, read time) after its level read and `managed_sync.round_admit` (imports, deletes, in flight) before its import walk, and an announcing drain prints them (`[sync] pass round N: …`). The `convergence` block's `target` is the newest pass's pinned commit (telemetry) and `converged_target` the stored converged obligation's target, null while no stamp backs one, so status never presents the pin as converged. The drain counts only page and checkpoint commits as progress (a legacy-sweep slice or a level read still working only keeps the quiet clock fresh); an abandoned pass's late progress is dropped; a stop whose head owner reports `restart_required` is `owner_restart_required` (`drainNext` names the process); a run that committed nothing (no advanced cursor, no committed page) stops as `sync_deadline_stalled` (exit 1). Tests: `test/sync-pass-phase-lines-7243.serial.test.ts`, `test/sync-status-truthful-7243.test.ts`, `test/honest-stalls-gbra133.test.ts`.- `src/core/persistence/sync-tail.ts` + `sync-tail-record.ts` — #6712 PR 2 (L5): the tail of a committed checkpoint (projection statistics, then link extraction for the run's imported slugs read from its manifest). `recordSyncTail` runs inside the checkpoint's publication transaction (`applyManagedSyncCheckpoint`) and appends `{run_id, changed, extract}` to `op_checkpoints` `managed-sync-tail` / `<source>` (at most 16), so the tail is owed before anyone can read the run as synced. `withSyncTail` runs it after the outermost drain lease is released (`performManagedBranch`, and `performManagedSync` when it took the lease itself; a call still inside a lease, a dry run and a lease-held follower run none), bounded by `SYNC_TAIL_BUDGET_MS` (5 min) and the caller's deadline, and folds `tail` (`done` / `truncated` / `degraded` / `deferred` / `failed`, with `underived`: the run's imports its link extraction left underived, which the per-source "still owe extraction" line prints) and `links` into the result. The obligation is cleared by compare-and-swap only when every step ran; a failed, deferred or truncated tail attaches a degraded `sync_tail_degraded` notice with its fix (the sync CLI prints it with the capacity notices). Fault point `sync:tail_started`. Tests: `test/sync-drain-finish-tail.test.ts`.diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.mdindex 2ef673cd21..eacf05bdc1 100644--- a/docs/guides/troubleshooting.md+++ b/docs/guides/troubleshooting.md@@ -248,7 +248,7 @@ A spike warns only on its own: when at least `persistence.terminal_failures.spik```bashgbrain doctor --only persistence_terminal_failures --json # blockers, unresolved, historical, the fixgbrain sync status --source <id> # the same summary for one source, with BLOCKING lines-gbrain sources writer failures <id> --group-by category # groups on code + origin + category, each with its drill-down+gbrain sources writer failures <id> --group-by category # groups on code + origin + category (+ operation for a sync_fault), each with its drill-downgbrain sources writer failures <id> --category owner_exception --code storage_error --origin owner_exception --jsongbrain write-request <request> --json # one receipt: write_error_reason, suggestion, diagnosis.fix```diff --git a/llms-full.txt b/llms-full.txtindex f553cebd7b..85d4266698 100644--- a/llms-full.txt+++ b/llms-full.txt@@ -10405,7 +10405,7 @@ A spike warns only on its own: when at least `persistence.terminal_failures.spik```bashgbrain doctor --only persistence_terminal_failures --json # blockers, unresolved, historical, the fixgbrain sync status --source <id> # the same summary for one source, with BLOCKING lines-gbrain sources writer failures <id> --group-by category # groups on code + origin + category, each with its drill-down+gbrain sources writer failures <id> --group-by category # groups on code + origin + category (+ operation for a sync_fault), each with its drill-downgbrain sources writer failures <id> --category owner_exception --code storage_error --origin owner_exception --jsongbrain write-request <request> --json # one receipt: write_error_reason, suggestion, diagnosis.fix```diff --git a/src/commands/persistence-admin.ts b/src/commands/persistence-admin.tsindex 36dc8ade9d..ae81516444 100644--- a/src/commands/persistence-admin.ts+++ b/src/commands/persistence-admin.ts@@ -36,7 +36,8 @@ failures (read-only) lists the source's write receipts that ended without commit(failed, conflict, cancelled) plus any still holding a recovery record, newest first, eachwith its class, safe actions, whether a person decides, its disposition (superseded,already_written, duplicate or unknown), an inspect command and its fix. --group-by category-groups them on code, origin and category, each group with its exact drill-down filter.+groups them on code, origin and category (a sync_fault group also on its operation), each+group with its exact drill-down filter; --operation <op> keeps one write operation.A full page prints truncated with the next command (--before <cursor>). Unresolved rows bydefault; --state all adds resolved and historical ones. Human table by default, JSON with --json.Inspect status first. movement proves that managed sync data moves over a windowdiff --git a/src/core/default-source-path-check.ts b/src/core/default-source-path-check.tsindex ed21bc9056..64fd39363d 100644--- a/src/core/default-source-path-check.ts+++ b/src/core/default-source-path-check.ts@@ -34,7 +34,7 @@* npm-squat-check.ts / pglite-leftovers-check.ts. The gathering wrapper* lives on the doctor surface (doctor/checks/default-source-path.ts).*/-import { isAbsolute, posix, win32 } from 'path';+import { posix, win32 } from 'path';export interface DefaultSourcePathInput {/** The `default` sources row, or undefined when no such row exists. */@@ -84,7 +84,7 @@ export function assessDefaultSourcePath(message: `default source local_path is set: ${defaultSource.local_path}`,};}- if (repoPath && !isAbsolute(repoPath)) {+ if (repoPath && !posix.isAbsolute(repoPath) && !win32.isAbsolute(repoPath)) {return {status: 'warn',message:diff --git a/src/core/persistence/terminal-failures.ts b/src/core/persistence/terminal-failures.tsindex 86c1a88c18..cfd8cf3f39 100644--- a/src/core/persistence/terminal-failures.ts+++ b/src/core/persistence/terminal-failures.ts@@ -380,7 +380,7 @@ export async function readTerminalFailures(engine: BrainEngine, q: TerminalFailuconst filter = { code: row.code, origin: row.origin, category: row.category, ...(operation === undefined ? {} : { operation }) };groups.set(key, g = { code: row.code, origin: row.origin, category: row.category, ...(operation === undefined ? {} : { operation }), public_category: row.public_category, rows: 0, class: row.class, needs_human: row.needs_human,...(row.human_reason ? { human_reason: row.human_reason } : {}), filter, fix: row.fix, samples: [],- drill_down: terminalFailuresArgv({ sourceId: q.sourceId, state: q.state, sinceDays: q.sinceDays, category: row.category, code: row.code, origin: row.origin ?? NO_ORIGIN, operation }) });+ drill_down: terminalFailuresArgv({ sourceId: q.sourceId, state: q.state, sinceDays: q.sinceDays, category: row.category, code: row.code, origin: row.origin ?? NO_ORIGIN, operation: operation ?? q.operation }) });}g.rows++;if (g.samples.length < 3) g.samples.push({ request_id: row.request_id, slug: row.slug, state: row.state, ended_at: row.ended_at, inspect: row.inspect });diff --git a/test/default-source-path-check.test.ts b/test/default-source-path-check.test.tsindex 1320afb078..f0196cd668 100644--- a/test/default-source-path-check.test.ts+++ b/test/default-source-path-check.test.ts@@ -56,6 +56,13 @@ describe('assessDefaultSourcePath (pure)', () => {expect(a.message).toContain('/some/dir');});+ // #7630: a shared brain may hold a Windows host's sync.repo_path; doctor on another OS must not call it relative.+ test('null local_path + Windows-absolute sync.repo_path is not reported as relative', () => {+ const a = assessDefaultSourcePath({ ...BASE, livePages: 3, fileBackedPages: 3, repoPath: 'C:\\brain-example', repoPathIsDir: false });+ expect(a.status).toBe('warn');+ expect(a.message).not.toContain('relative path');+ });+test('null local_path + no pages → ok (nothing routes through it yet)', () => {const a = assessDefaultSourcePath({ ...BASE, livePages: 0 });expect(a.status).toBe('ok');diff --git a/test/sync-relative-anchor-refusal-7630.test.ts b/test/sync-relative-anchor-refusal-7630.test.tsindex f29b9d72cb..c1fea2e730 100644--- a/test/sync-relative-anchor-refusal-7630.test.ts+++ b/test/sync-relative-anchor-refusal-7630.test.ts@@ -439,6 +439,8 @@ for (const backend of testBackends()) {expect(check?.status).toBe('warn');expect(check?.message).toContain('sync.repo_path is the relative path "."');expect(check?.message).toContain('gbrain config set sync.repo_path <absolute-directory>');+ expect(check?.message).toContain('gbrain sources set-path default <absolute-directory>');+ expect(check?.message).not.toContain('sync refuses it');}, 120_000);// Value: protects=a successful sync of another source never runs .gitignore upkeep on the cwd's Git repo through a stored relative root;diff --git a/test/terminal-failures-6650.test.ts b/test/terminal-failures-6650.test.tsindex fd1fe6894c..9f99957c6e 100644--- a/test/terminal-failures-6650.test.ts+++ b/test/terminal-failures-6650.test.ts@@ -454,6 +454,25 @@ for (const kind of testBackends()) describe(`the aggregate, doctor and the drillfor (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);});+ // #7630: --operation narrows every category, so every group's drill-down carries it and lists exactly the group's rows.+ test('--group-by category with --operation keeps the operation in every group drill-down', async () => {+ await seed({ slug: 'notes/a', operation: 'put_page', state: 'failed', code: 'storage_error' });+ await seed({ slug: 'notes/b', operation: 'submit_job', state: 'failed', code: 'storage_error' });+ await seed({ slug: 'notes/c', operation: 'put_page', state: 'failed', code: 'preparation_stalled' });+ await seed({ slug: 'notes/d', operation: 'submit_job', state: 'failed', code: 'preparation_stalled' });+ const grouped = await readTerminalFailures(engine, { sourceId: SOURCE, groupBy: 'category', operation: 'put_page' });+ if (grouped.status !== 'ok') throw new Error('unknown');+ expect(grouped.groups!.map(g => g.code).sort()).toEqual(['preparation_stalled', 'storage_error']);+ for (const g of grouped.groups!) {+ expect(g.drill_down[g.drill_down.indexOf('--operation') + 1]).toBe('put_page');+ 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!.length).toBe(g.rows);+ expect(rows.rows!.map(r => r.operation)).toEqual(['put_page']);+ }+ });+test('a read past its statement deadline is unknown, and doctor says health is unknown', async () => {await seed({ slug: 'notes/x', state: 'failed', code: 'storage_error', compacted: true });const slow = new Proxy(engine, { get(target, key) {