Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

chore: keep cycle.ts and a KEY_FILES page inside their size ratchets

garrytan6f7948ab3e8f
diff --git a/docs/architecture/key-files/commands-2-continued.md b/docs/architecture/key-files/commands-2-continued.md
index 127dc2e88f..b2c2321d0c 100644
--- a/docs/architecture/key-files/commands-2-continued.md
+++ b/docs/architecture/key-files/commands-2-continued.md
@@ -17,7 +17,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/commands/dream-reset-key.ts` — `gbrain dream reset-key <base-key>` persists a breaker reset for one dream key (deaths finished before it stop counting; survives restarts); `gbrain dream reset-key --list [--json]` lists tripped keys with counts and reset commands. Dispatched from `dream.ts` before cycle flag parsing. The `dream_paid_loop` doctor check (`src/commands/doctor/checks/dream-breaker.ts`) warns on keys at the limit through the same counter. Its help names the per-source patterns key `dream:patterns:source:<id>`; doctor `dream_paid_loop` reports that prefix as the key's `key_prefix`.
-- `src/commands/dream.ts` — `gbrain dream` CLI; thin alias over `runCycle`. Flags: `--dry-run`, `--json`, `--phase <name>`, `--pull`, `--dir <path>`, `--input <file>` (ad-hoc transcript, implies `--phase synthesize`), `--date YYYY-MM-DD`, `--from <d> --to <d>` (backfill range), `--unsafe-bypass-dream-guard` (plumbed through `runCycle.synthBypassDreamGuard` → `SynthesizePhaseOpts.bypassDreamGuard` → `discoverTranscripts({bypassGuard})` / `readSingleTranscript({bypassGuard})`; loud stderr warning at synthesize-phase entry; never auto-applied for `--input`). Conflict detection: `--input` + `--date` exits 2. ISO date validation. `--dry-run` runs the scored triage pass but skips synthesis (NOT zero LLM calls). `--help` (and the retriage and reset-key subverb help) prints through `printHelpText`, so `--help --json` is one `{command, help, contract_version}` document (#8510). Exit 1 on status=failed; a `cycle_already_running` skip names the lock holder (pid, host, age) from `report.lock_holder`. `resolveBrainDir` returns `string | null` (order: `--dir` → resolved `--source`'s `local_path` → global `sync.repo_path` → null); a checkout-less postgres/Supabase brain runs DB-only phases (incl. `resolve_symbol_edges`) and skips the 6 filesystem phases with `details.reason: 'no_brain_dir'`; `runDream` owns the only hard error (no checkout AND no engine). When `--source` resolves but has no on-disk checkout, returns null (DB-only) rather than borrowing another source's global `sync.repo_path` (would mix scopes). Pinned by `test/dream-postgres.serial.test.ts`. `--drain [--window <seconds>]` for `--phase extract_atoms`: `runDrain()` bypasses the pack-gate and runs the single-hold bounded drain from `src/core/cycle/extract-atoms-drain.ts` under the same `cycleLockIdFor(sourceId)` the routine cycle uses (concurrent autopilot tick defers with `cycle_already_running`), reporting `{extracted, skipped, remaining, stopped}`. `--window` is a hard deadline for starting work (the item in flight finishes). Every stop maps through `drainOutcome` (`src/core/cycle/extract-atoms-drain-outcome.ts`): exit 0 only for `stopped: drained` with `remaining: 0`; exit 11 (`BUDGET_STOP_EXIT_CODE`) for a retryable stop (`atom_drain_incomplete`: window, deadline, lock, batch cap, budget, a null count; `atom_drain_provider_failure` reasons `rate_limit`/`transient`), printing the rerun command (`gbrain dream --drain --window <s> [--source <id>]`) on stderr and adding `resume_command` under `--json`; exit 1 for a stop a rerun cannot clear (`atom_drain_provider_failure` reasons `auth`/`billing`/`model_not_found`/`content_block`, `atom_drain_no_progress` over a counted backlog), printing the registry suggestion as a `Fix:` line and adding the rendered `fix` instead of `resume_command`. `--json` of any incomplete stop carries `status` (`incomplete` or `provider_failure`, never `ok`), `retryable`, `code` and `reason`; `LockUnavailableError` → `cycle_already_running` skip (also exit 11). Under `--json` (D2) every path is one document: usage errors are `invalid_params` envelopes (exit 2, unknown `--phase` included), a failed or contained cycle under the guard is a `cycle_failed` envelope leading with the CycleReport keys, and `retriage` / `reset-key` refusals are envelopes. The `extract_atoms_backlog` doctor check (`computeExtractAtomsBacklogCheck`) surfaces the silent pack-gated backlog with the exact `--drain` command; pack-gated cycle skips carry a greppable `pack_gated:true` marker. `dream retriage` dispatches on `args[0] === 'retriage'` BEFORE `parseArgs` (its flag set never collides with cycle flags; `dream retriage --help` prints subcommand help engine-free per the same IRON RULE). `--eval-run` opts the process in to `GBRAIN_DECIDE_SLOTS` (`enableDecideEvalOverride`) for eval harnesses; consent, egress and the daily cap still apply.
+- `src/commands/dream.ts` — `gbrain dream` CLI; thin alias over `runCycle`. Flags: `--dry-run`, `--json`, `--phase <name>`, `--pull`, `--dir <path>`, `--input <file>` (ad-hoc transcript, implies `--phase synthesize`), `--date YYYY-MM-DD`, `--from <d> --to <d>` (backfill range), `--unsafe-bypass-dream-guard` (plumbed through `runCycle.synthBypassDreamGuard` → `SynthesizePhaseOpts.bypassDreamGuard` → `discoverTranscripts({bypassGuard})` / `readSingleTranscript({bypassGuard})`; loud stderr warning at synthesize-phase entry; never auto-applied for `--input`). Conflict detection: `--input` + `--date` exits 2. ISO date validation. `--dry-run` runs the scored triage pass but skips synthesis (NOT zero LLM calls). Exit 1 on status=failed; a `cycle_already_running` skip names the lock holder (pid, host, age) from `report.lock_holder`. `resolveBrainDir` returns `string | null` (order: `--dir` → resolved `--source`'s `local_path` → global `sync.repo_path` → null); a checkout-less postgres/Supabase brain runs DB-only phases (incl. `resolve_symbol_edges`) and skips the 6 filesystem phases with `details.reason: 'no_brain_dir'`; `runDream` owns the only hard error (no checkout AND no engine). When `--source` resolves but has no on-disk checkout, returns null (DB-only) rather than borrowing another source's global `sync.repo_path` (would mix scopes). Pinned by `test/dream-postgres.serial.test.ts`. `--drain [--window <seconds>]` for `--phase extract_atoms`: `runDrain()` bypasses the pack-gate and runs the single-hold bounded drain from `src/core/cycle/extract-atoms-drain.ts` under the same `cycleLockIdFor(sourceId)` the routine cycle uses (concurrent autopilot tick defers with `cycle_already_running`), reporting `{extracted, skipped, remaining, stopped}`. `--window` is a hard deadline for starting work (the item in flight finishes). Every stop maps through `drainOutcome` (`src/core/cycle/extract-atoms-drain-outcome.ts`): exit 0 only for `stopped: drained` with `remaining: 0`; exit 11 (`BUDGET_STOP_EXIT_CODE`) for a retryable stop (`atom_drain_incomplete`: window, deadline, lock, batch cap, budget, a null count; `atom_drain_provider_failure` reasons `rate_limit`/`transient`), printing the rerun command (`gbrain dream --drain --window <s> [--source <id>]`) on stderr and adding `resume_command` under `--json`; exit 1 for a stop a rerun cannot clear (`atom_drain_provider_failure` reasons `auth`/`billing`/`model_not_found`/`content_block`, `atom_drain_no_progress` over a counted backlog), printing the registry suggestion as a `Fix:` line and adding the rendered `fix` instead of `resume_command`. `--json` of any incomplete stop carries `status` (`incomplete` or `provider_failure`, never `ok`), `retryable`, `code` and `reason`; `LockUnavailableError` → `cycle_already_running` skip (also exit 11). Under `--json` (D2) every path is one document: usage errors are `invalid_params` envelopes (exit 2, unknown `--phase` included), a failed or contained cycle under the guard is a `cycle_failed` envelope leading with the CycleReport keys, and `retriage` / `reset-key` refusals are envelopes. The `extract_atoms_backlog` doctor check (`computeExtractAtomsBacklogCheck`) surfaces the silent pack-gated backlog with the exact `--drain` command; pack-gated cycle skips carry a greppable `pack_gated:true` marker. `dream retriage` dispatches on `args[0] === 'retriage'` BEFORE `parseArgs` (its flag set never collides with cycle flags; `dream retriage --help` prints subcommand help engine-free per the same IRON RULE). `--eval-run` opts the process in to `GBRAIN_DECIDE_SLOTS` (`enableDecideEvalOverride`) for eval harnesses; consent, egress and the daily cap still apply.
- `src/commands/dream.ts` — `gbrain dream` CLI; thin alias over `runCycle`. Flags: `--dry-run`, `--json`, `--phase <name>`, `--pull`, `--dir <path>`, `--input <file>` (ad-hoc transcript, implies `--phase synthesize`), `--date YYYY-MM-DD`, `--from <d> --to <d>` (backfill range), `--unsafe-bypass-dream-guard` (plumbed through `runCycle.synthBypassDreamGuard` → `SynthesizePhaseOpts.bypassDreamGuard` → `discoverTranscripts({bypassGuard})` / `readSingleTranscript({bypassGuard})`; loud stderr warning at synthesize-phase entry; never auto-applied for `--input`). Conflict detection: `--input` + `--date` exits 2. ISO date validation. `--dry-run` runs the scored triage pass but skips synthesis (NOT zero LLM calls). Exit 1 on status=failed; a `cycle_already_running` skip names the lock holder (pid, host, age) from `report.lock_holder`. Source scope enters the shared 6-tier resolver whenever `--source <id>` is given OR `GBRAIN_SOURCE` is set (a null explicit falls through to tier 2: validated + `assertSourceExists`, so an invalid/unknown env value is a clean exit 1; the `__all__` sentinel is excluded and falls through to the unscoped routing, which already spans every source); an env scope naming the brain's default-like source keeps the full implicit cycle (#4700 semantics), any other keeps the `--source` freshness boundary. `resolveBrainDir` returns `string | null` (order: `--dir` → resolved source's `local_path` → global `sync.repo_path` → null); a checkout-less postgres/Supabase brain runs DB-only phases (incl. `resolve_symbol_edges`) and skips the 6 filesystem phases with `details.reason: 'no_brain_dir'`; `runDream` owns the only hard error (no checkout AND no engine). When `--source` resolves but has no on-disk checkout, returns null (DB-only) rather than borrowing another source's global `sync.repo_path` (would mix scopes). Pinned by `test/dream-postgres.serial.test.ts`. `--drain [--window <seconds>]` for `--phase extract_atoms`: `runDrain()` bypasses the pack-gate and runs the single-hold bounded drain from `src/core/cycle/extract-atoms-drain.ts` under the same `cycleLockIdFor(sourceId)` the routine cycle uses (concurrent autopilot tick defers with `cycle_already_running`), reporting `{extracted, skipped, remaining, stopped}`. `--window` is a hard deadline for starting work (the item in flight finishes). Every stop maps through `drainOutcome` (`src/core/cycle/extract-atoms-drain-outcome.ts`): exit 0 only for `stopped: drained` with `remaining: 0`; exit 11 (`BUDGET_STOP_EXIT_CODE`) for a retryable stop (`atom_drain_incomplete`: window, deadline, lock, batch cap, budget, a null count; `atom_drain_provider_failure` reasons `rate_limit`/`transient`), printing the rerun command (`gbrain dream --drain --window <s> [--source <id>]`) on stderr and adding `resume_command` under `--json`; exit 1 for a stop a rerun cannot clear (`atom_drain_provider_failure` reasons `auth`/`billing`/`model_not_found`/`content_block`, `atom_drain_no_progress` over a counted backlog), printing the registry suggestion as a `Fix:` line and adding the rendered `fix` instead of `resume_command`. `--json` of any incomplete stop carries `status` (`incomplete` or `provider_failure`, never `ok`), `retryable`, `code` and `reason`; `LockUnavailableError` → `cycle_already_running` skip (also exit 11). Under `--json` (D2) every path is one document: usage errors are `invalid_params` envelopes (exit 2, unknown `--phase` included), a failed or contained cycle under the guard is a `cycle_failed` envelope leading with the CycleReport keys, and `retriage` / `reset-key` refusals are envelopes. The `extract_atoms_backlog` doctor check (`computeExtractAtomsBacklogCheck`) surfaces the silent pack-gated backlog with the exact `--drain` command; pack-gated cycle skips carry a greppable `pack_gated:true` marker. `dream retriage` dispatches on `args[0] === 'retriage'` BEFORE `parseArgs` (its flag set never collides with cycle flags; `dream retriage --help` prints subcommand help engine-free per the same IRON RULE). `--eval-run` opts the process in to `GBRAIN_DECIDE_SLOTS` (`enableDecideEvalOverride`) for eval harnesses; consent, egress and the daily cap still apply.
diff --git a/src/core/cycle.ts b/src/core/cycle.ts
index d9a7d70f28..e3d6d56f30 100644
--- a/src/core/cycle.ts
+++ b/src/core/cycle.ts
@@ -2622,9 +2622,7 @@ async function runCycleUnscoped(
phaseResults.push(scSkip);
} else {
progress.start('cycle.synthesize_concepts');
- const { runPhaseSynthesizeConcepts } = await import('./cycle/synthesize-concepts.ts');
- // #7986: same as extract_atoms (#5833): a timeout or lock steal stops the phase before its next concept.
- const scSignal = cycleSignal ? anyAbortSignal([cycleSignal]) : null;
+ const { runPhaseSynthesizeConcepts } = await import('./cycle/synthesize-concepts.ts'), scSignal = cycleSignal ? anyAbortSignal([cycleSignal]) : null; // #7986: as extract_atoms
const { result, duration_ms } = await racedTimePhase(() => runPhaseSynthesizeConcepts(engine, {
brainDir: brainDir ?? undefined,
// #4416: thread the cycle's resolved source into the phase's page/
@@ -2636,8 +2634,7 @@ async function runCycleUnscoped(
// v0.41.19.0 (T3): closure refreshes cycle lock + fires outer hook.
yieldDuringPhase: buildYieldDuringPhase(lock, opts.yieldDuringPhase, onStolen),
// v0.41.19.0 (T4): pass same reporter (not a child).
- progress,
- signal: scSignal?.signal,
+ progress, signal: scSignal?.signal,
}), 'synthesize_concepts').finally(() => scSignal?.dispose());
result.duration_ms = duration_ms;
phaseResults.push(result);