feat(dream): --archive-dir flag persists CycleReport JSON + atomic latest.json symlink

[ChenyqThu]

Summary

Adds an --archive-dir <path> flag to gbrain dream that, when paired with --json, writes the CycleReport to <path>/<iso>.json (fs-safe colon-free timestamp) and atomically swaps a <path>/latest.json symlink to point at it.

Motivation

The cron pattern of "spawn dream --json, capture stdout, parse JSON, archive to a per-cycle file, swap a latest pointer" repeats across every downstream that wraps dream. Pushing the archive surface into core removes ~80 LoC from each wrapper while giving everyone the same atomic-swap contract (no dangling symlink ever visible to readers — rename is atomic on the same fs).

Concrete downstream case: my fork jarvis-knowledge-os-v2 ships a 205-line dream-wrap launchd worker whose primary value (after this PR lands) becomes the exit-code translation block (~30 lines). The entire archive + symlink surface (~80 lines) collapses into a single --archive-dir arg.

Behavior

• --archive-dir without --json is a no-op + emits a stderr warning (printed human report has no JSON to archive)
• Directory is auto-created (mkdirSync recursive)
• ISO timestamp is colon-free (2026-05-17T23-45-12Z) so SMB / Windows shares accept the filenames
• latest.json swap uses symlink-to-tmp + rename pattern (atomic on the same fs); on platforms where symlink isn't supported the per-cycle file still lands and a stderr warning fires
• Cycle status semantics unchanged (--archive-dir affects archive side-effect only, not exit code or report shape)

Help text

  --archive-dir <path>
                      Persist the CycleReport JSON to <path>/<iso>.json and
                      atomically swap a <path>/latest.json symlink. Pairs with
                      --json; no-op without it. Replaces ad-hoc downstream
                      stdout-capture wrappers. Directory is auto-created.

Test plan

• bun run typecheck — clean
• bun test test/dream-cli-flags.test.ts test/dream.test.ts — 29 pass / 0 fail / 72 expect() calls / 19.46s
• 5 new static-introspection cases in test/dream-cli-flags.test.ts (flag declared, archive helper exists, no-op-without-json contract, isoStamp colon-free contract)
• 5 new integration cases in test/dream.test.ts against real PGLite + real archive dir:
  • per-cycle file + symlink shape
  • fs-safe filename (no :, sortable, matches regex)
  • atomic swap on second run (symlink target changes, both per-cycle files retained)
  • auto-creates missing destination directory
  • no-op without --json + stderr warning emitted

Diff size

3 files / +205 / -3 — additive flag, no behavior change for existing callers.

Related downstream cleanup

On merge, my fork drops skills/kos-jarvis/dream-wrap/run.ts from 205 LoC to ~30 (exit code translation only). Filed as PR-3 in my fork's TODO.

Pattern matches the garrytan/gbrain PR style of #1016 (additive AI recipe field) and the superseded #1017 (bootstrap probes) — fork-side experience codified into upstream so the wrapper layer thins.

🤖 Generated with Claude Code