clawvault 3.2.1 → 3.4.0

package/dist/chunk-D5U3Q4N5.js

@@ -0,0 +1,872 @@
+import {
+  requestLlmCompletion,
+  resolveLlmProvider
+} from "./chunk-DVOUSOR3.js";
+import {
+  readInboxItems
+} from "./chunk-2PKBIKDH.js";
+import {
+  buildHeuristicSurveyRecommendations,
+  classifyInboxItemHeuristic,
+  extractHeuristicInsights,
+  normalizeForDedup,
+  similarityScore
+} from "./chunk-35JCYSRR.js";
+import {
+  resolveVaultPath
+} from "./chunk-GJO3CFUN.js";
+
+// src/lib/maintenance/log.ts
+import * as fs from "fs";
+import * as path from "path";
+var MaintenanceLogger = class {
+  filePath;
+  runId;
+  dryRun;
+  constructor(vaultPath, runId, dryRun) {
+    this.filePath = path.join(path.resolve(vaultPath), ".clawvault", "maintenance-log.jsonl");
+    this.runId = runId;
+    this.dryRun = dryRun;
+    fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+  }
+  get path() {
+    return this.filePath;
+  }
+  append(worker, level, message, data) {
+    const event = {
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      runId: this.runId,
+      worker,
+      level,
+      message
+    };
+    if (data && Object.keys(data).length > 0) {
+      event.data = data;
+    }
+    if (this.dryRun) {
+      event.data = { ...event.data ?? {}, dryRun: true };
+    }
+    fs.appendFileSync(this.filePath, `${JSON.stringify(event)}
+`, "utf-8");
+  }
+};
+
+// src/lib/maintenance/llm.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+var VALID_PROVIDERS = ["anthropic", "openai", "gemini", "xai", "openclaw"];
+var VAULT_CONFIG_FILE = ".clawvault.json";
+function asProvider(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  return VALID_PROVIDERS.includes(value) ? value : null;
+}
+function readWorkerLlmOverrides(vaultPath) {
+  try {
+    const configPath = path2.join(path2.resolve(vaultPath), VAULT_CONFIG_FILE);
+    if (!fs2.existsSync(configPath)) {
+      return { provider: null, model: null };
+    }
+    const parsed = JSON.parse(fs2.readFileSync(configPath, "utf-8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { provider: null, model: null };
+    }
+    const observe = parsed.observe;
+    if (!observe || typeof observe !== "object" || Array.isArray(observe)) {
+      return { provider: null, model: null };
+    }
+    const record = observe;
+    const provider = asProvider(record.provider);
+    const model = typeof record.model === "string" && record.model.trim() ? record.model.trim() : null;
+    return { provider, model };
+  } catch {
+    return { provider: null, model: null };
+  }
+}
+function createWorkerLlmClient(vaultPath) {
+  if (process.env.CLAWVAULT_NO_LLM) {
+    return {
+      enabled: false,
+      provider: null,
+      model: null,
+      complete: async () => ""
+    };
+  }
+  const { provider: configuredProvider, model: configuredModel } = readWorkerLlmOverrides(vaultPath);
+  const resolvedProvider = configuredProvider ?? resolveLlmProvider();
+  const enabled = !!resolvedProvider;
+  return {
+    enabled,
+    provider: resolvedProvider,
+    model: configuredModel,
+    complete: async (systemPrompt, userPrompt, options = {}) => {
+      if (!enabled) {
+        return "";
+      }
+      try {
+        return await requestLlmCompletion({
+          provider: resolvedProvider,
+          model: options.model ?? configuredModel ?? void 0,
+          tier: options.tier ?? "default",
+          systemPrompt,
+          prompt: userPrompt,
+          temperature: 0.1,
+          maxTokens: 1200
+        });
+      } catch {
+        return "";
+      }
+    }
+  };
+}
+
+// src/lib/maintenance/state.ts
+import * as fs3 from "fs";
+import * as path3 from "path";
+
+// src/lib/maintenance/types.ts
+var MAINTENANCE_WORKERS = ["curator", "janitor", "distiller", "surveyor"];
+
+// src/lib/maintenance/state.ts
+var STATE_FILE = "maintenance-state.json";
+function defaultState() {
+  return {
+    version: 1,
+    workers: {
+      curator: { processedHashes: [] },
+      janitor: { processedHashes: [] },
+      distiller: { processedHashes: [] },
+      surveyor: { processedHashes: [] }
+    }
+  };
+}
+function statePath(vaultPath) {
+  return path3.join(path3.resolve(vaultPath), ".clawvault", STATE_FILE);
+}
+function readMaintenanceState(vaultPath) {
+  const filePath = statePath(vaultPath);
+  if (!fs3.existsSync(filePath)) {
+    return defaultState();
+  }
+  try {
+    const raw = JSON.parse(fs3.readFileSync(filePath, "utf-8"));
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      return defaultState();
+    }
+    const record = raw;
+    const next = defaultState();
+    for (const worker of MAINTENANCE_WORKERS) {
+      const candidate = record.workers?.[worker];
+      const hashes = Array.isArray(candidate?.processedHashes) ? candidate.processedHashes.filter((value) => typeof value === "string" && value.length > 0) : [];
+      next.workers[worker] = {
+        processedHashes: hashes,
+        updatedAt: typeof candidate?.updatedAt === "string" ? candidate.updatedAt : void 0
+      };
+    }
+    return next;
+  } catch {
+    return defaultState();
+  }
+}
+function writeMaintenanceState(vaultPath, state) {
+  const filePath = statePath(vaultPath);
+  fs3.mkdirSync(path3.dirname(filePath), { recursive: true });
+  fs3.writeFileSync(filePath, `${JSON.stringify(state, null, 2)}
+`, "utf-8");
+}
+
+// src/lib/maintenance/curator-worker.ts
+import * as path5 from "path";
+import matter from "gray-matter";
+
+// src/lib/maintenance/worker-utils.ts
+import * as fs4 from "fs";
+import * as path4 from "path";
+import { createHash } from "crypto";
+var CURATOR_SYSTEM_PROMPT = [
+  "You are Curator, a vault maintenance worker.",
+  "Classify each inbox capture into one destination category.",
+  "Return strict JSON only with shape:",
+  '{"routes":[{"hash":"...","category":"...","reason":"..."}]}'
+].join(" ");
+var JANITOR_SYSTEM_PROMPT = [
+  "You are Janitor, a vault hygiene worker.",
+  "Given dedupe/staleness metrics, propose concise cleanup recommendations.",
+  "Return plain text bullets."
+].join(" ");
+var DISTILLER_SYSTEM_PROMPT = [
+  "You are Distiller, a memory extraction worker.",
+  "Extract facts, decisions, and lessons from long-form captures.",
+  "Return strict JSON only with shape:",
+  '{"items":[{"hash":"...","facts":["..."],"decisions":["..."],"lessons":["..."]}]}'
+].join(" ");
+var SURVEYOR_SYSTEM_PROMPT = [
+  "You are Surveyor, a graph health worker.",
+  "Analyze vault metrics and suggest practical improvements.",
+  "Return plain text bullets."
+].join(" ");
+var CURATOR_ALLOWED_CATEGORIES = /* @__PURE__ */ new Set([
+  "rules",
+  "preferences",
+  "decisions",
+  "patterns",
+  "people",
+  "projects",
+  "goals",
+  "transcripts",
+  "inbox",
+  "facts",
+  "feelings",
+  "lessons",
+  "commitments",
+  "handoffs",
+  "research",
+  "agents"
+]);
+function truncate(text, max) {
+  if (text.length <= max) {
+    return text;
+  }
+  return `${text.slice(0, Math.max(0, max - 3))}...`;
+}
+function toRelative(vaultPath, filePath) {
+  return path4.relative(path4.resolve(vaultPath), filePath).replace(/\\/g, "/");
+}
+function extractJsonObject(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const codeBlockMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidate = codeBlockMatch ? codeBlockMatch[1].trim() : trimmed;
+  const firstBrace = candidate.indexOf("{");
+  const lastBrace = candidate.lastIndexOf("}");
+  if (firstBrace < 0 || lastBrace <= firstBrace) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(candidate.slice(firstBrace, lastBrace + 1));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function writeFileIfChanged(filePath, content, dryRun) {
+  const normalized = content.endsWith("\n") ? content : `${content}
+`;
+  if (fs4.existsSync(filePath)) {
+    const existing = fs4.readFileSync(filePath, "utf-8");
+    if (existing === normalized) {
+      return false;
+    }
+  }
+  if (!dryRun) {
+    fs4.mkdirSync(path4.dirname(filePath), { recursive: true });
+    fs4.writeFileSync(filePath, normalized, "utf-8");
+  }
+  return true;
+}
+function moveToArchive(sourcePath, archiveDir, dryRun) {
+  const baseName = path4.basename(sourcePath);
+  let destinationPath = path4.join(archiveDir, baseName);
+  let counter = 1;
+  while (fs4.existsSync(destinationPath)) {
+    const ext = path4.extname(baseName);
+    const stem = ext ? baseName.slice(0, -ext.length) : baseName;
+    destinationPath = path4.join(archiveDir, `${stem}-${counter}${ext}`);
+    counter += 1;
+  }
+  if (!dryRun) {
+    fs4.mkdirSync(archiveDir, { recursive: true });
+    fs4.renameSync(sourcePath, destinationPath);
+  }
+  return { moved: true, destinationPath };
+}
+function hashList(values) {
+  return createHash("sha256").update(values.join("|")).digest("hex");
+}
+function parseCuratorRoutes(raw) {
+  const parsed = extractJsonObject(raw);
+  const routesRaw = parsed?.routes;
+  if (!Array.isArray(routesRaw)) {
+    return /* @__PURE__ */ new Map();
+  }
+  const routes = /* @__PURE__ */ new Map();
+  for (const entry of routesRaw) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      continue;
+    }
+    const record = entry;
+    const hash = typeof record.hash === "string" ? record.hash.trim() : "";
+    const category = typeof record.category === "string" ? record.category.trim() : "";
+    if (!hash || !category || !CURATOR_ALLOWED_CATEGORIES.has(category)) {
+      continue;
+    }
+    routes.set(hash, category);
+  }
+  return routes;
+}
+function parseDistillerInsights(raw) {
+  const parsed = extractJsonObject(raw);
+  const itemsRaw = parsed?.items;
+  if (!Array.isArray(itemsRaw)) {
+    return /* @__PURE__ */ new Map();
+  }
+  const map = /* @__PURE__ */ new Map();
+  for (const entry of itemsRaw) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      continue;
+    }
+    const record = entry;
+    const hash = typeof record.hash === "string" ? record.hash.trim() : "";
+    if (!hash) {
+      continue;
+    }
+    const facts = Array.isArray(record.facts) ? record.facts.filter((value) => typeof value === "string" && value.trim().length > 0) : [];
+    const decisions = Array.isArray(record.decisions) ? record.decisions.filter((value) => typeof value === "string" && value.trim().length > 0) : [];
+    const lessons = Array.isArray(record.lessons) ? record.lessons.filter((value) => typeof value === "string" && value.trim().length > 0) : [];
+    map.set(hash, { facts, decisions, lessons });
+  }
+  return map;
+}
+function wordsCount(content) {
+  return content.trim().split(/\s+/).filter(Boolean).length;
+}
+function buildCuratorLlmPrompt(items) {
+  const payload = items.map((item) => ({
+    hash: item.hash,
+    title: item.title,
+    sample: truncate(item.content, 300)
+  }));
+  return [
+    "Classify each inbox item into a single category.",
+    `Allowed categories: ${[...CURATOR_ALLOWED_CATEGORIES].join(", ")}`,
+    "Return JSON only.",
+    JSON.stringify(payload, null, 2)
+  ].join("\n\n");
+}
+function buildDistillerLlmPrompt(items) {
+  const payload = items.map((item) => ({
+    hash: item.hash,
+    title: item.title,
+    content: truncate(item.content, 1800)
+  }));
+  return [
+    "Extract facts, decisions, and lessons for each item.",
+    "Return concise bullet-style statements and JSON only.",
+    JSON.stringify(payload, null, 2)
+  ].join("\n\n");
+}
+
+// src/lib/maintenance/curator-worker.ts
+function renderCuratedContent(item, now, category) {
+  const body = `${item.content.trim()}
+
+---
+Curated from \`${item.relativePath}\` by background curator.
+`;
+  return matter.stringify(body, {
+    title: item.title,
+    date: now.toISOString().split("T")[0],
+    source: "inbox",
+    inboxHash: item.hash,
+    inboxPath: item.relativePath,
+    curatedBy: "curator",
+    curatedCategory: category
+  });
+}
+async function runCuratorWorker(ctx, state, llm, logger) {
+  const items = readInboxItems(ctx.vaultPath, { limit: ctx.maxItems });
+  const processed = new Set(state.workers.curator.processedHashes);
+  const pending = items.filter((item) => !processed.has(item.hash));
+  let usedLlm = false;
+  let llmRoutes = /* @__PURE__ */ new Map();
+  if (pending.length > 0 && llm.enabled) {
+    const response = await llm.complete(
+      CURATOR_SYSTEM_PROMPT,
+      buildCuratorLlmPrompt(pending),
+      { tier: "background" }
+    );
+    if (response.trim()) {
+      llmRoutes = parseCuratorRoutes(response);
+      usedLlm = llmRoutes.size > 0;
+    }
+  }
+  const actions = [];
+  let processedCount = 0;
+  for (const item of pending) {
+    const category = llmRoutes.get(item.hash) ?? classifyInboxItemHeuristic(item);
+    const now = ctx.now();
+    const targetPath = path5.join(ctx.vaultPath, category, `inbox-${item.hash.slice(0, 12)}.md`);
+    const wrote = writeFileIfChanged(targetPath, renderCuratedContent(item, now, category), ctx.dryRun);
+    processed.add(item.hash);
+    processedCount += 1;
+    const action = `${item.relativePath} -> ${toRelative(ctx.vaultPath, targetPath)}${wrote ? "" : " (unchanged)"}`;
+    actions.push(action);
+    logger.append("curator", "info", "Curated inbox item", {
+      source: item.relativePath,
+      category,
+      target: toRelative(ctx.vaultPath, targetPath),
+      wrote
+    });
+  }
+  state.workers.curator.processedHashes = [...processed];
+  state.workers.curator.updatedAt = ctx.now().toISOString();
+  return {
+    worker: "curator",
+    processed: processedCount,
+    skipped: items.length - pending.length,
+    actions,
+    usedLlm,
+    degradedMode: !usedLlm
+  };
+}
+
+// src/lib/maintenance/janitor-worker.ts
+import * as path6 from "path";
+import matter2 from "gray-matter";
+function buildRelatedClusters(items) {
+  const clusters = [];
+  const used = /* @__PURE__ */ new Set();
+  for (let index = 0; index < items.length; index += 1) {
+    const seed = items[index];
+    if (used.has(seed.hash)) {
+      continue;
+    }
+    const clusterItems = [seed];
+    for (let cursor = index + 1; cursor < items.length; cursor += 1) {
+      const candidate = items[cursor];
+      if (used.has(candidate.hash)) {
+        continue;
+      }
+      const score = similarityScore(seed.content, candidate.content);
+      if (score >= 0.55) {
+        clusterItems.push(candidate);
+      }
+    }
+    if (clusterItems.length > 1) {
+      for (const item of clusterItems) {
+        used.add(item.hash);
+      }
+      const clusterId = hashList(clusterItems.map((item) => item.hash).sort()).slice(0, 12);
+      clusters.push({ id: clusterId, items: clusterItems.sort((left, right) => left.relativePath.localeCompare(right.relativePath)) });
+    }
+  }
+  return clusters;
+}
+function renderJanitorMergedCluster(cluster, now) {
+  const lines = cluster.items.map((item) => `- **${item.title}** (\`${item.relativePath}\`): ${truncate(item.content, 180)}`);
+  return matter2.stringify(
+    `## Related captures
+${lines.join("\n")}
+`,
+    {
+      title: `Merged inbox cluster ${cluster.id}`,
+      date: now.toISOString().split("T")[0],
+      type: "inbox-merge",
+      sources: cluster.items.map((item) => item.relativePath)
+    }
+  );
+}
+function renderJanitorReport(params) {
+  const recommendations = params.llmRecommendation.trim() ? params.llmRecommendation.trim() : "- Keep capture titles descriptive to improve curator routing quality.";
+  return [
+    `# Janitor report (${params.now.toISOString().split("T")[0]})`,
+    "",
+    `- Duplicates archived: ${params.duplicatesMoved}`,
+    `- Stale items archived: ${params.staleArchived}`,
+    `- Merged related clusters: ${params.mergedClusters}`,
+    "",
+    "## Recommendations",
+    recommendations
+  ].join("\n");
+}
+async function runJanitorWorker(ctx, state, llm, logger) {
+  const items = readInboxItems(ctx.vaultPath, { limit: ctx.maxItems });
+  const byNormalized = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const key = normalizeForDedup(item.content);
+    if (!key) {
+      continue;
+    }
+    const bucket = byNormalized.get(key) ?? [];
+    bucket.push(item);
+    byNormalized.set(key, bucket);
+  }
+  let duplicatesMoved = 0;
+  const actions = [];
+  for (const [, grouped] of byNormalized) {
+    if (grouped.length < 2) {
+      continue;
+    }
+    const sorted = [...grouped].sort((left, right) => left.capturedAt.getTime() - right.capturedAt.getTime());
+    for (const duplicate of sorted.slice(1)) {
+      const archiveDir = path6.join(ctx.vaultPath, "inbox", "archive", "deduped");
+      const moved = moveToArchive(duplicate.path, archiveDir, ctx.dryRun);
+      duplicatesMoved += 1;
+      actions.push(`Archived duplicate ${duplicate.relativePath} -> ${toRelative(ctx.vaultPath, moved.destinationPath)}`);
+      logger.append("janitor", "info", "Archived duplicate inbox capture", {
+        source: duplicate.relativePath,
+        target: toRelative(ctx.vaultPath, moved.destinationPath)
+      });
+    }
+  }
+  const refreshItems = readInboxItems(ctx.vaultPath, { limit: ctx.maxItems });
+  let staleArchived = 0;
+  const staleCutoffMs = ctx.now().getTime() - 30 * 24 * 60 * 60 * 1e3;
+  for (const item of refreshItems) {
+    if (item.capturedAt.getTime() >= staleCutoffMs) {
+      continue;
+    }
+    const archiveDir = path6.join(ctx.vaultPath, "inbox", "archive", "stale");
+    const moved = moveToArchive(item.path, archiveDir, ctx.dryRun);
+    staleArchived += 1;
+    actions.push(`Archived stale ${item.relativePath} -> ${toRelative(ctx.vaultPath, moved.destinationPath)}`);
+    logger.append("janitor", "info", "Archived stale inbox capture", {
+      source: item.relativePath,
+      target: toRelative(ctx.vaultPath, moved.destinationPath)
+    });
+  }
+  const postArchiveItems = readInboxItems(ctx.vaultPath, { limit: ctx.maxItems });
+  const clusters = buildRelatedClusters(postArchiveItems);
+  for (const cluster of clusters) {
+    const mergedPath = path6.join(ctx.vaultPath, "inbox", "merged", `merged-${cluster.id}.md`);
+    const wrote = writeFileIfChanged(mergedPath, renderJanitorMergedCluster(cluster, ctx.now()), ctx.dryRun);
+    actions.push(`${wrote ? "Updated" : "Kept"} merged cluster ${toRelative(ctx.vaultPath, mergedPath)}`);
+    logger.append("janitor", "info", "Updated merged inbox cluster", {
+      clusterId: cluster.id,
+      file: toRelative(ctx.vaultPath, mergedPath),
+      items: cluster.items.map((item) => item.relativePath)
+    });
+  }
+  let llmRecommendation = "";
+  let usedLlm = false;
+  if (llm.enabled) {
+    llmRecommendation = await llm.complete(
+      JANITOR_SYSTEM_PROMPT,
+      [
+        "Provide 2-4 concise hygiene recommendations.",
+        `duplicatesMoved=${duplicatesMoved}`,
+        `staleArchived=${staleArchived}`,
+        `mergedClusters=${clusters.length}`
+      ].join("\n"),
+      { tier: "background" }
+    );
+    usedLlm = llmRecommendation.trim().length > 0;
+  }
+  const reportPath = path6.join(ctx.vaultPath, ".clawvault", "maintenance", "janitor-report.md");
+  writeFileIfChanged(reportPath, renderJanitorReport({
+    now: ctx.now(),
+    duplicatesMoved,
+    staleArchived,
+    mergedClusters: clusters.length,
+    llmRecommendation
+  }), ctx.dryRun);
+  logger.append("janitor", "info", "Updated janitor report", {
+    report: toRelative(ctx.vaultPath, reportPath),
+    duplicatesMoved,
+    staleArchived,
+    mergedClusters: clusters.length
+  });
+  state.workers.janitor.updatedAt = ctx.now().toISOString();
+  return {
+    worker: "janitor",
+    processed: duplicatesMoved + staleArchived + clusters.length,
+    skipped: 0,
+    actions,
+    usedLlm,
+    degradedMode: !usedLlm
+  };
+}
+
+// src/lib/maintenance/distiller-worker.ts
+import * as path7 from "path";
+import matter3 from "gray-matter";
+function renderDistilledContent(item, now, sectionTitle, entries) {
+  const body = `## ${sectionTitle}
+${entries.map((line) => `- ${line}`).join("\n")}
+
+---
+Distilled from \`${item.relativePath}\`.
+`;
+  return matter3.stringify(body, {
+    title: `${sectionTitle} from ${item.title}`,
+    date: now.toISOString().split("T")[0],
+    source: "distiller",
+    inboxHash: item.hash,
+    inboxPath: item.relativePath
+  });
+}
+function writeDistilledEntries(ctx, item, category, sectionTitle, entries, logger, actions) {
+  if (entries.length === 0) {
+    return;
+  }
+  const filePath = path7.join(ctx.vaultPath, category, `distilled-${item.hash.slice(0, 12)}.md`);
+  const wrote = writeFileIfChanged(
+    filePath,
+    renderDistilledContent(item, ctx.now(), sectionTitle, entries),
+    ctx.dryRun
+  );
+  actions.push(`${wrote ? "Updated" : "Kept"} ${toRelative(ctx.vaultPath, filePath)}`);
+  logger.append("distiller", "info", "Updated distilled output", {
+    source: item.relativePath,
+    category,
+    target: toRelative(ctx.vaultPath, filePath),
+    entries: entries.length,
+    wrote
+  });
+}
+async function runDistillerWorker(ctx, state, llm, logger) {
+  const items = readInboxItems(ctx.vaultPath, { limit: ctx.maxItems });
+  const processed = new Set(state.workers.distiller.processedHashes);
+  const pending = items.filter((item) => !processed.has(item.hash));
+  const longForm = pending.filter((item) => wordsCount(item.content) >= 80);
+  let llmInsights = /* @__PURE__ */ new Map();
+  let usedLlm = false;
+  if (llm.enabled && longForm.length > 0) {
+    const response = await llm.complete(
+      DISTILLER_SYSTEM_PROMPT,
+      buildDistillerLlmPrompt(longForm),
+      { tier: "complex" }
+    );
+    if (response.trim()) {
+      llmInsights = parseDistillerInsights(response);
+      usedLlm = llmInsights.size > 0;
+    }
+  }
+  const actions = [];
+  let processedCount = 0;
+  for (const item of longForm) {
+    const insights = llmInsights.get(item.hash) ?? extractHeuristicInsights(item.content);
+    writeDistilledEntries(ctx, item, "facts", "Facts", insights.facts, logger, actions);
+    writeDistilledEntries(ctx, item, "decisions", "Decisions", insights.decisions, logger, actions);
+    writeDistilledEntries(ctx, item, "lessons", "Lessons", insights.lessons, logger, actions);
+    processed.add(item.hash);
+    processedCount += 1;
+  }
+  for (const item of pending) {
+    if (!processed.has(item.hash)) {
+      processed.add(item.hash);
+      logger.append("distiller", "info", "Skipped short-form inbox item", {
+        source: item.relativePath,
+        words: wordsCount(item.content)
+      });
+    }
+  }
+  state.workers.distiller.processedHashes = [...processed];
+  state.workers.distiller.updatedAt = ctx.now().toISOString();
+  return {
+    worker: "distiller",
+    processed: processedCount,
+    skipped: pending.length - processedCount + (items.length - pending.length),
+    actions,
+    usedLlm,
+    degradedMode: !usedLlm
+  };
+}
+
+// src/lib/maintenance/surveyor-worker.ts
+import * as fs5 from "fs";
+import * as path8 from "path";
+import { globSync } from "glob";
+function collectVaultSurvey(vaultPath) {
+  const docs = globSync("**/*.md", {
+    cwd: path8.resolve(vaultPath),
+    nodir: true,
+    absolute: true,
+    ignore: [".clawvault/**", "ledger/**", "node_modules/**"]
+  });
+  const categoryCounts = {};
+  let linkedDocs = 0;
+  for (const filePath of docs) {
+    const relativePath = toRelative(vaultPath, filePath);
+    const category = relativePath.split("/")[0] || "root";
+    categoryCounts[category] = (categoryCounts[category] ?? 0) + 1;
+    const content = fs5.readFileSync(filePath, "utf-8");
+    if (/\[\[[^\]]+\]\]/.test(content)) {
+      linkedDocs += 1;
+    }
+  }
+  const linkedRatio = docs.length === 0 ? 0 : linkedDocs / docs.length;
+  return {
+    totalDocs: docs.length,
+    linkedDocs,
+    linkedRatio,
+    categoryCounts
+  };
+}
+function renderSurveyorReport(params) {
+  const counts = Object.entries(params.survey.categoryCounts).sort((left, right) => right[1] - left[1]).map(([category, count]) => `- ${category}: ${count}`);
+  return [
+    `# Surveyor report (${params.now.toISOString().split("T")[0]})`,
+    "",
+    "## Vault health snapshot",
+    `- Total markdown docs: ${params.survey.totalDocs}`,
+    `- Linked docs: ${params.survey.linkedDocs}`,
+    `- Link coverage ratio: ${(params.survey.linkedRatio * 100).toFixed(1)}%`,
+    `- Inbox active captures: ${params.inboxCount}`,
+    "",
+    "## Category distribution",
+    ...counts.length > 0 ? counts : ["- No markdown categories found."],
+    "",
+    "## Recommendations",
+    ...params.recommendations.map((entry) => entry.startsWith("- ") ? entry : `- ${entry}`)
+  ].join("\n");
+}
+async function runSurveyorWorker(ctx, state, llm, logger) {
+  const survey = collectVaultSurvey(ctx.vaultPath);
+  const inboxCount = readInboxItems(ctx.vaultPath).length;
+  const heuristicRecommendations = buildHeuristicSurveyRecommendations({
+    inboxCount,
+    linkedRatio: survey.linkedRatio,
+    categoryCounts: survey.categoryCounts
+  });
+  let llmSuggestions = "";
+  let usedLlm = false;
+  if (llm.enabled) {
+    llmSuggestions = await llm.complete(
+      SURVEYOR_SYSTEM_PROMPT,
+      [
+        "Review this vault health summary and suggest 2-5 actionable improvements.",
+        JSON.stringify({
+          totalDocs: survey.totalDocs,
+          linkedDocs: survey.linkedDocs,
+          linkedRatio: survey.linkedRatio,
+          inboxCount,
+          categoryCounts: survey.categoryCounts
+        }, null, 2)
+      ].join("\n\n"),
+      { tier: "complex" }
+    );
+    usedLlm = llmSuggestions.trim().length > 0;
+  }
+  const recommendations = [...heuristicRecommendations];
+  if (llmSuggestions.trim()) {
+    const lines = llmSuggestions.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    recommendations.push(...lines);
+  }
+  const reportPath = path8.join(ctx.vaultPath, ".clawvault", "maintenance", "surveyor-report.md");
+  writeFileIfChanged(reportPath, renderSurveyorReport({
+    now: ctx.now(),
+    survey,
+    inboxCount,
+    recommendations
+  }), ctx.dryRun);
+  logger.append("surveyor", "info", "Updated surveyor report", {
+    report: toRelative(ctx.vaultPath, reportPath),
+    totalDocs: survey.totalDocs,
+    inboxCount
+  });
+  const snapshotHash = hashList([
+    String(survey.totalDocs),
+    String(survey.linkedDocs),
+    String(inboxCount),
+    JSON.stringify(survey.categoryCounts)
+  ]);
+  state.workers.surveyor.processedHashes = [snapshotHash];
+  state.workers.surveyor.updatedAt = ctx.now().toISOString();
+  return {
+    worker: "surveyor",
+    processed: 1,
+    skipped: 0,
+    actions: [`Updated ${toRelative(ctx.vaultPath, reportPath)}`],
+    usedLlm,
+    degradedMode: !usedLlm
+  };
+}
+
+// src/commands/maintain.ts
+function parseWorker(value) {
+  if (!value) {
+    return null;
+  }
+  return MAINTENANCE_WORKERS.includes(value) ? value : null;
+}
+function buildRunId(now) {
+  return `maint-${now.toISOString().replace(/[-:.]/g, "").replace("T", "t")}`;
+}
+async function maintainCommand(options = {}) {
+  const resolvedWorker = parseWorker(options.worker);
+  if (options.worker && !resolvedWorker) {
+    throw new Error(
+      `Unknown worker "${options.worker}". Expected one of: ${MAINTENANCE_WORKERS.join(", ")}`
+    );
+  }
+  const vaultPath = resolveVaultPath({ explicitPath: options.vaultPath });
+  const now = () => /* @__PURE__ */ new Date();
+  const started = now();
+  const runId = buildRunId(started);
+  const dryRun = options.dryRun ?? false;
+  const maxItems = typeof options.limit === "number" && Number.isFinite(options.limit) && options.limit > 0 ? Math.floor(options.limit) : void 0;
+  const state = readMaintenanceState(vaultPath);
+  const logger = new MaintenanceLogger(vaultPath, runId, dryRun);
+  const llm = createWorkerLlmClient(vaultPath);
+  const workerList = resolvedWorker ? [resolvedWorker] : [...MAINTENANCE_WORKERS];
+  const ctx = {
+    vaultPath,
+    runId,
+    now,
+    dryRun,
+    maxItems
+  };
+  const workers = [];
+  for (const worker of workerList) {
+    logger.append(worker, "info", "Worker started");
+    let result;
+    if (worker === "curator") {
+      result = await runCuratorWorker(ctx, state, llm, logger);
+    } else if (worker === "janitor") {
+      result = await runJanitorWorker(ctx, state, llm, logger);
+    } else if (worker === "distiller") {
+      result = await runDistillerWorker(ctx, state, llm, logger);
+    } else {
+      result = await runSurveyorWorker(ctx, state, llm, logger);
+    }
+    workers.push(result);
+    logger.append(worker, "info", "Worker completed", {
+      processed: result.processed,
+      skipped: result.skipped,
+      degradedMode: result.degradedMode
+    });
+  }
+  writeMaintenanceState(vaultPath, state);
+  const finishedAt = now().toISOString();
+  const summary = {
+    runId,
+    vaultPath,
+    startedAt: started.toISOString(),
+    finishedAt,
+    logPath: logger.path,
+    workers
+  };
+  if (!options.quiet) {
+    console.log(`Maintenance run: ${runId}`);
+    for (const worker of workers) {
+      const mode = worker.degradedMode ? "heuristic" : "llm";
+      console.log(
+        `- ${worker.worker}: processed=${worker.processed}, skipped=${worker.skipped}, mode=${mode}`
+      );
+    }
+    console.log(`Maintenance log: ${summary.logPath}`);
+  }
+  return summary;
+}
+function registerMaintainCommand(program) {
+  program.command("maintain").description("Run inbox maintenance workers (curator, janitor, distiller, surveyor)").option("--worker <name>", `Run a single worker: ${MAINTENANCE_WORKERS.join(", ")}`).option("--limit <n>", "Limit inbox items processed per worker", (value) => Number.parseInt(value, 10)).option("--dry-run", "Preview actions without writing files").option("-v, --vault <path>", "Vault path").action(async (rawOptions) => {
+    await maintainCommand({
+      vaultPath: rawOptions.vault,
+      worker: rawOptions.worker,
+      dryRun: rawOptions.dryRun,
+      limit: rawOptions.limit
+    });
+  });
+}
+
+export {
+  maintainCommand,
+  registerMaintainCommand
+};