Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(cycle): unindexed_files reports incomplete when a source scan errors

garrytanc9aaaab7f1dc
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8cadb056cf..1c1295c5aa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,14 @@ credits are retained; no result has been reassigned to another provider. Origina
identifiers and attribution are available in the pre-removal Git revision
`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).
+## [Unreleased]
+
+**The `unindexed_files` maintenance phase no longer reports a complete scan when a source could not be scanned.** A source whose Git checkout failed to read was counted as an error and the phase warned, but its `details.complete` still said `true`, so anything reading the phase result took the run as a full scan of every managed source. `complete` is now `true` only when no source stopped at its time budget and none errored. Reported by @Masashi-Ono0611 (#8887).
+
+### Itemized changes
+
+- `src/core/cycle/unindexed-files.ts`: `details.complete` also requires `errors.length === 0`. Test: `test/unindexed-files.test.ts` (a source whose `.git/HEAD` is unreadable: phase `warn`, one error, `complete: false`).
+
## [0.60.620.0] - 2026-11-09
**A diverged managed checkout now publishes its local commits on refresh by default when Git durability is on, after a secret scan of those commits.** Commits a script made with plain `git commit` in a managed checkout used to strand there whenever the remote moved: every `gbrain sources refresh` refused `refresh_diverged` and asked the user, unless `sources.refresh_publish_diverged` was set to `true`. With the setting unset, a worktree whose Git durability is on (`gbrain sources writer git-durability <source> --enable`, or the legacy hook) now publishes them itself: the local commits merged with the upstream in memory, never a rebase or force-push, then the fast-forward. The publish child scans, under its publish lock and for the exact commits it pushes, what they add: commit messages, added lines (including a value a later commit removed) and merge-commit conflict resolutions. A value that looks like a secret, added text too large to scan, or a commit that changes `.gbrain-scan-allow` or a `.gitattributes` refuses the new `publish_secret_found` naming the file, line, rule and commit, never the value, with nothing pushed; commits the scan cannot read in full refuse `publish_scan_unreadable` instead. The rewritten-upstream refusal and the `--expect-remote` bound are unchanged. `false` turns it off; `true` still publishes with durability off.
diff --git a/docs/architecture/key-files/core-cycle.md b/docs/architecture/key-files/core-cycle.md
index 1891a1231f..7b8a44873a 100644
--- a/docs/architecture/key-files/core-cycle.md
+++ b/docs/architecture/key-files/core-cycle.md
@@ -57,6 +57,6 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/core/cycle/fence-repair.ts` — the `fence_repair` maintenance phase: `runFenceRepairPhase(engine, { dryRun, signal?, deadlineAtMs?, registry?, now? })` runs the `fences` repair kind (`src/core/repair/fences.ts`) once through the trusted `repairRunner` (apply; a preview on a dry run) over every active source, with no rule logic of its own: the kind plans from its census, skips sources this host may not write (an owner reason such as `host_mismatch`, `owner_unavailable` as the fallback) and the candidates a running sync still names (`sync_in_progress`; the rest of a syncing source is repaired), reads `fences.repair.llm` and the daily USD ledger, and re-plans on the next run. `fences.repair.enabled` false skips it without calling the kind (the summary names `gbrain config set fences.repair.enabled true`). The run's deadline is min(`FENCE_REPAIR_PHASE_BUDGET_MS` = 300 s, a third of the maintenance job's remaining time), 300 s without a job deadline; past it `runRepair` stops before the next item with `time_budget` (status ok, resumed by the next run). Details read the kind's `FenceRepairVerification`: `candidates`, `repaired`, `repaired_by_tier`, `held_by_reason`, `llm_usd`, `llm_usd_per_repair`, `oldest_hold_at`/`oldest_hold_age_hours`, `llm_enabled`, `scan_partial`, `time_budget_ms`, `stopped_reason`; the summary says when Tier 3 is off and how many fences need a manual edit (`fix`: `gbrain repair fences`). Any other stop reports `warn` with the kind's fix; an internal error reports `warn` with its code only (no message, which could carry fence content) unless the cycle is aborted. Brain-global, after `sync` in `ALL_PHASES`, classified `writes`. Test: `test/cycle-fence-repair.test.ts`.
- `src/core/cycle/content-repair.ts` — the `content_repair` maintenance phase (#6377): `runContentRepairPhase(engine, { dryRun, signal?, deadlineAtMs?, kinds?, registry?, now? })` runs the content-repair lane (`src/core/repair/content-lane.ts`) minus `fences`, which `fence_repair` just ran (`contentRepairPhaseKinds()`; with `CONTENT_REPAIR_KINDS` holding only `fences` the phase runs nothing and reports `skipped` / `no_kinds`), through the shared trusted `repairRunner` over every active source: an apply, or a preview on a dry run. Gated on `fences.repair.enabled` (one switch for the whole lane; the summary names `gbrain config set fences.repair.enabled true` and `gbrain repair content`). Deadline min(`CONTENT_REPAIR_PHASE_BUDGET_MS` = 120 s, a third of the maintenance job's remaining time); past it the lane's kind stops `time_budget` (status ok, the next run resumes). Details: `kinds`, `candidates`, `repaired`, `held_by_reason` (each kind's `remaining`, else its per-item outcome reasons), `by_kind` (mode, counts by outcome, spend, oldest hold, stop), `llm_usd`, `oldest_hold_at` / `oldest_hold_age_hours`, `time_budget_ms`, `stopped_reason`; the summary counts holds that wait for a person (`merge_recommended`, `content_repair_needs_human`) and points at `gbrain sync status`. Any stop other than the time budget reports `warn` with the kind's fix; an internal error reports `warn` with its code only unless the cycle is aborted. Brain-global, right after `fence_repair` in `ALL_PHASES`, classified `writes`. Test: `test/cycle-content-repair.test.ts`.
-- `src/core/cycle/unindexed-files.ts` — the `unindexed_files` maintenance phase (#6865, global, right after `content_repair` through the `REPAIR_LANE_PHASES` dispatch helper): on a managed brain, `runUnindexedFilesPhase(engine, { dryRun, signal?, deadlineAtMs?, now? })` runs one detector pass (`persistence/unindexed-files.ts`) per managed Git source this host owns, least recently scanned first (#7149: no stored result first, then the oldest, so one large source cannot starve the others), under one deadline of min(5 min, a third of the maintenance job's remaining time), each source also stopping at its own budget (`unindexedScanBudgetMs`: 60 s per started 100k live pages); a source the budget stops continues from its stored cursor next run. A real run stores each result and schedules the found files for a re-screen on the next sync (`requestGitHoldRetry`, at most 5,000 per run); a dry run reports without writing. Company-brain sources and sources this host does not own are skipped with a reason; an error on one source is `warn` and the others still run. Details are counts by source and code, never a path; it never runs on the per-sync path. Classified `no_coordinated_write` (`phase-table.ts`). Tests: `test/unindexed-files.test.ts`, `test/unindexed-files-convergence-7149.test.ts`, `test/managed-phase-matrix.test.ts`.
+- `src/core/cycle/unindexed-files.ts` — the `unindexed_files` maintenance phase (#6865, global, right after `content_repair` through the `REPAIR_LANE_PHASES` dispatch helper): on a managed brain, `runUnindexedFilesPhase(engine, { dryRun, signal?, deadlineAtMs?, now? })` runs one detector pass (`persistence/unindexed-files.ts`) per managed Git source this host owns, least recently scanned first (#7149: no stored result first, then the oldest, so one large source cannot starve the others), under one deadline of min(5 min, a third of the maintenance job's remaining time), each source also stopping at its own budget (`unindexedScanBudgetMs`: 60 s per started 100k live pages); a source the budget stops continues from its stored cursor next run. A real run stores each result and schedules the found files for a re-screen on the next sync (`requestGitHoldRetry`, at most 5,000 per run); a dry run reports without writing. Company-brain sources and sources this host does not own are skipped with a reason; an error on one source is `warn` and the others still run, and `details.complete` is true only when no source stopped at its budget or errored (#8887). Details are counts by source and code, never a path; it never runs on the per-sync path. Classified `no_coordinated_write` (`phase-table.ts`). Tests: `test/unindexed-files.test.ts`, `test/unindexed-files-convergence-7149.test.ts`, `test/managed-phase-matrix.test.ts`.
- `src/core/cycle/phase-table.ts` — `MANAGED_PHASE_TABLE` classifies every `ALL_PHASES` entry for managed brains as `writes` (publishes through the coordinator), `no_coordinated_write` (derived projections, side tables, audit-only) or `managed_skip`, each with its reason; `isManagedBrain` is what `runPhaseLint` uses to report issues without rewriting managed canonical files. The managed phase matrix test fails for an unclassified phase.
diff --git a/src/core/cycle/unindexed-files.ts b/src/core/cycle/unindexed-files.ts
index de0e55f3f6..516064e1be 100644
--- a/src/core/cycle/unindexed-files.ts
+++ b/src/core/cycle/unindexed-files.ts
@@ -107,7 +107,7 @@ export async function runUnindexedFilesPhase(engine: BrainEngine | null, opts: U
details: {
mode: opts.dryRun ? 'dry_run' : 'apply', sources: sources.map(({ by_code: _codes, ...source }) => source), scanned: total('scanned'), unindexed: total('unindexed'),
slug_taken: total('slug_taken'), scheduled_now: total('scheduled_now'), already_scheduled: total('already_scheduled'), metafile_skipped: total('metafile_skipped'), by_code: byCode,
- complete: incomplete === 0, time_budget_ms: timeBudgetMs, skipped, errors,
+ complete: incomplete === 0 && errors.length === 0, time_budget_ms: timeBudgetMs, skipped, errors,
...(errors.length ? { fix: { argv: ['gbrain', 'doctor', '--only', 'unindexed_files', '--json'], consent: [], actor: 'agent', requires_exclusive: false,
why: 'Shows each managed Git source\'s unindexed-file state and the next step; read-only.' } } : {}),
},
diff --git a/test/unindexed-files.test.ts b/test/unindexed-files.test.ts
index ea9cabe634..3c0482aec8 100644
--- a/test/unindexed-files.test.ts
+++ b/test/unindexed-files.test.ts
@@ -316,3 +316,14 @@ test('retry-held --unindexed refuses a connector source with invalid_params', ()
await unmanaged(engine, () => engine.executeRaw('DELETE FROM sources WHERE id=$1', [id]));
await expect(runRetryHeld(engine, [id, '--unindexed', '--all'])).rejects.toMatchObject({ code: 'invalid_params', message: 'Unknown option: --all.' });
}), 60_000);
+
+test('#8887: a source whose scan errors leaves the phase incomplete, so the run never reads as a full scan', () => each(async engine => {
+ const s = await source(engine, { 'notes/a.md': note('A') });
+ await s.sync();
+ writeFileSync(join(s.repo, '.git', 'HEAD'), 'not a ref\n');
+ const phase = await runUnindexedFilesPhase(engine, { dryRun: false });
+ expect(phase.status).toBe('warn');
+ expect(phase.details.errors).toEqual([{ source_id: s.id, code: expect.any(String) }]);
+ expect(phase.details.complete).toBe(false);
+}), 240_000);
+