mulmoclaude 0.1.0

package/server/workspace/journal/diff.ts

@@ -0,0 +1,71 @@
+// "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.
+  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.
+  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.
+export function findDirtySessions(current: readonly SessionFileMeta[], processed: Record<string, ProcessedSessionRecord>): DirtySessionDecision {
+  const dirty: string[] = [];
+  const seenNow = new Set<string>();
+
+  for (const meta of current) {
+    seenNow.add(meta.id);
+    const prev = processed[meta.id];
+    if (!prev) {
+      dirty.push(meta.id);
+      continue;
+    }
+    if (meta.mtimeMs > prev.lastMtimeMs) {
+      dirty.push(meta.id);
+    }
+  }
+
+  const missing: string[] = [];
+  for (const id of Object.keys(processed)) {
+    if (!seenNow.has(id)) missing.push(id);
+  }
+
+  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) {
+    next[meta.id] = { lastMtimeMs: meta.mtimeMs };
+  }
+  return next;
+}

package/server/workspace/journal/index.ts

@@ -0,0 +1,185 @@
+// 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.
+
+import { workspacePath as defaultWorkspacePath } from "../workspace.js";
+import {
+  writeJournalIndex,
+  listTopicSlugs as listTopicSlugsIO,
+  readTopicFile,
+  listDailyFiles as listDailyFilesIO,
+  countArchivedTopics as countArchivedIO,
+} from "../../utils/files/journal-io.js";
+import { readState, writeState, isDailyDue, isOptimizationDue } from "./state.js";
+import { runDailyPass } from "./dailyPass.js";
+import { runOptimizationPass } from "./optimizationPass.js";
+import { buildIndexMarkdown, type IndexTopicEntry, type IndexDailyEntry } from "./indexFile.js";
+import { runClaudeCli, ClaudeCliNotFoundError, type Summarize } from "./archivist.js";
+import { extractFirstH1 } from "../../../src/utils/markdown/extractFirstH1.js";
+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.
+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.
+let 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.
+  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;
+  running = true;
+  try {
+    await runJournalPass(opts);
+  } catch (err) {
+    if (err instanceof ClaudeCliNotFoundError) {
+      disabled = true;
+      log.warn("journal", err.message);
+      return;
+    }
+    log.warn("journal", "unexpected failure, continuing", {
+      error: String(err),
+    });
+  } finally {
+    running = false;
+  }
+}
+
+async function runJournalPass(opts: MaybeRunJournalOptions): Promise<void> {
+  const workspaceRoot = opts.workspaceRoot ?? defaultWorkspacePath;
+  const summarize = opts.summarize ?? runClaudeCli;
+  const activeSessionIds = opts.activeSessionIds ?? new Set<string>();
+
+  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;
+  if (opts.force === true) {
+    log.info("journal", "force-run: skipping interval gates");
+  }
+
+  let nextState = state;
+
+  if (daily) {
+    log.info("journal", "running daily pass");
+    const { nextState: afterDaily, result } = await runDailyPass(nextState, {
+      workspaceRoot,
+      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.
+    nextState = {
+      ...afterDaily,
+      ...(result.skipped.length === 0 && {
+        lastDailyRunAt: new Date(now).toISOString(),
+      }),
+    };
+    log.info("journal", "daily pass done", {
+      sessions: result.sessionsIngested.length,
+      days: result.daysTouched.length,
+      topicsCreated: result.topicsCreated.length,
+      topicsUpdated: result.topicsUpdated.length,
+      daysSkipped: result.skipped.length,
+    });
+  }
+
+  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.
+    const optimizationSucceeded = !result.skipped || result.skippedReason === "fewer than 2 topics";
+    nextState = {
+      ...afterOpt,
+      ...(optimizationSucceeded && {
+        lastOptimizationRunAt: new Date(now).toISOString(),
+      }),
+    };
+    if (result.skipped) {
+      log.info("journal", "optimization pass skipped", {
+        reason: result.skippedReason,
+      });
+    } else {
+      log.info("journal", "optimization pass done", {
+        merged: result.mergedSlugs.length,
+        archived: result.archivedSlugs.length,
+      });
+    }
+  }
+
+  await rebuildIndex(workspaceRoot);
+  await writeState(workspaceRoot, nextState);
+}
+
+// --- Index rebuild -------------------------------------------------
+
+async function rebuildIndex(workspaceRoot: string): Promise<void> {
+  const topics = await walkTopics(workspaceRoot);
+  const dailyEntries = await listDailyFilesIO(workspaceRoot);
+  const days: IndexDailyEntry[] = dailyEntries.map((e) => ({
+    date: `${e.year}-${e.month}-${e.day}`,
+  }));
+  const archivedCount = await countArchivedIO(workspaceRoot);
+  const md = buildIndexMarkdown({
+    topics,
+    days,
+    archivedTopicCount: archivedCount,
+    builtAtIso: new Date().toISOString(),
+  });
+  await writeJournalIndex(md, workspaceRoot);
+}
+
+async function walkTopics(workspaceRoot: string): Promise<IndexTopicEntry[]> {
+  const slugs = await listTopicSlugsIO(workspaceRoot);
+  const out: IndexTopicEntry[] = [];
+  for (const slug of slugs) {
+    const content = await readTopicFile(slug, workspaceRoot);
+    out.push({
+      slug,
+      title: content ? (extractFirstH1(content) ?? undefined) : undefined,
+    });
+  }
+  return out;
+}
+
+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;
+}

