Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* gbrain dream — run one brain maintenance cycle.
*
* The README brand promise: "the agent runs while I sleep, the dream
* cycle ... I wake up and the brain is smarter." Cron-friendly, JSON
* report, phase-selectable.
*
* Thin alias over runCycle (src/core/cycle.ts). Both this command and
* `gbrain autopilot` converge on the same primitive so there's one
* source of truth for what "overnight maintenance" means.
*
* Usage:
* gbrain dream # full 6-phase cycle
* gbrain dream --dry-run # preview, no writes
* gbrain dream --json # CycleReport JSON (for agents)
* gbrain dream --phase lint # run a single phase
* gbrain dream --pull # also git pull the brain repo
* gbrain dream --dir /path/to/brain # explicit brain location
*
* Cron: 0 2 * * * gbrain dream --json >> /var/log/gbrain-dream.log
*
* Related: `gbrain autopilot --install` for continuous daemonized
* maintenance. dream is the one-shot, autopilot is the scheduler.
*/
import type { BrainEngine } from '../core/engine.ts';
import {
runCycle,
resolveSourceForDir,
ALL_PHASES,
type CyclePhase,
type CycleReport,
} from '../core/cycle.ts';
import { ALL_SOURCES, isResolverUserError, resolveImplicitDefaultSourceId, resolveSourceId } from '../core/source-resolver.ts';
import { jsonGuardActive, jsonRequested, setCliExitVerdict, writeJsonDocument } from '../core/cli-force-exit.ts';
import { BUDGET_STOP_EXIT_CODE } from '../core/exit-codes.ts';
import { opError, type OperationError } from '../core/ops/contract.ts';
import { usageError, writeCliError, writeCliRefusal } from '../cli/cli-error.ts';
import { printHelpText } from '../cli/help/render.ts';
import { cliRenderContext, renderAction, shellQuote, type Action } from '../core/agent-output.ts';
import { codeEntry } from '../core/error-catalogue.ts';
import { fetchSource } from '../core/sources-load.ts';
import { existsSync } from 'fs';
import { isAbsolute, resolve } from 'node:path';
interface DreamArgs {
json: boolean;
dryRun: boolean;
pull: boolean;
/**
* #4493: every explicitly-named (or --input/--drain-implied) phase, order
* preserved, deduped. Empty = full/default cycle. Previously a single
* `phase` scalar read from the FIRST --phase flag, so repeats were
* silently dropped.
*/
phases: CyclePhase[];
dir: string | null;
help: boolean;
/** v0.21: ad-hoc transcript file path; implies --phase synthesize. */
inputFile: string | null;
/** v0.21: restrict synthesize to a single date (YYYY-MM-DD). */
date: string | null;
/** v0.21: backfill range start (YYYY-MM-DD). */
from: string | null;
/** v0.21: backfill range end (YYYY-MM-DD). */
to: string | null;
/**
* v0.23.2: disable the synthesize phase's self-consumption guard.
* Long-form flag name to discourage casual use; loud stderr warning fires when set.
* Never auto-applied for --input (codex finding #3).
*/
bypassDreamGuard: boolean;
/**
* v0.41.13: per-source cycle scoping. Threaded into runCycle as
* `sourceId` so `cycle.ts:1947-1967` writes `last_full_cycle_at`
* to `sources.config` on success — without it, `gbrain doctor`'s
* `cycle_freshness` check stays stale forever. Accepts `--source
* <id>` and the alias `--source-id <id>` (the v0.37.7.0 #1167
* canonical name across import/extract/graph-query); both work
* until a follow-up CLI cleanup picks one. Supersedes PR #1559.
*/
source: string | null;
/**
* issue #1678: bounded single-hold backlog drain. `--drain` (currently only
* for `--phase extract_atoms`) holds the cycle lock once and loops bounded
* batches, rediscovering eligibility each batch, until the backlog empties or
* `--window` seconds elapse. Reports {extracted, skipped, remaining}; exits
* 3 unless it drained so a cron/agent loop knows to run again.
*/
drain: boolean;
/** Drain window in seconds, a hard deadline for starting work. Default 300 (5 min). */
windowSeconds: number;
/**
* issue #2860 — `--once`. One-shot bypass of the named `--phase`'s own
* `dream.<phase>.enabled` / `cycle.<phase>.enabled` config gate, for this
* invocation only. Never reads or writes the `.enabled` key — unlike the
* old "toggle enabled true, run, toggle back to false" workaround, a crash
* mid-run can't leave any global state stuck. (Phases may still write
* their own completion stamps, e.g. patterns' `last_evidence_ts` per
* #4879, so a forced run isn't re-paid by the next tick.) Requires an explicit
* `--phase <name>`; bare `--once` is a usage error (there'd be no single
* phase to target). Applies only to phases with a config `.enabled` gate
* (patterns, synthesize, conversation_facts_backfill, enrich_thin,
* skillopt, drift) — a no-op for phases that always run when named directly.
*/
once: boolean;
}
const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
const DEFAULT_DRAIN_WINDOW_SECONDS = 300;
/** Exit code for "drain ran but the backlog isn't empty — run again" (A3: a resumable stop, never 3). */
const EXIT_DRAIN_INCOMPLETE = BUDGET_STOP_EXIT_CODE;
/** D2: the human stderr line (unchanged) plus, under --json, the envelope as the document; then exit. */
function dreamExit(e: OperationError, json = jsonRequested(process.argv.slice(2))): never {
process.exit(writeCliRefusal(e, 'dream', { json }));
}
function sourceError(e: Error): OperationError {
return opError('unknown_source', e.message, 'Run `gbrain sources list` for the registered source ids, then pass one with --source.');
}
/**
* Collect every occurrence of `--<flag> <value>` in argv. Used to
* detect repeated flags with different values (e.g.
* `--source X --source Y`) and to surface a clean usage error
* instead of silently last-wins. Repeated identical values are
* collapsed to one (no-op). Missing values (flag at end of argv)
* return null to let the caller raise an explicit usage error
* rather than fall through with `undefined`.
*/
function collectFlagValues(args: string[], flag: string): string[] | null {
const values: string[] = [];
for (let i = 0; i < args.length; i++) {
if (args[i] !== flag) continue;
const v = args[i + 1];
if (v === undefined) return null; // flag at end of argv
values.push(v);
}
return values;
}
function parseArgs(args: string[]): DreamArgs {
// #4493: collect EVERY --phase occurrence. `args.indexOf('--phase')` used
// to read only the FIRST flag, so `--phase a --phase b --phase c` silently
// ran phase a alone and exited 0 with a report covering one phase. Each
// value is validated, order is preserved, repeats of the same value
// collapse (same contract as the repeated --source handling below).
const json = jsonRequested(args);
const phaseValues = collectFlagValues(args, '--phase');
if (phaseValues === null) {
dreamExit(usageError('--phase <name>: missing value. Usage: gbrain dream --phase <name>', 'Example: gbrain dream --phase lint'), json);
}
// issue #2860 (Codex P3): captured BEFORE --input/--drain get a chance to
// implicitly default `phases` below, so --once's validation can require
// the user actually TYPED --phase, not merely that some phase ended up
// resolved. Without this, `--input <f> --once` and `--drain --once`
// slip past the "explicit --phase required" contract (the derived
// phase value is already non-null by the time that check runs) and
// --once becomes silently ineffective for both.
const phaseWasExplicit = phaseValues.length > 0;
let phases: CyclePhase[] = [];
for (const rawPhase of phaseValues) {
if (rawPhase === 'auto_think') {
dreamExit(usageError('The auto_think phase is replaced by pinned questions: dream.auto_think.questions became pins (inactive when auto_think was off).',
'Run gbrain dream --phase standing_questions to refresh due pins; gbrain questions list shows them.'), json);
}
if (!(ALL_PHASES as string[]).includes(rawPhase)) {
dreamExit(usageError(`Unknown phase "${rawPhase}". Valid: ${ALL_PHASES.join(', ')}`, 'Example: gbrain dream --phase lint'), json);
}
if (!phases.includes(rawPhase as CyclePhase)) phases.push(rawPhase as CyclePhase);
}
const dirIdx = args.indexOf('--dir');
const dir = dirIdx !== -1 ? args[dirIdx + 1] : null;
const inputIdx = args.indexOf('--input');
const inputFile = inputIdx !== -1 ? args[inputIdx + 1] ?? null : null;
const dateIdx = args.indexOf('--date');
const date = dateIdx !== -1 ? args[dateIdx + 1] ?? null : null;
if (date && !ISO_DATE_RE.test(date)) {
dreamExit(usageError(`--date must be YYYY-MM-DD; got "${date}"`, 'Example: gbrain dream --phase synthesize --date 2026-01-31'), json);
}
const fromIdx = args.indexOf('--from');
const from = fromIdx !== -1 ? args[fromIdx + 1] ?? null : null;
if (from && !ISO_DATE_RE.test(from)) {
dreamExit(usageError(`--from must be YYYY-MM-DD; got "${from}"`, 'Example: gbrain dream --phase synthesize --from 2026-01-01 --to 2026-01-31'), json);
}
const toIdx = args.indexOf('--to');
const to = toIdx !== -1 ? args[toIdx + 1] ?? null : null;
if (to && !ISO_DATE_RE.test(to)) {
dreamExit(usageError(`--to must be YYYY-MM-DD; got "${to}"`, 'Example: gbrain dream --phase synthesize --from 2026-01-01 --to 2026-01-31'), json);
}
if (from && to && from > to) {
dreamExit(usageError(`--from (${from}) is after --to (${to}); empty range`, 'Pass --from on or before --to.'), json);
}
// --input + --date / --from / --to is incoherent: --input is a single
// file, the date filters scan a directory.
if (inputFile && (date || from || to)) {
dreamExit(usageError('--input cannot be combined with --date / --from / --to', 'Use --input <file> alone, or the date filters alone.'), json);
}
// --input implies --phase synthesize.
if (inputFile && phases.length === 0) phases = ['synthesize'];
// v0.41.13: --source <id> (and the --source-id alias) drives per-source
// cycle scoping. Resolution rules:
// - missing value (flag at end of argv) → exit 2 with usage
// - repeated with different values (e.g. --source X --source Y) → exit 2
// - --source X --source-id Y (conflicting flag aliases) → exit 2
// - --source X --source X (or --source-id repeated with same value) → accepted
// - --help short-circuits BEFORE this block fires (see runDream).
// Closes the PR #1559 silent-no-op class through a clean argv contract.
const sourceValues = collectFlagValues(args, '--source');
const sourceIdValues = collectFlagValues(args, '--source-id');
if (sourceValues === null) {
dreamExit(usageError('--source <id>: missing value. Usage: gbrain dream --source <source-id>', 'Example: gbrain dream --source default'), json);
}
if (sourceIdValues === null) {
dreamExit(usageError('--source-id <id>: missing value. Usage: gbrain dream --source-id <source-id>', 'Example: gbrain dream --source-id default'), json);
}
const uniqSource = Array.from(new Set(sourceValues));
const uniqSourceId = Array.from(new Set(sourceIdValues));
if (uniqSource.length > 1) {
dreamExit(usageError(`specify --source once; got [${uniqSource.map(v => `"${v}"`).join(', ')}]`, 'Run one dream per source: gbrain dream --source <id>.'), json);
}
if (uniqSourceId.length > 1) {
dreamExit(usageError(`specify --source-id once; got [${uniqSourceId.map(v => `"${v}"`).join(', ')}]`, 'Run one dream per source: gbrain dream --source <id>.'), json);
}
if (uniqSource.length === 1 && uniqSourceId.length === 1 && uniqSource[0] !== uniqSourceId[0]) {
dreamExit(usageError(
`use --source OR --source-id, not both (different values): ` +
`--source="${uniqSource[0]}" vs --source-id="${uniqSourceId[0]}"`,
'Pass one of --source / --source-id.'), json);
}
const source = uniqSource[0] ?? uniqSourceId[0] ?? null;
// issue #1678: --drain [--window <seconds>]. Only extract_atoms is drainable
// this wave (it has a real eligibility predicate; synthesize_concepts does
// not — Codex #12). --drain with no --phase defaults to extract_atoms.
const drain = args.includes('--drain');
const windowIdx = args.indexOf('--window');
let windowSeconds = DEFAULT_DRAIN_WINDOW_SECONDS;
if (windowIdx !== -1) {
const raw = args[windowIdx + 1];
if (raw === undefined || !/^\d+$/.test(raw.trim()) || parseInt(raw, 10) <= 0) {
dreamExit(usageError(`--window must be a positive integer (seconds); got "${raw}"`, 'Example: gbrain dream --drain --window 300'), json);
}
windowSeconds = parseInt(raw, 10);
}
if (drain) {
if (phases.length === 0) phases = ['extract_atoms'];
else if (phases.length > 1 || phases[0] !== 'extract_atoms') {
dreamExit(usageError(`--drain currently supports only --phase extract_atoms (got "${phases.join(', ')}")`, 'Example: gbrain dream --drain --phase extract_atoms'), json);
}
}
// issue #2860: --once requires an EXPLICIT single --phase target (typed
// by the user, not merely implied by --input/--drain — see
// `phaseWasExplicit` above). Bare `--once` (full/default cycle) has no
// single phase to bypass the gate for, and force-enabling EVERY
// currently-disabled phase at once would be exactly the kind of
// surprise-spend risk the flag exists to prevent. An implicit phase
// (from --input or --drain) is rejected too: --drain returns before
// onceForPhase is ever read, and --input already bypasses the
// synthesize gate on its own, so --once would silently do nothing in
// either case — reject loudly instead of pretending it worked (Codex
// review finding).
//
// Codex review finding: `--help` must short-circuit BEFORE this exits(2),
// matching the "IRON RULE" pinned by test/dream.test.ts's
// "--help --source whatever prints help and exits 0" case — `gbrain
// dream --help --once` (no --phase) must show help, not a usage error.
const once = args.includes('--once');
const wantsHelp = args.includes('--help') || args.includes('-h');
if (once && !phaseWasExplicit && !wantsHelp) {
dreamExit(usageError(
'--once requires an explicit --phase <name> (bypasses that one ' +
'phase\'s dream.<phase>.enabled / cycle.<phase>.enabled gate for ' +
'this run only; never touches config). A phase implied by --input ' +
'or --drain does not count — --once would silently do nothing for ' +
'those. Usage: gbrain dream --phase <name> --once',
'Example: gbrain dream --phase synthesize --once'), json);
}
// #4493 corollary: --once bypasses ONE phase's enabled gate; with several
// named phases there is no single target, and force-enabling them all at
// once is the surprise-spend risk #2860 exists to prevent.
if (once && phases.length > 1 && !wantsHelp) {
dreamExit(usageError(
`--once supports a single --phase target; got [${phases.join(', ')}]. ` +
'Run each phase in its own --phase <name> --once invocation.',
'Example: gbrain dream --phase synthesize --once'), json);
}
return {
json,
dryRun: args.includes('--dry-run'),
pull: args.includes('--pull'),
phases,
dir,
help: args.includes('--help') || args.includes('-h'),
inputFile,
date,
from,
to,
bypassDreamGuard: args.includes('--unsafe-bypass-dream-guard'),
source,
drain,
windowSeconds,
once,
};
}
/**
* Resolve the brain directory without the `findRepoRoot` footgun.
*
* Resolution order (v0.41.30 — postgres support):
* 1. An explicit --dir argument (exits 1 if it doesn't exist — a real mistake).
* 2. T1: when --source resolved to a source that has an on-disk `local_path`,
* use it (matches `gbrain sync`, lets that source's filesystem phases run).
* 3. The legacy `sync.repo_path` config key (pre-v0.18 default-source brains).
* 4. `null` — no local checkout. The cycle then SKIPS filesystem phases
* (lint/backlinks/sync/synthesize/extract/patterns) with reason
* `no_brain_dir` and runs the DB-only phases (resolve_symbol_edges, embed,
* orphans, ...). This is what makes `gbrain dream` work on a postgres /
* Supabase brain with no checkout. `runDream` owns the only hard error:
* no checkout AND no engine = truly nothing to run.
*
* Still never walks cwd for a `.git` — only the explicit / source / config
* signals are trusted.
*/
async function resolveBrainDir(
engine: BrainEngine | null,
explicit: string | null,
resolvedSourceId?: string,
): Promise<string | null> {
if (explicit) {
if (!existsSync(explicit)) {
dreamExit(opError('not_found', `--dir path does not exist: ${explicit}`, 'Pass an existing brain directory to --dir, or omit it to use the configured source.'));
}
// Resolve to absolute so downstream writeFileSync(join(brainDir, slug))
// can't silently land at cwd when explicit is `.` / `./brain` / etc.
return resolve(explicit);
}
// T1: the user scoped to a specific source via --source/--source-id; if that
// source has a checkout on disk, use it so its filesystem phases can run.
if (engine && resolvedSourceId) {
const src = await fetchSource(engine, resolvedSourceId);
if (src?.local_path && isAbsolute(src.local_path) && existsSync(src.local_path)) {
return resolve(src.local_path);
}
// Explicit --source whose checkout isn't on disk → DB-only (skip FS phases).
// Do NOT fall through to the global sync.repo_path below: that path belongs
// to the default/unscoped brain, and running FS phases (sync/lint/extract)
// against it while the DB phases AND the last_full_cycle_at stamp target
// <resolvedSourceId> would mix scopes — syncing one source's checkout while
// marking a different source fresh. (codex P1 review finding.)
return null;
}
if (engine) {
const configured = await engine.getConfig('sync.repo_path');
// #7630: a relative stored path names whatever directory gbrain runs from, so it is no checkout.
if (configured && isAbsolute(configured) && existsSync(configured)) {
return resolve(configured);
}
}
// No checkout found. Return null (NOT exit) — DB-only phases can still run
// against the engine. The both-null hard error lives in runDream.
return null;
}
function printHelp(args: string[]): Promise<void> {
return printHelpText('dream', `Usage: gbrain dream [options]
gbrain dream retriage [flags] (see: gbrain dream retriage --help)
gbrain dream reset-key <key> | --list (see: gbrain dream reset-key --help)
Run one brain maintenance cycle. Eight phases:
lint -> backlinks -> sync -> synthesize -> extract -> patterns -> embed -> orphans
The synthesize + patterns phases (v0.21) consolidate yesterday's
conversation transcripts into reflections, originals, and cross-session
pattern pages. Designed for cron (exits when done).
The synthesize phase (#4152) runs a two-stage cascade: a cheap scored triage
(model: models.dream.triage, gate: dream.triage.threshold, default 0.5) gates
the expensive per-transcript synthesis subagents (turn budget:
dream.synthesize.max_turns, default 16). Retune the threshold any time —
scores are cached, so re-gating costs zero new LLM calls. \`dream retriage\`
re-scores the corpus and reconciles the queued synthesis backlog.
Options:
--dry-run Preview all fixes without writing. Note: synthesize
runs the cheap scored triage pass (caches verdicts),
but skips the synthesis subagents; propose_takes,
grade_takes and calibration_profile are skipped.
"--dry-run" does NOT mean "zero LLM calls."
--json Emit the CycleReport as JSON (agent-readable)
--phase <name> Run only the named phase(s). Repeatable — every named
phase runs, in canonical cycle order (#4493).
Valid: ${ALL_PHASES.join(' | ')}
--once With --phase <name>: run that phase once even if its
own dream.<phase>.enabled / cycle.<phase>.enabled
config gate is false. Never reads or writes config —
unlike toggling the flag on/off around the run, a
crash mid-invocation can't leave it stuck. Applies to
patterns, synthesize, conversation_facts_backfill,
enrich_thin, skillopt, drift, lint, consolidate; no-op
on phases with no such gate. Requires an EXPLICIT
--phase <name> — a phase implied by --input or
--drain does not count (bare
--once, or --once with --input/--drain and no
explicit --phase, is a usage error).
--eval-run Eval harness run: honor GBRAIN_DECIDE_SLOTS (e.g. triage=on)
for System One slots in this process; consent keys, the
egress gate and the daily cap still apply
--pull git pull the brain repo before syncing (default: no pull)
--dir <path> Brain directory (default: configured brain). On a
postgres/remote brain with no local checkout, the
filesystem phases (lint, backlinks, sync, synthesize,
extract, patterns) are skipped (reason: no_brain_dir)
and the DB-only phases still run.
--source <id> Scope the cycle to one source so doctor's
cycle_freshness check sees a fresh stamp on
completion. When omitted, gbrain derives the
source from --dir / the configured checkout
when it matches a source's local_path (#1869),
or from the default-like source selected by
sources.default / sole-non-default routing.
A named non-default source runs the deterministic
freshness phases unless --phase is given
(explicit phases are honored verbatim). A bare
no --source dream against the default-like source,
and --source default, still run the full cycle.
GBRAIN_SOURCE=<id> is equivalent when --source is
omitted.
--source-id <id> Alias for --source. Matches the v0.37.7.0+
naming used by import/extract/graph-query.
--input <file> Synthesize a specific transcript file (implies
--phase synthesize). Bypasses corpus-dir scan.
--date YYYY-MM-DD Synthesize transcripts dated for one specific day.
--from YYYY-MM-DD Backfill range start (use with --to).
--to YYYY-MM-DD Backfill range end.
--drain Bounded backlog drain for --phase extract_atoms
(the default phase when --drain is set). Holds the
cycle lock once, processes batches until the backlog
empties or --window elapses, reports {extracted,
remaining, stopped}. Exits 0 when the backlog drained;
11 when running again can continue (window, budget,
batch cap, deadline, lock, an unknown count, a rate
limit or transient provider failure), printing the
rerun command; 1 when it cannot until something
changes (provider auth, billing, unknown model or
content block; no_progress), printing the fix. --json
adds status, retryable and code. Use this to grind down an
extract_atoms backlog on a brain whose pack doesn't
run the phase in the routine cycle.
--window <seconds> Drain window, a hard deadline: no page or transcript
starts after it and the one in flight finishes, so a
run ends within one item of the window. Default 300.
--unsafe-bypass-dream-guard
Disable the self-consumption guard. Use only when you
know the input file is NOT dream-cycle output but the
guard is firing. Loud stderr warning + cost reminder
fires every run.
--help, -h Show this help
Examples:
gbrain dream
gbrain dream --dry-run --json
gbrain dream --phase lint
gbrain dream --phase patterns --once # run once, ignore dream.patterns.enabled=false
gbrain dream --phase synthesize --input ~/transcripts/2026-04-25.txt
gbrain dream --phase synthesize --from 2026-04-01 --to 2026-04-25
0 2 * * * gbrain dream --json # nightly via cron
Configure synthesize:
gbrain config set dream.synthesize.session_corpus_dir /path/to/transcripts
gbrain config set cycle.timezone Asia/Kolkata # optional; defaults to host timezone
Related:
gbrain autopilot --install # continuous maintenance as a daemon
gbrain autopilot # same maintenance cycle, scheduled
`, args);
}
// ─── Human-friendly report printing ────────────────────────────────
function printHuman(report: CycleReport) {
if (report.status === 'skipped') {
if (report.reason === 'cycle_already_running') {
const h = report.lock_holder;
console.log(`Skipped: another cycle is already running. (locked${h ? ` by pid ${h.holder_pid} on ${h.holder_host} for ${Math.round(h.age_ms / 1000)}s` : ''})`);
} else if (report.reason === 'no_database') {
console.log(`Skipped: no database available.`);
} else {
console.log(`Skipped: ${report.reason ?? 'unknown reason'}.`);
}
return;
}
if (report.status === 'clean') {
// A 'clean' cycle can still carry a skip reason worth surfacing — e.g.
// synthesize's D8 legacy-key / D5 oversize-chunk skips leave
// transcripts_processed/synth_pages_written at 0 (so deriveStatus sees
// no activity) while `details.skips` names exactly why each transcript
// was passed over. Without this, `--input <already-handled-file>`
// prints only "Brain is healthy" with no indication anything was
// examined and skipped.
const skipLines: string[] = [];
for (const p of report.phases) {
const skips = (p.details as { skips?: Array<{ filePath: string; reason: string }> } | undefined)?.skips;
if (Array.isArray(skips)) {
for (const s of skips) {
skipLines.push(` - ${p.phase}: ${s.filePath} (${s.reason})`);
}
}
}
console.log(
`Brain is healthy. ${report.phases.length} phase(s) checked in ${(report.duration_ms / 1000).toFixed(1)}s.`,
);
if (skipLines.length > 0) {
console.log('Skipped:');
for (const line of skipLines) console.log(line);
}
return;
}
console.log(`Dream cycle (${report.status}) in ${(report.duration_ms / 1000).toFixed(1)}s:`);
for (const p of report.phases) {
const icon =
p.status === 'ok' ? '✓' :
p.status === 'warn' ? '!' :
p.status === 'skipped' ? '-' : '✗';
const line = ` ${icon} ${p.phase.padEnd(10)} ${p.summary}`;
console.log(line);
const details = p.details as Record<string, unknown> | undefined;
const failures = Array.isArray(details?.failures) ? details.failures : [];
if (failures.length > 0) {
for (const f of failures) {
// sync failures carry `source`; synthesize_concepts failures carry
// `concept` — name whichever is present so a concept-synthesis
// failure isn't printed as an anonymous '?'.
const { source, concept, error } = f as { source?: string; concept?: string; error?: string };
console.log(` ✗ ${source ?? concept ?? '?'}: ${error ?? 'unknown error'}`);
}
}
if (p.error) {
const hint = p.error.hint ? ` (${p.error.hint})` : '';
console.log(` [${p.error.class}/${p.error.code}] ${p.error.message}${hint}`);
}
}
const t = report.totals;
const hasTotals =
t.lint_fixes > 0 || t.backlinks_added > 0 || t.pages_synced > 0 ||
t.pages_extracted > 0 || t.pages_embedded > 0 || t.orphans_found > 0 ||
t.transcripts_processed > 0 || t.synth_pages_written > 0 || t.patterns_written > 0;
if (hasTotals) {
console.log(
` totals: lint=${t.lint_fixes} backlinks=${t.backlinks_added} synced=${t.pages_synced} ` +
`extracted=${t.pages_extracted} embedded=${t.pages_embedded} orphans=${t.orphans_found} ` +
`synth_transcripts=${t.transcripts_processed} synth_pages=${t.synth_pages_written} ` +
`patterns=${t.patterns_written}`,
);
}
}
// ── Test-only export ───────────────────────────────────────
// `__testing` re-exports otherwise-private helpers so unit tests can pin
// CLI output behavior without spawning a subprocess. Not part of the
// runtime contract.
export const __testing = {
printHuman,
};
// ─── CLI entry ─────────────────────────────────────────────────────
// The resolver's user-facing throws (unknown/archived source, invalid --source
// / GBRAIN_SOURCE value) surface as a clean stderr line + exit 1 via the shared
// `isResolverUserError` predicate (source-resolver.ts, next to the messages it
// matches). Anything else — TypeError / connection failures / genuine bugs —
// is intentionally NOT caught and propagates with a stack trace so programmer
// bugs are never hidden as operator errors. (Plan D-T3, codex C-7.)
/**
* issue #1678 — bounded single-hold extract_atoms drain (see DreamArgs.drain).
* Holds the cycle lock once (same id the routine cycle uses for this source),
* loops bounded batches rediscovering eligibility, reports remaining, exits
* EXIT_DRAIN_INCOMPLETE when the backlog isn't empty so a loop knows to retry.
*/
async function runDrain(
engine: BrainEngine,
opts: DreamArgs,
resolvedSourceId: string | undefined,
brainDir: string | null,
): Promise<void> {
const { LockUnavailableError } = await import('../core/db-lock.ts');
const { countExtractAtomsBacklog } = await import('../core/cycle/extract-atoms.ts');
const { runExtractAtomsDrainForSource } = await import('../core/cycle/extract-atoms-drain.ts');
const extractionSourceId = resolvedSourceId ?? 'default';
// Dry-run: preview the backlog without holding the lock or extracting.
if (opts.dryRun) {
const remaining = await countExtractAtomsBacklog(engine, extractionSourceId);
if (opts.json) {
await writeJsonDocument(JSON.stringify({ phase: 'extract_atoms', status: 'ok', dry_run: true, extracted: 0, skipped: 0, remaining, batches: 0, stopped: 'window', failure_count: 0, failures: [], omitted_failure_count: 0, last_error: null, resume_command: drainCommand(opts) }, null, 2));
} else {
console.log(`[drain] dry-run: ${remaining ?? '?'} page(s) eligible for atom extraction (no work done)`);
}
// null = the backlog count query FAILED — treat as incomplete, never as
// "drained" (Codex: `remaining ?? 0` would exit 0 on a failed count and
// make automation believe the backlog cleared when it was never verified).
if (remaining === null || remaining > 0) process.exit(EXIT_DRAIN_INCOMPLETE);
return;
}
let result;
try {
// DECISION 5A: the lock/batch/count wiring lives in the shared helper so
// the CLI path, the Minion handler, and autopilot's auto-drain can't drift.
result = await runExtractAtomsDrainForSource(engine, {
sourceId: resolvedSourceId,
windowSeconds: opts.windowSeconds,
brainDir: brainDir ?? undefined,
onBatch: opts.json ? undefined : ({ batch, extracted, remaining }) => {
process.stderr.write(`[drain] batch ${batch}: +${extracted} atom(s), ~${remaining ?? '?'} remaining\n`);
},
});
} catch (e) {
if (e instanceof LockUnavailableError) {
if (opts.json) {
await writeJsonDocument(JSON.stringify({ phase: 'extract_atoms', status: 'skipped', reason: 'cycle_already_running', resume_command: drainCommand(opts) }, null, 2));
} else {
console.log('[drain] skipped: another cycle holds the lock (cycle_already_running) — run again shortly');
}
process.exit(EXIT_DRAIN_INCOMPLETE);
}
throw e;
}
// #4539: surface WHY the drain underperformed. Pre-fix the phase's
// failures[] was collapsed to bare counts inside the drain adapter, so a
// run that failed on every item printed only `stopped: no_progress` and the
// operator had to re-run the phase by hand to see the provider/parse error.
// Stderr (not stdout): progress/diagnostics never pollute the data stream.
if (result.failure_count > 0) {
// #4730: the bounded per-item records ride the --json payload; the human
// stderr line reports the totals (and any cap overflow) so nothing is
// silently dropped in either mode.
const omitted = result.omitted_failure_count > 0
? ` (${result.failures.length} detailed, ${result.omitted_failure_count} beyond the record cap)`
: '';
process.stderr.write(
`[drain] ${result.failure_count} item failure(s)${omitted}${result.last_error ? `; last error: ${result.last_error}` : ''}\n`,
);
}
// #6503: cut items are not failures and not complete; say so once per drain.
if ((result.input_truncated ?? 0) > 0) {
process.stderr.write(
`[drain] ${result.input_truncated} item(s) cut at cycle.extract_atoms.max_input_chars: the model did not read their tail; ` +
'head atoms are kept, the items are not marked complete and are skipped until the cap rises (gbrain config set cycle.extract_atoms.max_input_chars <n>)\n',
);
}
const { drainBudgetNotice, usd } = await import('../core/cycle/extract-atoms-budget-notice.ts');
const { drainOutcome } = await import('../core/cycle/extract-atoms-drain-outcome.ts');
// #6817: one stop → exit/status/retryable mapping, shared with the Minion handler.
const outcome = drainOutcome(result);
const budgetNotice = result.stopped === 'budget' ? drainBudgetNotice(result) : null;
const fix = outcome.retryable || !outcome.code ? undefined : codeEntry(outcome.code)?.fix;
if (opts.json) {
await writeJsonDocument(JSON.stringify(outcome.status === 'ok' ? result : {
...result, status: outcome.status, retryable: outcome.retryable, code: outcome.code,
...(outcome.reason ? { reason: outcome.reason } : {}),
...(outcome.retryable ? { resume_command: drainCommand(opts) } : {}),
...(fix ? { fix: renderAction(fix, cliRenderContext()) } : {}),
...(budgetNotice ? { notices: [budgetNotice] } : {}) }, null, 2));
} else {
console.log(`[drain] extracted ${result.extracted} atom(s) across ${result.batches} batch(es); ${result.remaining ?? '?'} remaining (stopped: ${result.stopped})`);
}
// null remaining = the final count query failed; do not report success.
if (outcome.status === 'ok') return;
const stop = `[drain] stopped: ${result.stopped}${outcome.status === 'provider_failure' ? ` (${outcome.reason})` : ''}; ${result.remaining ?? '?'} page(s) remaining.`;
process.stderr.write(budgetNotice
? `[drain] stopped: budget; spent ${usd(result.spent_usd)} of the ${usd(result.budget_usd)} per-run cap (cycle.extract_atoms.budget_usd); ` +
`${result.remaining ?? '?'} page(s) remaining. Rerun: ${drainCommand(opts)}, or raise the cap: gbrain config set cycle.extract_atoms.budget_usd <usd>\n`
: outcome.retryable
? `${stop} Rerun: ${drainCommand(opts)}\n`
: `${stop} Fix: ${nonRetryableFixLine(outcome.code!, fix!)}\n`,
);
process.exit(outcome.exit);
}
/** The registry suggestion for a non-retryable drain stop, plus its read-only check when the prose does not already name it. */
function nonRetryableFixLine(code: string, fix: Action): string {
const suggestion = codeEntry(code)!.suggestion;
const check = shellQuote(fix.argv ?? []);
return suggestion.includes(check) ? suggestion : `${suggestion} Read-only check: ${check}`;
}
function drainCommand(opts: DreamArgs): string {
return `gbrain dream --drain --window ${opts.windowSeconds}${opts.source ? ` --source ${opts.source}` : ''}`;
}
export async function runDream(engine: BrainEngine | null, args: string[]): Promise<CycleReport | void> {
// ─── `dream retriage` subverb (#4152) — dispatched BEFORE parseArgs so its
// flag set never collides with the cycle flags. `dream --help` never reaches
// here (args[0] is '--help'); `dream retriage --help` prints subcommand help
// inside runDreamRetriage without touching the engine (same IRON RULE).
if (args[0] === 'retriage') {
const { runDreamRetriage } = await import('./dream-retriage.ts');
await runDreamRetriage(engine, args.slice(1));
return;
}
if (args[0] === 'reset-key') {
const { runDreamResetKey } = await import('./dream-reset-key.ts');
await runDreamResetKey(engine, args.slice(1));
return;
}
if (args.includes('--eval-run')) {
const { enableDecideEvalOverride } = await import('../core/ai/decide/config.ts');
enableDecideEvalOverride();
}
// Fail-loud guard (structured-review r3 P1): the CLI flag registry unions
// retriage's flags into `dream`, so the pre-dispatch validator accepts
// `gbrain dream --reconcile-queue` — but without the `retriage` positional,
// parseArgs would ignore the flag and silently run the full (paid, writing)
// maintenance cycle instead of the reconciliation the user asked for.
{
const RETRIAGE_ONLY_FLAGS = ['--reconcile-queue', '--cancel-unmatched', '--audit-rejects'];
const stray = args.find(a => RETRIAGE_ONLY_FLAGS.includes(a));
if (stray) {
setCliExitVerdict(writeCliRefusal(usageError(
`gbrain dream: ${stray} belongs to the 'retriage' subcommand — ` +
`did you mean: gbrain dream retriage ${args.join(' ')}`,
`Run it as: gbrain dream retriage ${args.join(' ')}`), 'dream', { json: jsonRequested(args) }));
return;
}
}
const opts = parseArgs(args);
// ─── IRON RULE: --help short-circuits BEFORE any engine-bearing work ─
// Tests pin this ordering so `gbrain dream --help --source whatever`
// ALWAYS prints help and exits 0, never reaching the engine-null gate
// below. If you reorder this, test/dream.test.ts ("--help --source whatever") fails.
if (opts.help) {
await printHelp(args);
return;
}
// v0.41.13: --source <id> resolution. Three guards in order:
// 1. engine null → exit 1 (the writeback in cycle.ts requires a
// DB connection; without engine we'd silently fail the same way
// PR #1559 was created to fix)
// 2. resolveSourceId throws on unknown id → typed-error catch
// surfaces clean message; non-resolver throws propagate
// 3. archived source → exit 1 with restore hint (writing
// last_full_cycle_at to an archived source would mask data
// staleness when the source is later restored)
let resolvedSourceId: string | undefined;
// #4700: a bare `gbrain dream` whose brain routes bare commands to a
// non-default source (sources.default config, or sole-non-default routing)
// IS the canonical default cycle for that brain — run the full implicit
// phase set instead of the freshness-only source cycle. Explicit
// `--source <id>` and the autopilot fanout keep the freshness boundary.
let implicitDefaultSourceId: string | null = null;
let fullImplicitSourceCycle = false;
// #4778: GBRAIN_SOURCE is tier 2 of the shared resolver, but dream only
// entered the resolver behind the --source gate, so an env-scoped bare run
// cycled the unscoped brain and never stamped the intended source. The
// __all__ sentinel is excluded: unscoped dream already spans every source,
// and a '__all__' scope has no local_path (every filesystem phase would be
// skipped as no_brain_dir).
const envSource = process.env.GBRAIN_SOURCE ?? '';
const envScoped = envSource !== '' && envSource !== ALL_SOURCES;
if (opts.source === null && engine !== null) {
try {
implicitDefaultSourceId = await resolveImplicitDefaultSourceId(engine);
} catch (e) {
if (isResolverUserError(e)) dreamExit(sourceError(e as Error), opts.json);
throw e;
}
// Gated on an EMPTY env, not on !envScoped: an explicit GBRAIN_SOURCE=__all__
// asks for the whole brain and must not be narrowed to the implicit default.
if (opts.dir === null && envSource === '' && implicitDefaultSourceId && implicitDefaultSourceId !== 'default') {
resolvedSourceId = implicitDefaultSourceId;
fullImplicitSourceCycle = true;
}
}
if (opts.source !== null || envScoped) {
if (engine === null) {
dreamExit(opError('database_error',
'gbrain dream --source <id> / GBRAIN_SOURCE=<id> requires a connected brain ' +
'(no engine available); omit the source scope or run `gbrain init` first',
'Fix the brain connection (`gbrain doctor --json` names the cause), or run without a source scope.'), opts.json);
}
try {
// A null explicit falls through to tier 2 (GBRAIN_SOURCE: validate +
// assertSourceExists) — the recall.ts pattern.
resolvedSourceId = await resolveSourceId(engine, opts.source);
} catch (e) {
if (isResolverUserError(e)) dreamExit(sourceError(e as Error), opts.json);
throw e; // genuine bugs propagate with stack trace
}
// #4700 mirror of the path-derived branch below: an env scope naming the
// brain's default-like source is still the canonical default cycle, not
// a freshness-only --source cycle.
fullImplicitSourceCycle = opts.source === null
&& implicitDefaultSourceId === resolvedSourceId
&& resolvedSourceId !== 'default';
// Archived-source guard via fetchSource from sources-load.ts
// (single-row SELECT that projects `archived` and falls back to
// pre-v0.26.5 schemas via isUndefinedColumnError catch — same
// legacy-safety net the rest of the codebase uses). engine's
// built-in listAllSources defaults to includeArchived=false AND
// doesn't project the archived column, so it cannot be used here.
const src = await fetchSource(engine, resolvedSourceId);
if (src?.archived === true) {
dreamExit(opError('unknown_source',
`source ${resolvedSourceId} is archived; restore with ` +
`\`gbrain sources restore ${resolvedSourceId}\` before cycling`,
`Ask the user whether to restore it (gbrain sources restore ${resolvedSourceId}), then run dream again.`), opts.json);
}
}
const brainDir = await resolveBrainDir(engine, opts.dir, resolvedSourceId);
// Both-null is the only hard error: no local checkout AND no DB connection
// means neither filesystem phases nor DB phases can run. With an engine but
// no checkout, the cycle skips filesystem phases and runs DB-only phases
// (resolve_symbol_edges, embed, orphans, ...) — the postgres support path.
if (brainDir === null && engine === null) {
dreamExit(opError('no_brain',
'No brain directory found and no database connection. ' +
'Pass --dir <path> or configure a brain via `gbrain init`.',
'Pass --dir <path>, fix the brain connection, or create a brain with `gbrain init` (see `gbrain init --help`).'), opts.json);
}
// #1869: a path-scoped run (--dir, or the configured sync.repo_path) whose
// directory matches a registered source's local_path IS that source's cycle
// — derive the source id so runCycle writes last_source_cycle_at /
// last_full_cycle_at on success and doctor's cycle_freshness check stops
// reading perpetually stale. Explicit --source still wins (resolved above).
// Fixed here at the command level, NOT in runCycle's stamp gate, so legacy
// global callers (autopilot-global-maintenance runs GLOBAL_PHASES with a
// brainDir and no sourceId) can't falsely stamp per-source freshness.
// A derived match on an archived source is skipped silently (falls back to
// legacy unscoped behavior) — stamping it would mask staleness on restore,
// mirroring the explicit --source archived guard above.
if (resolvedSourceId === undefined && engine !== null && brainDir !== null) {
const derived = await resolveSourceForDir(engine, brainDir);
if (derived !== undefined) {
const src = await fetchSource(engine, derived);
if (src?.archived !== true) {
resolvedSourceId = derived;
// #4700: a path-derived run that lands on the brain's default-like
// source is still the canonical default cycle — keep the full
// implicit phase set rather than downgrading to freshness-only.
fullImplicitSourceCycle = opts.source === null
&& implicitDefaultSourceId === derived
&& derived !== 'default';
}
}
}
// ─── issue #1678: bounded single-hold extract_atoms drain ──────────
if (opts.drain) {
if (engine === null) {
dreamExit(opError('database_error', 'gbrain dream --drain requires a connected brain (no engine available)',
'Fix the brain connection (`gbrain doctor --json` names the cause), then run the drain again.'), opts.json);
}
return runDrain(engine, opts, resolvedSourceId, brainDir);
}
// #4493: pass EVERY named phase through (runCycle already accepts the
// array); empty means the full/default cycle.
const phases: CyclePhase[] | undefined = opts.phases.length > 0 ? opts.phases : undefined;
const report = await runCycle(engine, {
brainDir,
// #6023: the local CLI sees private fact text in the consolidate dry-run preview.
remote: false,
dryRun: opts.dryRun,
pull: opts.pull,
phases,
directPhases: phases !== undefined,
// Undefined for legacy unscoped runs; set for explicit source cycles,
// path-derived cycles, and bare default-like non-default source cycles.
sourceId: resolvedSourceId,
fullImplicitSourceCycle,
synthInputFile: opts.inputFile ?? undefined,
synthDate: opts.date ?? undefined,
synthFrom: opts.from ?? undefined,
synthTo: opts.to ?? undefined,
synthBypassDreamGuard: opts.bypassDreamGuard,
// issue #2860: exactly one phase is guaranteed here when opts.once is
// set (parseArgs enforces --once requires a single explicit --phase).
onceForPhase: opts.once ? opts.phases[0]! : undefined,
});
// A phase the caller named (or --input implied) that skipped for want of a
// database did not do what was asked: refuse like --source/--drain do.
const noDbPhase = report.phases.find(p => p.status === 'skipped' && p.details?.reason === 'no_database'
&& (opts.phases as string[]).includes(p.phase));
if (noDbPhase) {
dreamExit(opError('database_error',
`gbrain dream --phase ${noDbPhase.phase} requires a connected brain (no engine available); the phase was skipped (no_database)`,
'Fix the brain connection (`gbrain doctor --json` names the cause), then run the phase again.'), opts.json);
}
// Exit non-zero when the cycle failed overall or any phase failed (agent-first
// operator wave E4): a 'partial' cycle whose phase reports 'fail' — thrown and
// contained, or caught inside the runner — is never success. Warn-only
// 'partial' cycles still exit 0.
const failedPhases = report.phases.filter(p => p.status === 'fail' || p.details?.contained === true).map(p => p.phase);
const failed = report.status === 'failed' || failedPhases.length > 0;
// #7646: a phase that needs the user (sync_anchor_relative) fails again on every rerun; its ask_user fix leads instead.
const askPhase = report.phases.find(p => failedPhases.includes(p.phase) && p.fix?.next === 'ask_user');
if (!opts.json) printHuman(report);
else if (!failed || !jsonGuardActive()) await writeJsonDocument(JSON.stringify(report, null, 2));
else {
// D2: under the --json guard a failed cycle is one envelope leading with the CycleReport keys.
writeCliError(opError('cycle_failed', `The dream cycle ${report.status === 'failed' ? 'failed' : 'had failing phases'}${failedPhases.length ? ` (${failedPhases.join(', ')})` : ''}.`,
askPhase ? `The ${askPhase.phase} phase needs the user: ${askPhase.summary} Follow phases[].fix before rerunning.`
: `Read phases[].error for the cause, fix it, then rerun the phase: gbrain dream --phase ${failedPhases[0] ?? '<phase>'}`),
'dream', { json: true, stderr: false, legacy: { ...report }, ...(askPhase ? { extra: { fix: askPhase.fix } } : {}) });
}
if (failed && !opts.json && failedPhases.length > 0) {
console.error(askPhase
? `Dream failed: the ${askPhase.phase} phase needs the user before it can run: ${askPhase.fix?.user_message ?? askPhase.summary}`
: `Dream failed: ${failedPhases.length} phase(s) failed (${failedPhases.join(', ')}); see the phase errors above. After fixing the cause, re-run one with: gbrain dream --phase ${failedPhases[0]}`);
}
if (failed) process.exit(1);
return report;
}