mulmoclaude 0.5.2 → 0.6.0

package/server/workspace/journal/dailyPass.ts

@@ -1,13 +1,3 @@
-// The daily pass: walk chat/*.jsonl, find sessions changed since
-// the last run, bucket events by local-date, call the archivist
-// once per affected day, and apply its output (write daily/*.md,
-// create/append/rewrite topics/*.md).
-//
-// This file is the only one in the journal module that combines
-// filesystem side-effects with LLM calls. Pure bits (event parsing,
-// bucketing) are factored into small exported helpers so tests can
-// exercise them without touching disk.
-
 import fsp from "node:fs/promises";
 import path from "node:path";
 import { workspacePath as defaultWorkspacePath } from "../workspace.js";
@@ -37,26 +27,16 @@ import { EVENT_TYPES } from "../../../src/types/events.js";
 import { extractAndAppendMemory } from "./memoryExtractor.js";
 import { isRecord } from "../../utils/types.js";
 
-// --- Constants ------------------------------------------------------
-
-// Per-event content is truncated before handing to the archivist so
-// an accidentally huge tool result (e.g. base64 image data) doesn't
-// blow past the CLI's context window.
+// Truncate per-event content so an oversized tool result (e.g. base64 image) doesn't blow past the CLI's context window.
 const MAX_EVENT_CONTENT_CHARS = 600;
 
-// Hard cap on events per session included in the prompt. Sessions
-// with thousands of events get their head kept — the archivist can
-// generally get the gist from the opening.
+// Cap events per session in the prompt; sessions with thousands keep the head — archivist gets the gist from the opening.
 const MAX_EVENTS_PER_SESSION = 80;
 
-// --- Public entry ---------------------------------------------------
-
 export interface DailyPassDeps {
   workspaceRoot?: string;
   summarize: Summarize;
-  // Active session ids to skip (mid-write). Caller passes the
-  // live session registry to avoid ingesting jsonl files that the
-  // agent is still appending to.
+  // Skip mid-write sessions: caller passes the live registry so we don't ingest jsonl the agent is still appending to.
   activeSessionIds: ReadonlySet<string>;
 }
 