package/server/workspace/journal/indexFile.ts

@@ -0,0 +1,136 @@
+// Pure builder for summaries/_index.md. Takes in-memory listings of
+// the journal's current topic / daily files and returns the full
+// markdown for the index. All filesystem walking happens in the
+// caller; this function is deterministic and easy to snapshot-test.
+
+import { isoDateOnly } from "../../utils/date.js";
+
+export interface IndexTopicEntry {
+  // Filesystem slug (matches topics/<slug>.md).
+  slug: string;
+  // Optional human-readable title extracted from the topic file's
+  // first H1 heading. Falls back to `slug` if absent so the index
+  // row always reads sensibly.
+  title?: string;
+  // ISO timestamp of the last write to the topic file. Rendered
+  // for "stale topic" visibility.
+  lastUpdatedIso?: string;
+}
+
+export interface IndexDailyEntry {
+  // YYYY-MM-DD in local time. Matches the folder layout.
+  date: string;
+}
+
+export interface IndexInputs {
+  topics: readonly IndexTopicEntry[];
+  days: readonly IndexDailyEntry[];
+  archivedTopicCount: number;
+  builtAtIso: string;
+  // How many "Recent days" rows to list before collapsing the
+  // remainder. The full listing still lives under daily/ on disk.
+  maxRecentDays?: number;
+}
+
+export const DEFAULT_MAX_RECENT_DAYS = 14;
+
+export function buildIndexMarkdown(input: IndexInputs): string {
+  const maxRecent = input.maxRecentDays ?? DEFAULT_MAX_RECENT_DAYS;
+  return [
+    "# Workspace Journal",
+    "",
+    `*Last updated: ${input.builtAtIso}*`,
+    "",
+    ...renderTopicsSection(input.topics),
+    "",
+    ...renderRecentDaysSection(input.days, maxRecent),
+    "",
+    ...renderArchiveSection(input.archivedTopicCount),
+    "",
+  ].join("\n");
+}
+
+export function renderTopicsSection(topics: readonly IndexTopicEntry[]): string[] {
+  const lines: string[] = ["## Topics", ""];
+  if (topics.length === 0) {
+    lines.push("_No topics yet._");
+    return lines;
+  }
+  // Newest-first by last update (topics with no timestamp sort
+  // last, ordered alphabetically among themselves for stability).
+  const sorted = [...topics].sort(compareTopicsNewestFirst);
+  for (const t of sorted) {
+    lines.push(renderTopicRow(t));
+  }
+  return lines;
+}
+
+export function renderRecentDaysSection(days: readonly IndexDailyEntry[], maxRecent: number): string[] {
+  const lines: string[] = ["## Recent days", ""];
+  if (days.length === 0) {
+    lines.push("_No daily entries yet._");
+    return lines;
+  }
+  // Newest-first by date string (YYYY-MM-DD sorts lexically).
+  const sorted = [...days].sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0));
+  const head = sorted.slice(0, maxRecent);
+  for (const d of head) {
+    lines.push(renderDailyRow(d));
+  }
+  const rest = sorted.length - head.length;
+  if (rest > 0) {
+    lines.push("");
+    lines.push(`_…and ${rest} earlier day${rest === 1 ? "" : "s"}._`);
+  }
+  return lines;
+}
+
+export function renderArchiveSection(archivedTopicCount: number): string[] {
+  const lines: string[] = ["## Archive", ""];
+  if (archivedTopicCount === 0) {
+    lines.push("_No archived topics._");
+    return lines;
+  }
+  const noun = archivedTopicCount === 1 ? "archived topic" : "archived topics";
+  lines.push(`- [Archived topics](archive/topics/) — ${archivedTopicCount} ${noun}`);
+  return lines;
+}
+
+// Parse an ISO timestamp into a numeric sort key. Invalid or missing
+// timestamps get -Infinity so they sort to the bottom (oldest).
+function topicSortKey(entry: IndexTopicEntry): number {
+  if (!entry.lastUpdatedIso) return -Infinity;
+  const ms = Date.parse(entry.lastUpdatedIso);
+  return Number.isNaN(ms) ? -Infinity : ms;
+}
+
+function compareBySlug(a: IndexTopicEntry, b: IndexTopicEntry): number {
+  if (a.slug < b.slug) return -1;
+  if (a.slug > b.slug) return 1;
+  return 0;
+}
+
+function compareTopicsNewestFirst(a: IndexTopicEntry, b: IndexTopicEntry): number {
+  const ak = topicSortKey(a);
+  const bk = topicSortKey(b);
+  // Both valid timestamps → compare numerically.
+  // One or both invalid (-Infinity) → valid wins; if both invalid,
+  // fall through to the slug tie-breaker.
+  const aValid = Number.isFinite(ak);
+  const bValid = Number.isFinite(bk);
+  if (aValid && bValid && bk !== ak) return bk - ak;
+  if (aValid !== bValid) return aValid ? -1 : 1;
+  // Tie-break on slug for determinism.
+  return compareBySlug(a, b);
+}
+
+function renderTopicRow(t: IndexTopicEntry): string {
+  const label = t.title && t.title.trim().length > 0 ? t.title : t.slug;
+  const stamp = t.lastUpdatedIso ? ` — updated ${isoDateOnly(t.lastUpdatedIso)}` : "";
+  return `- [${label}](topics/${t.slug}.md)${stamp}`;
+}
+
+function renderDailyRow(d: IndexDailyEntry): string {
+  const [year, month, day] = d.date.split("-");
+  return `- [${d.date}](daily/${year}/${month}/${day}.md)`;
+}

