Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* `dream` — the only mutating batch operation in the Brain layer.
*
* `dream` reads the current Brain state and decides which transitions
* to apply. It is deterministic given the inputs and the configured
* time (the `--now` parameter). The algorithm is anchored in design
* doc §7.3 and the per-rule clarifications in §7.4.
*
* This module is the ORCHESTRATOR: it sequences the stages and owns the
* decisions that only make sense with the whole run in view — the run id,
* the `changed` gate, the snapshot, the workrun lifecycle and the
* safeguard checkpoints. Each stage's mechanics live in its own module:
*
* - `dream-scan.ts` read the `Brain/` tree into memory
* - `dream-plan-topics.ts` what a cluster of signals on a topic means
* - `dream-refresh.ts` counters, confidence, unconfirmed → confirmed
* - `dream-plan-retires.ts` when a preference has outlived its usefulness
* - `reconcile-outcomes.ts` domain classification of contradictions
* - `dream-apply.ts` the plan turned into disk state, in order
* - `dream-report.ts` the run's audit trail in `Brain/log/`
* - `dream-summary.ts` the {@link DreamRunSummary} the caller sees
* - `dream-outcome.ts` the `changed` gate, warnings, retire siblings
* - `dream-rollup.ts` the rollup-ladder plan and its link manifest
* - `dream-tail.ts` topic planning and the human view render
*
* Outputs (high level):
*
* - Pre-run snapshot under `Brain/.snapshots/<run_id>.tar.zst`,
* created BEFORE any state-changing write so a crash mid-run can
* be rolled back atomically.
* - New / updated files in `Brain/preferences/`.
* - Moves into `Brain/retired/`.
* - Moves from `Brain/inbox/` into `Brain/inbox/processed/`.
* - Moves from `Brain/inbox/` into `Brain/inbox/archived/` for signals
* that left the contradiction window unconsumed (`signal-archive.ts`).
* - One appended event in `Brain/log/<today>.md` summarising the
* run — **only** if any state actually changed. Idempotent reruns
* touch nothing.
*
* Invariants:
*
* - Same-sign signals on an active preference are noted (moved to
* `processed/`, log event `noted-redundant`) but do NOT create a
* second preference and do NOT increment `applied_count`.
* - Opposite-sign signals against an active preference accumulate
* toward a rebuttal. Hitting `candidate_threshold` retires the
* active preference (reason `rebutted`) UNLESS it is pinned, in
* which case the rebut attempt is logged as a `retain-pinned`
* event and the preference stays.
* - Corrupted frontmatter on a single file produces a
* `skip-corrupted-frontmatter` log event and is skipped. The run
* continues for the rest of the tree.
* - dryRun mode returns the planned summary but performs no writes.
*/
import { withTopicPass, withViewPass } from "./dream-tail.ts";
import { vaultRelativeOf } from "./no-vault.ts";
import { withLogReadPass } from "./log-days.ts";
import { existsSync } from "node:fs";
import { join } from "node:path";
import { regenerateActiveQuiet } from "./active.ts";
import {
applyDreamPlan,
gatedRetireSlugs,
plannedSignalArchiveIds,
plannedSignalMoveIds,
type DreamApplyResult,
} from "./dream-apply.ts";
import { planAutoRetires } from "./dream-plan-retires.ts";
import { planTopics, topicKeyContentionWarnings } from "./dream-plan-topics.ts";
import type { ScanResult } from "./dream-plan.ts";
import {
planCrossTopicRules,
readCrossTopicLedger,
resolveCrossTopicConfig,
} from "./dream-plan-cross-topic.ts";
import { planRefresh, scanApplyEvidence } from "./dream-refresh.ts";
import { writeDreamLog } from "./dream-report.ts";
import { scanBrain } from "./dream-scan.ts";
import { planSignalArchive } from "./signal-archive.ts";
import { buildChangedSummary, buildNoOpSummary } from "./dream-summary.ts";
import type { DreamOptions, DreamRunSummary, DreamWarning } from "./dream-types.ts";
import { openWorkrun, WORKRUN_PHASE, workrunPath, type WorkrunHandle } from "./dream-workrun.ts";
import { buildIntentReview } from "./intent-review.ts";
import { logShardWikilink } from "./log.ts";
import {
OPERATION,
progressCounter,
progressReasonForError,
type ProgressCounter,
} from "./progress.ts";
import { regenerateLessonsQuiet } from "./lessons.ts";
import { brainDirsForWrite, collisionCandidateName } from "./paths.ts";
import { isStoreOnly } from "../store/store-only.ts";
import { repairLaneEntryIds } from "../store-migration/lane-id-repair.ts";
import { loadBrainConfig } from "./policy.ts";
import { buildReconcileOutcomes } from "./reconcile-outcomes.ts";
import { buildRollupPlan, memoizedLinkCandidates } from "./dream-rollup.ts";
import { collectWarnings, hasStateChange, withRetireSiblings } from "./dream-outcome.ts";
import { applySalienceGate } from "./salience-gate.ts";
import { withDestructiveSnapshot } from "./snapshot-gate.ts";
import { compactRunStamp, isoDate } from "./time.ts";
import { BRAIN_SNAPSHOT_REASON } from "./types.ts";
// ----- Public surface ------------------------------------------------------
export type {
DreamGateOverrides,
DreamGatedRetireEntry,
DreamOptions,
DreamRunSummary,
DreamUncertainEntry,
DreamWarning,
} from "./dream-types.ts";
export { shouldGateRetireFromConfirmed } from "./dream-apply.ts";
export { scanBrain } from "./dream-scan.ts";
// ----- Main entry ----------------------------------------------------------
/**
* Execution stages of one pass, in the order they run.
*
* Neither existing vocabulary fits: `DREAM_PHASE` is the REPORTING order
* of the summary, and `WORKRUN_PHASE` marks the points where a phase's
* durable output has already landed - both are about what finished, and
* progress is about what is happening. These five name the spans between
* the safeguard checkpoints, which is where the wall-clock actually goes.
*
* So one operation has two stage vocabularies, and a reader will trip on
* it, because `log` is a member of both and means different things: here
* it is the span during which the audit tail is written, and in
* `DREAM_PHASE` it is the summary section that reports what that span
* did. If you are reading a progress record, this is the list it draws
* from; if you are reading `DreamRunSummary.phases`, that is the other
* one. Merging them would mean either reporting spans the summary does
* not have or emitting progress for phases that never execute.
*/
const DREAM_STAGE = Object.freeze({
scan: "scan",
plan: "plan",
apply: "apply",
log: "log",
finalize: "finalize",
} as const);
/** Code carried on the summary when the caller's progress sink failed. */
const PROGRESS_SINK_FAULT_CODE = "progress-sink-failed";
function errorMessage(error: unknown): string {
return error instanceof Error ? error.message : String(error);
}
/**
* Carry a failed progress sink onto the summary the caller already reads.
* Only the first fault is reported: the sink is detached after it, so a
* second entry could only describe the same broken stream twice.
*/
function noteProgressFaults(warnings: DreamWarning[], faults: ReadonlyArray<string>): void {
const first = faults[0];
if (first === undefined) return;
warnings.push({
code: PROGRESS_SINK_FAULT_CODE,
message: `progress reporting stopped after the sink threw: ${first}`,
});
}
/** `previewReadable` was passed to a pass that is not a dry run. */
export class DreamPreviewReadableError extends Error {
constructor() {
super("dream: previewReadable applies to a dry run only");
this.name = "DreamPreviewReadableError";
}
}
/**
* The scan as a caller who may read only what `admit` passes sees it:
* every record at a path it rejects is dropped, as if it were absent.
*/
function scanAsAdmitted(
vault: string | null,
scan: ScanResult,
admit: (rel: string) => boolean,
): ScanResult {
const keep = (path: string): boolean => admit(vaultRelativeOf(path, vault));
return {
...scan,
signals: scan.signals.filter((r) => keep(r.path)),
preferences: scan.preferences.filter((r) => keep(r.path)),
retired: scan.retired.filter((r) => keep(r.path)),
corrupted: scan.corrupted.filter((r) => keep(r.path)),
tombstonedPreferences: scan.tombstonedPreferences?.filter((r) => keep(r.path)),
};
}
/**
* Run one consolidation pass.
*
* A thin shell around {@link dreamRun} for one reason: a pass that stops
* at a checkpoint - because the operator interrupted it, or because the
* deadline elapsed - must say so on the progress stream before the error
* leaves. Without this the stream would simply end, and a caller could
* not tell a cancelled pass from a crashed one from a hung one, which is
* the whole distinction `SafeguardAbortError` exists to preserve.
*/
export function dream(vault: string | null, opts: DreamOptions = {}): DreamRunSummary {
// A caller's progress sink is an observer, and an observer must not be
// able to destroy what it observes: a closed pipe or a renderer defect
// cannot be allowed to abort a pass that is otherwise succeeding. Nor
// may it vanish - the fault is carried out on the summary the caller
// already reads, once, and the sink is detached for the rest of the run.
const progressFaults: string[] = [];
const progress = progressCounter(OPERATION.dream, opts.onProgress, {
onSinkError: (error) => progressFaults.push(errorMessage(error)),
});
try {
// One read pass for the whole dream: the store-only log is read once
// and shared by every preference's evidence walk (log-days.ts).
return withLogReadPass(() =>
withViewPass(withTopicPass(dreamRun(vault, opts, progress, progressFaults), opts), opts),
);
} catch (error) {
const reason = progressReasonForError(error);
if (reason !== null) progress.stop(reason);
throw error;
}
}
/** Ladder attempts for a no-vault run id, as many as a snapshot run gets. */
const NO_VAULT_RUN_ID_ATTEMPTS = 100;
/** The first `<base>[-N]` run id whose no-vault workrun journal does not exist yet. */
function uniqueNoVaultRunId(base: string): string {
for (let attempt = 1; attempt <= NO_VAULT_RUN_ID_ATTEMPTS; attempt++) {
const candidate = collisionCandidateName(base, attempt);
if (!existsSync(workrunPath(null, candidate))) return candidate;
}
throw new Error(`dream: no free run id after ${NO_VAULT_RUN_ID_ATTEMPTS} attempts (${base})`);
}
/**
* Regenerate the active and lessons digests after a pass. Where they land
* is `compiledDigestPath`'s one rule: `Brain/active.md` and
* `Brain/lessons.md` on an unswitched machine, the device-local cache on
* a store-only one (design D14 item 7), which this warms.
*/
function regenerateDigestPages(vault: string | null, now: Date): void {
regenerateActiveQuiet(vault, { now });
regenerateLessonsQuiet(vault, { now });
}
function dreamRun(
vault: string | null,
opts: DreamOptions,
progress: ProgressCounter,
progressFaults: ReadonlyArray<string>,
): DreamRunSummary {
const now = opts.now ?? new Date();
const dryRun = opts.dryRun === true;
if (opts.previewReadable !== undefined && !dryRun) throw new DreamPreviewReadableError();
// The stage opens BEFORE the first checkpoint, not after it. A guard
// that is already past its deadline - or a signal already aborted -
// trips here, and a counter with no stage open emits nothing, so the
// stream would report a pass that was stopped instantly as a pass that
// never spoke. Those are the two cases this release exists to keep
// apart.
progress.start(DREAM_STAGE.scan);
opts.safeguard?.checkpoint();
const cfg = loadBrainConfig(vault);
// Lane entries an earlier release filed under another path's id are
// moved to their own (`store-migration/lane-id-repair.ts`); a no-op once
// repaired, and never a reason to fail the pass.
if (!dryRun && (vault === null || isStoreOnly({ vault }))) {
try {
repairLaneEntryIds(vault);
} catch {
// The next pass tries again.
}
}
// Per-run gate resolution (no-dead-ends, Unit E): the override wins for
// this run, the configured value decides when it is absent. Resolved
// once, here, so the heal branch below has a single source of truth and
// nothing writes the decision back to `_brain.yaml`.
const healEnrichEnabled = opts.gates?.heal_enrich ?? cfg.dream.heal_enrich_enabled === true;
let runId = formatRunId(now);
// The retired_by stamp every retire in this pass carries. Built
// through the shared helper so it names the log shard the pass's own
// events land in - with a configured device id, the bare-date shape
// names a file this device never writes, and the doctor reads the
// provenance as a broken link.
const wikilinkToRun = logShardWikilink(isoDate(now));
const callerAgent = opts.agentName?.trim() ?? "";
const isNonPrimary =
cfg.primary_agent !== null && callerAgent.length > 0 && callerAgent !== cfg.primary_agent;
const warnings = collectWarnings(isNonPrimary, callerAgent, cfg.primary_agent);
// 0. Scan the whole Brain/ tree. Corrupted files (frontmatter
// parse-errors) are surfaced separately so the planning phase
// can emit `skip-corrupted-frontmatter` log entries without
// aborting.
//
// The guard goes in and the sink does not, and the two decisions
// have different reasons - see `ScanBrainOptions`. The scan is the
// largest unbounded read in the pass, so leaving it unguarded put
// the whole `Brain/` tree between two of the pass's five
// checkpoints; the stream, by contrast, is this counter's, which
// already owns a `scan` stage.
const fullScan = scanBrain(vault, opts.safeguard ? { safeguard: opts.safeguard } : {});
opts.onScanPreferences?.(fullScan.preferences);
const scan =
opts.previewReadable === undefined
? fullScan
: scanAsAdmitted(vault, fullScan, opts.previewReadable);
progress.advance(DREAM_STAGE.scan);
const intentReview = buildIntentReview(vault, {
now,
...(opts.previewReadable !== undefined ? { readable: opts.previewReadable } : {}),
});
progress.start(DREAM_STAGE.plan, scan.preferences.length);
// 1-2. Plan per-topic transitions: new unconfirmed preferences,
// same-sign noted-redundant moves, rebuttal accumulation.
const plan = planTopics(scan, cfg, now);
// A folded topic key claimed by two preferences is an ambiguity the pass
// refuses to settle by scan order, so it planned nothing for that key. The
// warning is how it says so - on the no-op summary as well as the changed
// one, because a run that decided nothing is exactly the run that must
// still explain itself.
warnings.push(...topicKeyContentionWarnings(plan));
// Archive step (issue #195): inbox signals the topic plan did not consume
// and that have left the contradiction window can never count toward a
// candidate again, so they leave the inbox for `inbox/archived/`.
// Planned after the topic plan so a consumed signal is never archived.
warnings.push(...planSignalArchive(scan, cfg, now, plan));
// 3. Plan refresh: applied / violated / last_evidence / confidence,
// and unconfirmed → confirmed promotion. We need the log of all
// apply-evidence entries up to `now` — we read every day file
// referenced by `last_evidence_at` plus today's file. Since the
// plan doesn't yet know dates, we scan the entire log/ directory.
const evidence = scanApplyEvidence(vault);
const refresh = planRefresh(vault, scan, evidence, cfg, now, plan);
// 4. Plan retires (expired-unconfirmed, stale-no-evidence). Pinned
// preferences get a `retain-pinned` log event instead of a real
// retire.
planAutoRetires(scan, cfg, now, plan, refresh);
// 4b. Cross-topic rule promotion (t_642bc2b8). Planned after the
// refresh pass - the source pool reads post-refresh confirmation
// state - and after the retire plan, so a preference this pass is
// about to retire is never cited as evidence. Before the `changed`
// gate, so a fired promotion counts as a state change and a
// below-threshold or budgeted-out pass stays byte-identical; the
// rollup ladder is the structural precedent (plan before the
// gate, persist the ledger only when fired). The ledger read is
// skipped entirely when the feature is off: an un-opted-in vault
// pays no I/O here. The disclosure sink is the run's warning list:
// a declared knob the resolver floored (finding 62) is named on
// the summary, never applied silently.
const crossTopicConfig = resolveCrossTopicConfig(cfg, (code, message) =>
warnings.push({ code, message }),
);
const crossTopic = planCrossTopicRules({
scan,
refresh,
config: crossTopicConfig,
ledger: crossTopicConfig ? readCrossTopicLedger(vault) : null,
now,
plan,
});
// 5. §7.3 step "move consumed signals out of inbox/" needs no pass of
// its own: both routes that consume a signal - the topic loop and
// the active-pref handler - already enqueued it into
// `plan.signalsToMove` at the moment they decided to consume it.
// Reconcile phase (F3): classify each contradiction topic into a
// domain. Source-freshness with a clear gap auto-resolves (recorded,
// never a sub-threshold mutation); everything else becomes an open
// question. Computed in-memory before the `changed` gate so the
// summary carries open_questions on both the no-op and changed paths;
// the `reconcile` log events below are emitted only on a changed run.
const reconcile = buildReconcileOutcomes(scan, plan, cfg, now);
// Deterministic salience gate over the ladder's fold set
// (salience-lifecycle-enrichment, unit 1). The ladder counts facts and
// nothing else, so this is the only seam where a salience judgement can
// change what the pass asks a model to fold. With
// `dream.salience_threshold` unset the gate is open and reads nothing,
// which is why an un-opted-in vault pays no I/O here.
const salienceGate = applySalienceGate({ vault, preferences: scan.preferences, cfg, now });
// The wikilink targets a fired rung's envelope offers, built at most
// ONCE per dream run and only if a rung fires. The manifest is a whole
// -vault walk (a frontmatter read per note under owner-scope delivery),
// the ladder is planned before the `changed` gate, and the runId
// collision path below re-plans - so an eager build paid that walk on
// every dry run that fires nothing, and twice on a collision.
const linkCandidates = memoizedLinkCandidates(vault, opts.agentName, opts.readable);
// Count-triggered fact rollup ladder (S3): pure counters over the
// ADMITTED fact artifacts (preferences) against the persisted per-tier
// baselines. Computed before the `changed` gate so a run whose ONLY
// effect is a rollup still counts as changed; below threshold it fires
// nothing and the ledger is never written, so the run stays
// byte-identical.
let rollupPlan = buildRollupPlan(vault, cfg, salienceGate.admitted, runId, linkCandidates);
if (!hasStateChange(plan, refresh, scan.corrupted.length, rollupPlan)) {
if (!dryRun) regenerateDigestPages(vault, now);
// A run that changed nothing still finished. Reporting it as an
// unterminated stream would make an idempotent rerun - the common
// case - indistinguishable from a pass that died in planning.
progress.finish();
noteProgressFaults(warnings, progressFaults);
return buildNoOpSummary({
runId,
dryRun,
plan,
refresh,
reconcile,
intentReviews: intentReview.reviews,
warnings,
salienceGate,
});
}
// ---- Execute --------------------------------------------------------
// The pre-run recovery point and every mutation behind it now run
// through `withDestructiveSnapshot`, the gate whose own header names
// an inline `createSnapshot` as the anti-pattern it exists to prevent.
// This module used to be that anti-pattern: it minted its own run id
// through a second collision ladder, took its own archive, and pruned
// retention afterwards with a third copy of the warning text. The
// wrapper owns all three now, and the run id it reserves is the one
// the workrun, the log and the rollup targets are named after.
let snapshotPathStr: string | undefined;
// Honor an already-expired deadline BEFORE spending snapshot I/O.
opts.safeguard?.checkpoint();
progress.start(DREAM_STAGE.apply);
// v0.12.0 Brain Integrity Suite: durable workrun for the dream pass.
// Opened lazily on the mutation path (no workrun on dry-run or
// no-op early-return). The handle is null until the exec branch
// claims it; it is finalised immediately before the summary is built.
let workrun: WorkrunHandle | null = null;
let exec: DreamApplyResult;
if (dryRun) {
// Dry-run still reports the move list so the caller's summary is
// accurate, but it does not touch disk.
opts.safeguard?.checkpoint();
exec = {
moved: plannedSignalMoveIds(plan),
archived: plannedSignalArchiveIds(plan),
gatedRetires: [],
healEnriched: 0,
};
} else {
const baseRunId = runId;
const applyRun = (): { applied: DreamApplyResult; handle: WorkrunHandle } => {
opts.safeguard?.checkpoint();
const handle = openWorkrun(vault, runId);
// Truthful checkpoints (no-dead-ends, Unit E). A marker means every
// durable effect attributed to that phase is already on disk, so a
// crash leaves a journal whose last marker names work that genuinely
// finished. Cluster and close are the only two phases whose work
// provably ends here: clustering is pure planning that produces no
// file at all, and close's single artifact - the pre-run snapshot -
// was written by the gate before this callback ran. Every other
// marker moved down to the point where that phase's writes land;
// see the emission notes there.
handle.checkpoint(WORKRUN_PHASE.clusterComplete);
handle.checkpoint(WORKRUN_PHASE.closeComplete);
const applied = applyDreamPlan({
vault,
cfg,
now,
plan,
refresh,
agentName: opts.agentName,
wikilinkToRun,
healEnrichEnabled,
...(opts.safeguard ? { safeguard: opts.safeguard } : {}),
workrun: handle,
});
return { applied, handle };
};
if (vault === null) {
// No vault (design D14 item 9): the store's shards are append-only
// and need no pre-run snapshot, so the plan applies directly. The
// run id climbs the same `-N` ladder a snapshot run does, so two
// passes in one second never share a workrun journal.
runId = uniqueNoVaultRunId(runId);
if (rollupPlan.fired && runId !== baseRunId) {
rollupPlan = buildRollupPlan(vault, cfg, salienceGate.admitted, runId, linkCandidates);
}
const ran = applyRun();
exec = ran.applied;
workrun = ran.handle;
} else {
const gated = withDestructiveSnapshot(
vault,
BRAIN_SNAPSHOT_REASON.dream,
(snapshot) => {
runId = snapshot.runId;
// The rollup plan (and each envelope's target_path) was built
// with the pre-collision runId; if the ladder corrected it,
// rebuild the plan so every target_path embeds the final run_id.
if (rollupPlan.fired && runId !== baseRunId) {
rollupPlan = buildRollupPlan(vault, cfg, salienceGate.admitted, runId, linkCandidates);
}
return applyRun();
},
{
// `now` rather than wall clock: the pass is byte-reproducible given
// its injected clock, and the snapshot audit line must not be the
// one thing that breaks that.
now,
// The dream run id names the workrun as well as the archive, so a
// candidate free in `.snapshots/` is not enough. This is the claim
// that used to live in a second ladder in this module.
available: (candidate) => !existsSync(workrunPath(vault, candidate)),
},
);
snapshotPathStr = gated.snapshot.path;
exec = gated.result.applied;
workrun = gated.result.handle;
}
}
// Post-mutation safeguard checkpoint: every state-changing write for
// this run is on disk, so a deadline that has passed stops the run here
// rather than part-way through the audit tail.
opts.safeguard?.checkpoint();
progress.advance(DREAM_STAGE.apply);
progress.start(DREAM_STAGE.log);
// v0.12.0 Brain Integrity Suite: build the gated-slug set once so the
// log body and the DreamRunSummary stay consistent — both views must
// exclude retires the destructive-from-confirmed gate skipped, or
// the next dream pass would parse a `pref-foo` log claiming the
// pref was retired while the file is still in `preferences/`.
const gatedSlugs = gatedRetireSlugs(exec.gatedRetires);
if (!dryRun) {
writeDreamLog({
vault,
now,
runId,
scan,
plan,
refresh,
reconcile,
rollupPlan,
crossTopicLedger: crossTopic.ledger,
moved: exec.moved,
archived: exec.archived,
gatedSlugs,
isNonPrimary,
callerAgent,
workrun,
});
// Retention already ran inside the gate, immediately after the
// archive was written. The set of survivors is the same either way -
// this run creates no further archives - and the gate is where the
// refusal and the removal list are reported, so a second prune here
// would be a second rule for one directory.
regenerateDigestPages(vault, now);
}
// Pre-finalize safeguard checkpoint (no-dead-ends, Unit E). Everything
// between the post-mutation checkpoint and this line - the log events,
// the rollup ledger write, snapshot pruning, the active/lessons
// regeneration - used to run with no deadline check at all, so a run
// already past its budget still reached `finalized`. Tripping here
// leaves the workrun dangling, which is the documented contract.
opts.safeguard?.checkpoint();
progress.advance(DREAM_STAGE.log);
progress.start(DREAM_STAGE.finalize);
// v0.12.0 Brain Integrity Suite: finalise the durable workrun
// immediately before constructing the summary. Any crash building
// the summary leaves the workrun dangling for the next pass to
// spot. `workrun` is null on dry-run / pre-mutation paths.
workrun?.finalize();
progress.advance(DREAM_STAGE.finalize);
progress.finish();
noteProgressFaults(warnings, progressFaults);
const summary = buildChangedSummary({
runId,
// `brainDirsForWrite` asserts the vault is writable, so the log path
// is resolved only on the branch that actually wrote to it.
runTail: dryRun
? { dry_run: true }
: {
// A store-only machine writes `log-event` records, no day file.
log_path:
vault === null || isStoreOnly({ vault })
? NO_VAULT_LOG_PATH
: join(brainDirsForWrite(vault).log, `${isoDate(now)}.md`),
},
scan,
plan,
refresh,
reconcile,
rollupPlan,
salienceGate,
intentReviews: intentReview.reviews,
warnings,
gatedRetires: exec.gatedRetires,
gatedSlugs,
moved: exec.moved,
archived: exec.archived,
healEnriched: exec.healEnriched,
snapshotPath: snapshotPathStr,
});
return withRetireSiblings(summary, scan, plan, {
enabled: opts.retireSiblingsEnabled,
gatedRetires: exec.gatedRetires,
// A dry run applies nothing, so it gates nothing; the preview asks the
// same confirmed-evidence gate the apply step will.
previewGateThreshold: dryRun ? cfg.retire.confirmed_evidence_min_threshold : undefined,
});
}
/** What a no-vault run names as its log: the brain log is a store record stream. */
const NO_VAULT_LOG_PATH = "store:log";
function formatRunId(d: Date): string {
// <reason>-YYYY-MM-DD-HHMMSS. The prefix is the snapshot-reason
// constant rather than a literal, so the archive's filename and the
// provenance stamped into its sidecar are one string.
return `${BRAIN_SNAPSHOT_REASON.dream}-${compactRunStamp(d)}`;
}