@@ -65,18 +45,9 @@ export interface DailyPassResult {
   sessionsIngested: string[];
   topicsCreated: string[];
   topicsUpdated: string[];
-  skipped: Array<{ date: string; reason: string }>;
-}
-
-// Inputs to the day loop, gathered up-front by `buildDailyPassPlan`
-// so `runDailyPass` reads as orchestration only — no IO interleaved
-// with scheduling decisions. Returned as a single object instead of
-// a tuple so future fields (e.g. caller-provided clock for tests)
-// can be added without re-threading every call site.
-//
-// `newTopicsSeen` is a mutable accumulator: the day loop adds to it
-// as topics are created. Including it in the plan keeps the lifecycle
-// visible at the call site.
+  skipped: { date: string; reason: string }[];
+}
+
 export interface DailyPassPlan {
   workspaceRoot: string;
   perSessionExcerpts: Map<string, Map<string, SessionExcerpt>>;
@@ -92,19 +63,8 @@ export interface DailyPassPlan {
   dirtyMetaById: ReadonlyMap<string, SessionFileMeta>;
 }
 
-/**
- * Read-only setup for `runDailyPass`: enumerate sessions, find the
- * dirty ones, build day buckets, snapshot existing topics, and
- * compute the initial mutable state. Returns `null` when there's
- * nothing to do (no dirty sessions). Otherwise returns a plan object
- * the day loop can iterate over.
- *
- * Intentionally does NOT short-circuit on empty `dayBuckets`. If
- * every dirty session produces zero excerpts (all malformed, or all
- * tool-only with no text turns) we still want `readAllTopics` to
- * fire and `initialNextState.knownTopics` to be normalised/sorted.
- * The day loop then iterates zero times and we drop straight through.
- */
+// Do NOT short-circuit on empty dayBuckets: if every dirty session yields zero excerpts we still want readAllTopics to
+// fire so initialNextState.knownTopics is normalised/sorted; the day loop then iterates zero times and drops through.
 export async function buildDailyPassPlan(state: JournalState, deps: DailyPassDeps): Promise<DailyPassPlan | null> {
   const workspaceRoot = deps.workspaceRoot ?? defaultWorkspacePath;
   const chatDir = path.join(workspaceRoot, WORKSPACE_DIRS.chat);
@@ -118,11 +78,7 @@ export async function buildDailyPassPlan(state: JournalState, deps: DailyPassDep
 
   const existingTopics = await readAllTopics(workspaceRoot);
   const newTopicsSeen = new Set<string>(state.knownTopics);
-  // `nextState` is rebuilt through the day loop and persisted after
-  // each successful day via writeState (atomic tmp+rename). We do
-  // NOT bump lastDailyRunAt here — that's the outer runner's job
-  // after the whole pass (including optimization) finishes, so
-  // partial progress doesn't look like a complete pass.
+  // Do NOT bump lastDailyRunAt here — outer runner does it after optimization, so partial progress isn't a complete pass.
   const initialNextState: JournalState = {
     ...state,
     knownTopics: [...newTopicsSeen].sort(),
@@ -177,7 +133,7 @@ export async function runDailyPass(state: JournalState, deps: DailyPassDeps): Pr
       result.topicsUpdated.push(...dayResult.topicsUpdated);
       result.sessionsIngested.push(...dayResult.sessionsIngested);
     }
-    nextState = dayResult.nextState;
+    ({ nextState } = dayResult);
   }
 
   await maybeExtractMemory(plan.perSessionExcerpts, plan.workspaceRoot, deps);
@@ -185,10 +141,6 @@ export async function runDailyPass(state: JournalState, deps: DailyPassDeps): Pr
   return { nextState, result };
 }
 
-// --- Phase 3 helper: single-day processing + state advance -----------
-// Extracted from the Phase 3 for-loop to keep runDailyPass under
-// the sonarjs/cognitive-complexity threshold.
-
 interface ProcessDayInput {
   workspaceRoot: string;
   date: string;
@@ -244,11 +196,7 @@ async function processDayAndAdvance(input: ProcessDayInput): Promise<ProcessDayO
   };
 }
 
-// --- Phase 4 helper: memory extraction -------------------------------
-// Scan dirty-session excerpts for durable user facts and append new
-// ones to memory.md. Fire-and-forget: if extraction fails the daily
-// summaries are already written, so the pass is still useful.
-
+// Fire-and-forget: if memory extraction fails the daily summaries are already written, so the pass is still useful.
 async function maybeExtractMemory(
   perSessionExcerpts: ReadonlyMap<string, ReadonlyMap<string, SessionExcerpt>>,
   workspaceRoot: string,
@@ -277,24 +225,16 @@ async function maybeExtractMemory(
   }
 }
 
-// --- Phase 3 helper: per-day side-effecting pipeline ----------------
-
-// Discriminated return so `runDailyPass` can branch on outcome
-// without digging into null or throwing.
 export type DayOutcome =
   | { kind: "skipped"; reason: string }
   | {
       kind: "processed";
       topicsCreated: string[];
       topicsUpdated: string[];
-      // Union of created + updated — handed back so the caller
-      // can keep `newTopicsSeen` in sync without recomputing.
+      // Union of created + updated so the caller can keep newTopicsSeen in sync without recomputing.
       topicsTouched: string[];
     };
 
-// Run the archivist for one day and apply its output (daily
-// summary + topic updates). All filesystem writes land here so
-// `runDailyPass` stays branching-lean.
 async function processOneDay(
   workspaceRoot: string,
   date: string,
@@ -335,10 +275,7 @@ async function processOneDay(
   };
 }
 