package/server/workspace/journal/linkRewrite.ts

@@ -0,0 +1,4 @@
+// Moved to server/utils/markdown.ts. Re-export for backwards
+// compatibility with existing callers in dailyPass.ts and
+// optimizationPass.ts.
+export { rewriteWorkspaceLinks, rewriteMarkdownLinks } from "../../utils/markdown.js";

package/server/workspace/journal/memoryExtractor.ts

@@ -0,0 +1,130 @@
+// Extracts durable user facts from chat session excerpts and
+// appends them to memory.md. Called at the end of the journal
+// daily pass so new facts are picked up even if the agent didn't
+// write them during the conversation.
+//
+// Only appends facts that aren't already in memory.md — the LLM
+// receives the current memory content as context and is instructed
+// to return ONLY new facts.
+
+import { readFileSync, existsSync } from "fs";
+import path from "path";
+import { WORKSPACE_FILES } from "../paths.js";
+import { writeFileAtomic } from "../../utils/files/atomic.js";
+import { log } from "../../system/logger/index.js";
+import { ClaudeCliNotFoundError } from "./archivist.js";
+
+const EXTRACTION_SYSTEM_PROMPT = `You are a personal-fact extractor. Given a batch of chat excerpts between a user and an AI assistant, extract ONLY durable facts about the USER — things that would still be true next week.
+
+Categories to look for:
+- Food preferences (likes, dislikes, allergies, diet)
+- Daily routines & habits (exercise, hobbies, recurring activities)
+- Possessions (car, devices, tools)
+- Family & pets (members, names, ages)
+- Location (city, commute, travel patterns)
+- Interests & hobbies (topics they follow, activities)
+- Schedule patterns (weekly meetings, monthly tasks)
+- Health (conditions, habits)
+- Work (job, role, company, work style)
+- Coding preferences (tools, conventions, style preferences)
+- Communication style (language, verbosity, formality)
+
+Rules:
+- Extract ONLY what the user explicitly stated — never infer or guess.
+- Each fact should be one concise bullet point.
+- If the user corrected a previous fact, output the corrected version only.
+- Do NOT extract facts about the AI, the app, or technical implementation details.
+- Do NOT extract ephemeral information (today's weather, a specific bug being debugged).
+- Output ONLY the bullet points, one per line, prefixed with "- ". No headers, no categories, no explanation.
+- If there are no new user facts, output exactly: NONE`;
+
+export interface MemoryExtractionDeps {
+  workspaceRoot: string;
+  /** The excerpts from today's dirty sessions, concatenated. */
+  excerpts: string;
+  /** Spawns claude CLI and returns stdout. Injectable for tests. */
+  summarize: (systemPrompt: string, userPrompt: string) => Promise<string>;
+}
+
+/**
+ * Extract new user facts from chat excerpts and append to memory.md.
+ * Returns the number of facts appended (0 if none found or on error).
+ */
+export async function extractAndAppendMemory(deps: MemoryExtractionDeps): Promise<number> {
+  const memoryPath = path.join(deps.workspaceRoot, WORKSPACE_FILES.memory);
+  const existingMemory = existsSync(memoryPath) ? readFileSync(memoryPath, "utf-8") : "";
+
+  const userPrompt = buildUserPrompt(existingMemory, deps.excerpts);
+  let raw: string;
+  try {
+    raw = await deps.summarize(EXTRACTION_SYSTEM_PROMPT, userPrompt);
+  } catch (err) {
+    if (err instanceof ClaudeCliNotFoundError) throw err;
+    log.warn("memory-extractor", "LLM call failed", {
+      error: String(err),
+    });
+    return 0;
+  }
+
+  const newFacts = parseExtractedFacts(raw);
+  if (newFacts.length === 0) return 0;
+
+  const factsToAppend = filterNewFacts(existingMemory, newFacts);
+  if (factsToAppend.length === 0) return 0;
+
+  const updatedContent = appendFacts(existingMemory, factsToAppend);
+  await writeFileAtomic(memoryPath, updatedContent);
+  log.info("memory-extractor", "appended new facts", {
+    count: factsToAppend.length,
+  });
+  return factsToAppend.length;
+}
+
+/** Build the user prompt with existing memory + new excerpts. */
+export function buildUserPrompt(existingMemory: string, excerpts: string): string {
+  const parts: string[] = [];
+  if (existingMemory.trim()) {
+    parts.push("## Already known (do NOT repeat these):\n\n" + existingMemory);
+  }
+  parts.push("## New chat excerpts:\n\n" + excerpts);
+  parts.push("\nExtract any NEW user facts not already in the 'Already known' section above. If none, output: NONE");
+  return parts.join("\n\n");
+}
+
+/** Parse LLM output into a list of fact strings. */
+export function parseExtractedFacts(raw: string): string[] {
+  const trimmed = raw.trim();
+  if (trimmed === "NONE" || trimmed === "") return [];
+  return trimmed
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith("- "))
+    .filter((line) => line.length > 3);
+}
+
+function normalizeFact(fact: string): string {
+  return fact.replace(/^- /, "").trim().toLowerCase();
+}
+
+/** Remove facts that already exist in the current memory content. */
+export function filterNewFacts(existingMemory: string, facts: readonly string[]): string[] {
+  const seen = new Set(parseExtractedFacts(existingMemory).map(normalizeFact));
+  const out: string[] = [];
+  for (const fact of facts) {
+    const key = normalizeFact(fact);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(fact);
+  }
+  return out;
+}
+
+/** Append facts to existing memory content. */
+export function appendFacts(existing: string, facts: string[]): string {
+  const trimmed = existing.trimEnd();
+  const factsBlock = facts.join("\n");
+  if (!trimmed) {
+    return `# Memory\n\nDistilled facts about you and your work.\n\n${factsBlock}\n`;
+  }
+  return `${trimmed}\n${factsBlock}\n`;
+}