-// Call the archivist summarizer and narrow its failure modes.
-// Returns null on recoverable failures (logged + skipped), throws
-// only for `ClaudeCliNotFoundError` which the outer runner uses to
-// disable the whole journal feature for the process lifetime.
+// Throws only for ClaudeCliNotFoundError (outer runner uses it to disable the whole journal feature for the process lifetime).
 async function callSummarizeForDay(date: string, input: DailyArchivistInput, summarize: Summarize): Promise<string | null> {
   try {
     return await summarize(DAILY_SYSTEM_PROMPT, buildDailyUserPrompt(input));
@@ -352,27 +289,16 @@ async function callSummarizeForDay(date: string, input: DailyArchivistInput, sum
   }
 }
 
-// Side-effecting wrapper: rewrite workspace-absolute links in the
-// archivist output relative to the daily summary's own location,
-// then write the file to disk. Factored out so the main loop's
-// body no longer contains path-math and I/O intermixed.
 async function writeDailySummaryForDate(workspaceRoot: string, date: string, rawMarkdown: string): Promise<void> {
-  // Rewrite any /workspace-absolute links in the archivist's output
-  // into true-relative links from the daily summary's location
-  // before writing to disk. Same treatment below for topic files.
+  // Rewrite /workspace-absolute links into true-relative links from the daily summary's location (same for topic files).
   const [yearPart, monthPart, dayPart] = date.split("-");
   const dailyFileWsPath = path.posix.join(WORKSPACE_DIRS.summaries, "daily", yearPart, monthPart, `${dayPart}.md`);
   const content = rewriteWorkspaceLinks(dailyFileWsPath, rawMarkdown);
   await writeDailySummary(date, content, workspaceRoot);
 }
 
-// Apply every topic update the archivist asked for, keeping the
-// in-memory `existingTopics` snapshot in sync so the next day in
-// this same pass sees fresh content. Mutates `existingTopics`.
-//
-// Per-update failures (EACCES, EIO, etc. surfaced by appendOrCreate)
-// are logged and skipped so a single broken topic file doesn't kill
-// the whole pass after days of progress have already been committed.
+// Mutates existingTopics so the next day in the same pass sees fresh content. Per-update failures are logged + skipped
+// so one broken topic file doesn't kill the whole pass after days of progress have already been committed.
 async function processTopicUpdatesForDay(
   workspaceRoot: string,
   updates: readonly TopicUpdate[],
@@ -397,9 +323,6 @@ async function processTopicUpdatesForDay(
   return { created, updated };
 }
 
-// Re-read the topic file fresh and upsert its snapshot into the
-// in-memory `existingTopics` list so the next day's archivist
-// call sees the latest content.
 async function refreshTopicSnapshot(workspaceRoot: string, slug: string, existingTopics: ExistingTopicSnapshot[]): Promise<void> {
   const newBody = await readTopicFile(slug, workspaceRoot);
   if (newBody === null) return;
@@ -409,11 +332,8 @@ async function refreshTopicSnapshot(workspaceRoot: string, slug: string, existin
   else existingTopics[idx] = snapshot;
 }
 
-// Persist the in-progress journal state after each day so a
-// mid-pass crash only costs the work written after the last
-// checkpoint. Write failures are logged but don't fail the pass —
-// the day's markdown is already on disk and the next run will
-// catch up.
+// Checkpoint state after each day so a mid-pass crash only costs work since the last write. Write failures don't fail
+// the pass — the day's markdown is already on disk and the next run catches up.
 async function persistStateAfterDay(workspaceRoot: string, state: JournalState, date: string): Promise<void> {
   try {
     await writeState(workspaceRoot, state);
@@ -425,17 +345,8 @@ async function persistStateAfterDay(workspaceRoot: string, state: JournalState,
   }
 }
 
-// --- Pure helpers (exported for unit tests) ------------------------
-
-// Bucket every session's per-date excerpts into a `dayBuckets`
-// map and a `sessionToDays` tracking map in one pass. Inputs are
-// the per-session excerpts loaded by `loadDirtySessionExcerpts`;
-// outputs are plain Maps the day loop can consume directly.
-//
-// `sessionToDays` is used later by `computeJustCompletedSessions`
-// to mark a session fully processed only after its last day has
-// been written. That's why both Maps are built here together —
-// they're two views of the same input and staying in sync matters.
+// dayBuckets and sessionToDays must stay in sync — sessionToDays drives "session fully processed only after its last
+// day has been written" downstream in computeJustCompletedSessions.
 export interface DayBucketsPlan {
   dayBuckets: Map<string, SessionExcerpt[]>;
   sessionToDays: Map<string, Set<string>>;
@@ -461,12 +372,8 @@ export function buildDayBuckets(perSessionExcerpts: ReadonlyMap<string, Readonly
   return { dayBuckets, sessionToDays };
 }
 
-// Apply the append-to-missing → create guard and canonicalise
-// the slug. The archivist occasionally asks to "append" to a
-// brand-new topic; silently promoting that to "create" removes a
+// The archivist occasionally asks to "append" to a brand-new topic; silently promoting that to "create" removes a
 // whole class of LLM mistakes without needing a schema rejection.
-// Also rewrites any workspace-absolute links in the body relative
-// to the target topic file's location.
 export function normalizeTopicAction(update: TopicUpdate, existingTopics: readonly ExistingTopicSnapshot[]): TopicUpdate {
   const canonicalSlug = slugify(update.slug);
   const exists = existingTopics.some((topic) => topic.slug === canonicalSlug);
@@ -478,29 +385,13 @@ export function normalizeTopicAction(update: TopicUpdate, existingTopics: readon
   };
 }
 
-// Parse an archivist raw output string into a validated
-// DailyArchivistOutput. Returns null when the JSON envelope is
-// missing or the shape doesn't match, so callers can treat it
-// as a skip reason without needing a separate `isValid` check.
-// Pure — combines `extractJsonObject` + `isDailyArchivistOutput`
-// behind a single gate.
 export function parseArchivistOutput(rawOutput: string): DailyArchivistOutput | null {
   const parsed = extractJsonObject(rawOutput);
   if (!isDailyArchivistOutput(parsed)) return null;
   return parsed;
 }
 
-// Decide which sessions have just completed their last pending
-// day, mutating `sessionToDays` to drop `date` from every entry
-// that touches it. Returns the `SessionFileMeta` records for the
-// freshly-completed sessions so the caller can feed them into
-// `applyProcessed`.
-//
-// A session is "complete" when its pending-days set, *after*
-// removing the current date, is empty. Sessions not in
-// `sessionToDays` (or not in `dirtyMetaById`) are silently
-// skipped — defensive against unexpected inputs, and the same
-// shape as the pre-refactor inline code.
+// Mutates sessionToDays. A session is "complete" when its pending-days set is empty AFTER removing the current date.
 export function computeJustCompletedSessions(
   date: string,
   excerpts: readonly SessionExcerpt[],
@@ -521,11 +412,6 @@ export function computeJustCompletedSessions(
   return justCompleted;
 }
 
-// Build the next JournalState from the previous one plus a batch
-// of just-completed sessions and the current view of known
-// topics. Tiny pure wrapper so the day loop has one place to
-// advance state instead of five-line spread literals scattered
-// through it.
 export function advanceJournalState(prev: JournalState, justCompleted: readonly SessionFileMeta[], newTopicsSeen: ReadonlySet<string>): JournalState {
   return {
     ...prev,
@@ -534,13 +420,7 @@ export function advanceJournalState(prev: JournalState, justCompleted: readonly
   };
 }
 
-// --- Filesystem helpers ---------------------------------------------
-
-// Load every dirty session's jsonl, bucket events by local-date,
-// and return the whole collection as a Map<sessionId, Map<date,
-// excerpt>>. Malformed sessions are logged and skipped so one
-// bad jsonl can't crash the pass. Returned shape is exactly what
-// `buildDayBuckets` wants as input.
+// Malformed sessions are logged and skipped so one bad jsonl can't crash the pass.
 async function loadDirtySessionExcerpts(chatDir: string, dirty: readonly string[], workspaceRoot: string): Promise<Map<string, Map<string, SessionExcerpt>>> {
   const perSession = new Map<string, Map<string, SessionExcerpt>>();
   for (const sessionId of dirty) {
@@ -593,10 +473,6 @@ async function loadSessionExcerptsByDate(chatDir: string, sessionId: string, wor
   return bucketParsedEvents(parsedEvents, sessionId, roleId, fallbackDate);
 }
 
-// Walk a jsonl string and return at most `maxEvents` parsed events
-// ready for bucketing. Skips blank lines, malformed JSON,
-// metadata entries, and anything `parseEntry` rejects. Pure —
-// exported so tests can exercise it with fabricated jsonl strings.
 export function parseJsonlEvents(raw: string, maxEvents: number): ParsedEntry[] {
   const events: ParsedEntry[] = [];
   for (const line of raw.split("\n")) {
@@ -610,14 +486,7 @@ export function parseJsonlEvents(raw: string, maxEvents: number): ParsedEntry[]
   return events;
 }
 
-// JSON.parse one jsonl line, guarding against blank lines,
-// malformed JSON, and any JSON value that isn't a plain object.
-// `JSON.parse` will happily return `null`, arrays, strings,
-// numbers, or booleans, none of which the downstream
-// `parseEntry` / `entryToExcerpt` functions can consume — and
-// `entry.type` on a `null` or primitive throws at runtime.
-// Returning `null` here collapses every invalid shape into the
-// same "skip this line" sentinel the caller already handles.
+// Reject non-object JSON (null, arrays, primitives) — entry.type would throw on them, and downstream parseEntry can't consume them.
 function parseJsonlLine(line: string): Record<string, unknown> | null {
   if (!line.trim()) return null;
   let parsed: unknown;
@@ -636,10 +505,7 @@ function isMetadataEntry(entry: Record<string, unknown>): boolean {
   return entry.type === EVENT_TYPES.sessionMeta || entry.type === EVENT_TYPES.claudeSessionId;
 }
 
-// Collect parsed events into per-date buckets using `fallbackDate`
-// for every event, since the legacy jsonl format has no per-event
-// timestamps. Extracted so the I/O-free bucket-building can be
-// reasoned about and unit-tested without a real jsonl file.
+// Uses fallbackDate for every event because the legacy jsonl format has no per-event timestamps.
 export function bucketParsedEvents(events: readonly ParsedEntry[], sessionId: string, roleId: string, fallbackDate: string): Map<string, SessionExcerpt> {
   const buckets = new Map<string, SessionExcerpt>();
   for (const parsed of events) {
@@ -666,13 +532,8 @@ async function readRoleIdFromMeta(sessionId: string, workspaceRoot: string): Pro
   return "unknown";
 }
 
-// Convert one jsonl entry into a flat excerpt the archivist can read,
-// plus any workspace-relative artifact paths the entry references.
-// Exported so tests can exercise it with fabricated entries.
 export interface ParsedEntry {
   excerpt: SessionEventExcerpt;
-  // 0+ workspace-relative artifact paths referenced by this entry.
-  // Used to build the ARTIFACTS REFERENCED prompt section.
   artifactPaths: string[];
 }
 
@@ -685,13 +546,11 @@ export function parseEntry(entry: Record<string, unknown>): ParsedEntry | null {
   };
 }
 
-// Legacy single-purpose form used by the existing unit tests.
-// Prefer `parseEntry` for code that also wants artifact paths.
+// Prefer parseEntry for code that also wants artifact paths; this form is kept for the existing unit tests.
 export function entryToExcerpt(entry: Record<string, unknown>): SessionEventExcerpt | null {
   const source = typeof entry.source === "string" ? entry.source : "unknown";
   const type = typeof entry.type === "string" ? entry.type : "unknown";
 
-  // text entries: {source, type: "text", message}
   if (type === EVENT_TYPES.text && typeof entry.message === "string") {
     return {
       source,
@@ -699,10 +558,7 @@ export function entryToExcerpt(entry: Record<string, unknown>): SessionEventExce
       content: truncate(entry.message, MAX_EVENT_CONTENT_CHARS),
     };
   }
-  // tool_result entries: {source: "tool", type: "tool_result", result: {toolName, message, ...}}
-  // `typeof null === "object"` so we must explicitly reject null
-  // to avoid a NullPointerException-style crash when accessing
-  // r.toolName below.
+  // typeof null === "object", so isRecord must reject null before accessing resultRecord.toolName below.
   if (type === EVENT_TYPES.toolResult && isRecord(entry.result)) {
     const resultRecord = entry.result as Record<string, unknown>;
     const toolName = typeof resultRecord.toolName === "string" ? resultRecord.toolName : "tool";
@@ -717,41 +573,32 @@ export function entryToExcerpt(entry: Record<string, unknown>): SessionEventExce
   return null;
 }
 
-// Pull workspace-relative artifact paths out of a jsonl entry. The
-// extraction is tool-aware: different plugins stash file paths in
-// different places inside their tool_result data. Exported for
-// tests.
+// Tool-aware extraction: different plugins stash file paths in different places inside tool_result data.
 export function extractArtifactPaths(entry: Record<string, unknown>): string[] {
   if (entry.type !== "tool_result") return [];
-  const result = entry.result;
+  const { result } = entry;
   if (!isRecord(result)) return [];
   const resultRecord = result as Record<string, unknown>;
-  const data = resultRecord.data;
+  const { data } = resultRecord;
   if (!isRecord(data)) return [];
   const dataRecord = data as Record<string, unknown>;
   const paths: string[] = [];
 
-  // Direct `filePath: string` — presentMulmoScript, presentHtml.
+  // presentMulmoScript / presentHtml expose filePath directly.
   if (typeof dataRecord.filePath === "string" && dataRecord.filePath.length > 0) {
     paths.push(dataRecord.filePath);
   }
 
-  // Wiki uses `pageName: string` and stores the page at
-  // `wiki/pages/<pageName>.md`. The plugin itself doesn't surface
-  // the full path in the result, so we synthesise it from the
-  // convention established in server/routes/wiki.ts.
+  // manageWiki only surfaces pageName; synthesise the path from the wiki/pages/<pageName>.md convention.
   if (resultRecord.toolName === "manageWiki" && typeof dataRecord.pageName === "string") {
     paths.push(`wiki/pages/${dataRecord.pageName}.md`);
   }
 
-  // Paths must be workspace-relative (not absolute, no escape).
-  // Drop anything suspicious rather than link to it.
   return paths.filter(isSafeWorkspacePath);
 }
 
-// Defensive: refuse absolute paths, parent-escapes, or scheme-like
-// strings. Protects against a malformed tool result wedging a
-// filesystem-absolute path into the archivist prompt.
+// Refuse absolute paths, parent-escapes, scheme-like strings — guards against a malformed tool result wedging an
+// absolute filesystem path into the archivist prompt.
 function isSafeWorkspacePath(candidatePath: string): boolean {
   if (!candidatePath) return false;
   if (candidatePath.startsWith("/")) return false;

package/server/workspace/journal/diff.ts

@@ -1,40 +1,18 @@
-// "Which sessions are new or have changed since the last journal
-// run?" — pure logic that takes in-memory representations of the
-// current filesystem and the persisted state, and returns the list
-// of session ids that need re-ingest.
-//
-// Extracted from the filesystem layer so tests can exercise it with
-// hand-rolled inputs instead of mocking `fs`.
-
 import type { JournalState, ProcessedSessionRecord } from "./state.js";
 
 export interface SessionFileMeta {
-  // Session id (matches the .jsonl filename without extension).
   id: string;
-  // mtime in ms since epoch. The only signal we use to detect
-  // appends — sessions don't have a version counter.
+  // mtime in ms — sessions have no version counter, so this is the only signal we have for "file changed".
   mtimeMs: number;
 }
 
 export interface DirtySessionDecision {
   dirty: string[];
-  // Sessions already in state whose files have vanished from disk.
-  // We keep them in the state record (no harm) but the caller may
-  // choose to prune them separately.
+  // Previously-processed sessions whose files have vanished — informational, not an error.
   missing: string[];
 }
 
-// Core diff. Given the current directory listing and the persisted
-// processed-sessions record, return:
-//   - `dirty`: sessions that were never seen, or whose mtime has
-//     advanced since we last ingested them, or whose mtime we don't
-//     have a record of (treat as dirty — safer to re-ingest than miss).
-//   - `missing`: sessions we had previously processed that no longer
-//     exist on disk. Not an error, just information.
-//
-// The caller may additionally exclude currently-active sessions
-// (whose jsonl could be mid-write); that's a separate concern and
-// kept out of the pure diff.
+// Treats unknown-mtime as dirty (safer to re-ingest than miss). Active mid-write sessions are filtered by the caller.
 export function findDirtySessions(current: readonly SessionFileMeta[], processed: Record<string, ProcessedSessionRecord>): DirtySessionDecision {
   const dirty: string[] = [];
   const seenNow = new Set<string>();
@@ -59,9 +37,6 @@ export function findDirtySessions(current: readonly SessionFileMeta[], processed
   return { dirty, missing };
 }
 
-// Produce the next processedSessions map after a successful ingest
-// of the given dirty ids. Pure — doesn't mutate input. Sessions not
-// in the dirty list keep their existing record.
 export function applyProcessed(previous: JournalState["processedSessions"], justProcessed: readonly SessionFileMeta[]): JournalState["processedSessions"] {
   const next: JournalState["processedSessions"] = { ...previous };
   for (const meta of justProcessed) {

package/server/workspace/journal/index.ts

@@ -1,50 +1,7 @@
-// Public entry point for the workspace journal. The agent route
-// calls `maybeRunJournal()` from its `finally` block — fire-and-
-// forget. This module decides whether a pass is actually due, holds
-// an in-process lock so concurrent sessions don't double-run,
-// orchestrates daily + optimization passes, and rebuilds _index.md.
-//
-// All failures are caught and logged here; nothing ever bubbles
-// back to the request handler.
-//
-// ── Architecture (#799) ──────────────────────────────────────────
-//
-// Two top-level passes hang off `maybeRunJournal()`, each with its
-// own cadence and its own state-machine slot. Memory extraction is
-// a sub-step of the daily pass, not a peer pipeline.
-//
-//   session-end
-//     │
-//     └─> maybeRunJournal()  [this file]
-//           │   gates by interval, holds the lock, traps errors
-//           │
-//           ├─> runDailyPass         (≥ 1 h since last)
-//           │     dailyPass.ts       finds new/changed sessions via
-//           │                        mtime, buckets events by local
-//           │                        date, calls `claude` CLI once
-//           │                        per day, writes daily summaries
-//           │                        + topics + state checkpoint.
-//           │     │
-//           │     │  early-returns when no dirty sessions; otherwise
-//           │     │  at the end of the per-day loop:
-//           │     │
-//           │     └─> extractAndAppendMemory
-//           │           memoryExtractor.ts  scans the day's new
-//           │                              daily file for memory-
-//           │                              worthy facts, appends to
-//           │                              the user's ~/.claude/
-//           │                              memory.md.
-//           │
-//           └─> runOptimizationPass  (≥ 7 d since last)
-//                 optimizationPass.ts reads existing topics, asks
-//                                    the LLM to merge duplicates /
-//                                    archive stale ones, writes back
-//                                    and updates archive/.
-//
-// _index.md is rebuilt at the end of every successful pass so the
-// UI's directory listing reflects whatever was just written.
-//
-// Audit + roadmap: `plans/audit-journal-subsystem.md` (#799).
+// Architecture (#799) — agent route calls maybeRunJournal() fire-and-forget from its finally block. The daily pass
+// (≥1h since last) walks chat/*.jsonl by mtime, buckets events by local date, writes daily summaries + topics, then
+// extractAndAppendMemory appends durable user facts to memory.md. The optimization pass (≥7d) merges/archives topics.
+// _index.md is rebuilt at the end of every successful pass. Roadmap: plans/audit-journal-subsystem.md.
 
 import { workspacePath as defaultWorkspacePath } from "../workspace.js";
 import {
@@ -64,42 +21,26 @@ import { log } from "../../system/logger/index.js";
 
 export { extractFirstH1 };
 
-// Module-level lock. A boolean is enough for the single-process
-// single-user MulmoClaude server; if two sessions finish at the
-// same instant, the second call returns immediately.
+// Single-process server, so a boolean is enough; a second concurrent call simply returns.
 let running = false;
 
-// Once we hit ENOENT on the `claude` CLI we disable the journal
-// for the rest of the server lifetime to avoid spamming warnings
-// on every session-end. Reset on server restart.
+// Latch off the journal for the rest of the process once the claude CLI is missing — avoids spamming on every session-end.
 let disabled = false;
 
-// Test-only reset for the module-level flags. The lock + disable
-// flags are intentionally module-scoped so a fresh server start
-// always begins from "neither running nor disabled"; a unit test
-// that exercises maybeRunJournal across multiple call sequences
-// needs a way to reproduce that fresh-start condition without
-// re-importing the module. Not exported via index — only consumers
-// importing this file directly should reach for it.
+// Reset module-level flags between unit-test runs without re-importing the module.
 export function __resetForTests(): void {
   running = false;
   disabled = false;
 }
 
-// The agent route calls this as `maybeRunJournal().catch(...)`.
 export interface MaybeRunJournalOptions {
   summarize?: Summarize;
   workspaceRoot?: string;
   activeSessionIds?: ReadonlySet<string>;
-  // Skip the interval check and run both passes unconditionally.
-  // Useful for debugging / CLI-driven manual runs — the feature's
-  // disable flags (claude CLI missing, in-process lock) still apply.
+  // Bypass the interval gate; the disable flags (CLI missing, in-process lock) still apply.
   force?: boolean;
 }
 
-// Everything inside swallows its own errors so the promise never
-// rejects in practice, but we still attach a catch at the call
-// site defensively.
 export async function maybeRunJournal(opts: MaybeRunJournalOptions = {}): Promise<void> {
   if (disabled) return;
   if (running) return;
@@ -128,9 +69,6 @@ async function runJournalPass(opts: MaybeRunJournalOptions): Promise<void> {
   const state = await readState(workspaceRoot);
   const now = Date.now();
 
-  // `force: true` bypasses the interval gate entirely so debug /
-  // startup flows can trigger a full pass even when nothing is
-  // technically due.
   const daily = opts.force === true || isDailyDue(state, now);
   const optimize = opts.force === true || isOptimizationDue(state, now);
   if (!daily && !optimize) return;
@@ -147,9 +85,7 @@ async function runJournalPass(opts: MaybeRunJournalOptions): Promise<void> {
       summarize,
       activeSessionIds,
     });
-    // Only advance lastDailyRunAt when no days were skipped —
-    // otherwise we'd wait a full interval before retrying a failed
-    // day, letting transient archivist failures silently lose events.
+    // Only bump lastDailyRunAt when no days were skipped — otherwise transient archivist failures silently lose events.
     nextState = {
       ...afterDaily,
       ...(result.skipped.length === 0 && {
@@ -168,11 +104,7 @@ async function runJournalPass(opts: MaybeRunJournalOptions): Promise<void> {
   if (optimize) {
     log.info("journal", "running optimization pass");
     const { nextState: afterOpt, result } = await runOptimizationPass(nextState, { workspaceRoot, summarize });
-    // Same rule as daily: only advance the timestamp when the pass
-    // actually ran to completion. A "skipped: too few topics" case
-    // is still considered successful — there was simply nothing to
-    // do — and we allow it to bump so we don't re-check on every
-    // session-end.
+    // Same rule as daily, except "fewer than 2 topics" is still success — bump so we don't re-check every session-end.
     const optimizationSucceeded = !result.skipped || result.skippedReason === "fewer than 2 topics";
     nextState = {
       ...afterOpt,
@@ -196,8 +128,6 @@ async function runJournalPass(opts: MaybeRunJournalOptions): Promise<void> {
   await writeState(workspaceRoot, nextState);
 }
 
-// --- Index rebuild -------------------------------------------------
-
 async function rebuildIndex(workspaceRoot: string): Promise<void> {
   const topics = await walkTopics(workspaceRoot);
   const dailyEntries = await listDailyFilesIO(workspaceRoot);
@@ -229,7 +159,6 @@ async function walkTopics(workspaceRoot: string): Promise<IndexTopicEntry[]> {
 
 const DAY_FILE_PATTERN = /^(\d{2})\.md$/;
 
-// Pure: returns the two-digit day if `name` matches `DD.md`, else null.
 export function parseDailyFilename(name: string): string | null {
   const match = DAY_FILE_PATTERN.exec(name);
   return match ? (match[1] ?? null) : null;