package/server/workspace/journal/optimizationPass.ts

@@ -0,0 +1,160 @@
+// Weekly-ish topic optimization pass: merge near-duplicates, move
+// stale topics into archive/. Separate file from dailyPass so the
+// two can evolve independently and so the optimizer stays opt-in
+// from the top-level runner.
+
+import { workspacePath as defaultWorkspacePath } from "../workspace.js";
+import { writeTopicFile, readAllTopicFiles, archiveTopic } from "../../utils/files/journal-io.js";
+import {
+  type Summarize,
+  type OptimizationTopicSnapshot,
+  OPTIMIZATION_SYSTEM_PROMPT,
+  buildOptimizationUserPrompt,
+  extractJsonObject,
+  isOptimizationOutput,
+  ClaudeCliNotFoundError,
+} from "./archivist.js";
+import { slugify } from "./paths.js";
+import type { JournalState } from "./state.js";
+import { log } from "../../system/logger/index.js";
+
+// How many characters of each topic file we hand to the optimizer.
+// Enough to judge duplication without blowing up the prompt.
+const OPTIMIZER_HEAD_CHARS = 500;
+
+export interface OptimizationPassDeps {
+  workspaceRoot?: string;
+  summarize: Summarize;
+}
+
+export interface OptimizationPassResult {
+  mergedSlugs: string[];
+  archivedSlugs: string[];
+  skipped: boolean;
+  skippedReason?: string;
+}
+
+// Pure planner: turns the optimizer's raw merge instructions into a
+// concrete list of slug-level operations. Empty merges (where every
+// source resolves to the merge target itself) are dropped, and slugs
+// are normalized via slugify so the I/O layer never has to.
+export interface MergePlanItem {
+  intoSlug: string;
+  fromSlugs: string[];
+  newContent: string;
+}
+
+export interface RawMerge {
+  into: string;
+  from: string[];
+  newContent: string;
+}
+
+export function planMerges(merges: readonly RawMerge[]): MergePlanItem[] {
+  const plans: MergePlanItem[] = [];
+  for (const merge of merges) {
+    const intoSlug = slugify(merge.into);
+    const fromSlugs = merge.from.map(slugify).filter((s) => s !== intoSlug);
+    if (fromSlugs.length === 0) continue;
+    plans.push({ intoSlug, fromSlugs, newContent: merge.newContent });
+  }
+  return plans;
+}
+
+// Pure transform: returns the next JournalState with any slug in
+// `removed` filtered out of knownTopics.
+export function applyRemovedTopics(state: JournalState, removed: ReadonlySet<string>): JournalState {
+  return {
+    ...state,
+    knownTopics: state.knownTopics.filter((t) => !removed.has(t)),
+  };
+}
+
+async function executeMergePlans(workspaceRoot: string, plans: MergePlanItem[], removed: Set<string>, mergedSlugs: string[]): Promise<void> {
+  for (const plan of plans) {
+    await writeTopicFile(plan.intoSlug, plan.newContent, workspaceRoot);
+    for (const src of plan.fromSlugs) {
+      // Only record the merge as successful if the source file
+      // actually moved. If archiveTopic fails (missing file, IO
+      // error) we leave the source out of the removed set so the
+      // in-memory knownTopics state stays accurate.
+      if (!(await archiveTopic(src, workspaceRoot))) continue;
+      removed.add(src);
+      mergedSlugs.push(src);
+    }
+  }
+}
+
+async function executeArchives(workspaceRoot: string, rawSlugs: readonly string[], removed: Set<string>, archivedSlugs: string[]): Promise<void> {
+  for (const raw of rawSlugs) {
+    const slug = slugify(raw);
+    if (removed.has(slug)) continue;
+    if (!(await archiveTopic(slug, workspaceRoot))) continue;
+    removed.add(slug);
+    archivedSlugs.push(slug);
+  }
+}
+
+export async function runOptimizationPass(
+  state: JournalState,
+  deps: OptimizationPassDeps,
+): Promise<{ nextState: JournalState; result: OptimizationPassResult }> {
+  const workspaceRoot = deps.workspaceRoot ?? defaultWorkspacePath;
+  const result: OptimizationPassResult = {
+    mergedSlugs: [],
+    archivedSlugs: [],
+    skipped: false,
+  };
+
+  const topics = await loadTopicHeads(workspaceRoot);
+  if (topics.length < 2) {
+    // Nothing to optimise — need at least 2 topics for a merge to
+    // be meaningful, and archiving a single topic would leave an
+    // empty journal which feels wrong.
+    result.skipped = true;
+    result.skippedReason = "fewer than 2 topics";
+    return { nextState: { ...state }, result };
+  }
+
+  let raw: string;
+  try {
+    raw = await deps.summarize(OPTIMIZATION_SYSTEM_PROMPT, buildOptimizationUserPrompt({ topics }));
+  } catch (err) {
+    if (err instanceof ClaudeCliNotFoundError) throw err;
+    log.warn("journal", "optimization summarize failed", {
+      error: String(err),
+    });
+    result.skipped = true;
+    result.skippedReason = "summarize failed";
+    return { nextState: { ...state }, result };
+  }
+
+  const parsed = extractJsonObject(raw);
+  if (!isOptimizationOutput(parsed)) {
+    log.warn("journal", "optimizer returned unusable JSON, skipping");
+    result.skipped = true;
+    result.skippedReason = "unusable optimizer JSON";
+    return { nextState: { ...state }, result };
+  }
+
+  const removed = new Set<string>();
+
+  // Apply merges first, then archives (which skip slugs already
+  // removed by a merge).
+  await executeMergePlans(workspaceRoot, planMerges(parsed.merges), removed, result.mergedSlugs);
+  await executeArchives(workspaceRoot, parsed.archives, removed, result.archivedSlugs);
+
+  return { nextState: applyRemovedTopics(state, removed), result };
+}
+
+async function loadTopicHeads(workspaceRoot: string): Promise<OptimizationTopicSnapshot[]> {
+  const topicMap = await readAllTopicFiles(workspaceRoot);
+  const out: OptimizationTopicSnapshot[] = [];
+  for (const [slug, content] of topicMap) {
+    out.push({
+      slug,
+      headContent: content.slice(0, OPTIMIZER_HEAD_CHARS),
+    });
+  }
+  return out;
+}