@swarmvaultai/engine 0.6.4 → 0.6.6

package/dist/index.js

@@ -9,6 +9,7 @@ import {
   firstSentences,
   getProviderForTask,
   initWorkspace,
+  isPathWithin,
   listFilesRecursive,
   loadVaultConfig,
   normalizeWhitespace,
@@ -21,7 +22,7 @@ import {
   uniqueBy,
   writeFileIfChanged,
   writeJsonFile
-} from "./chunk-OK5752AP.js";
+} from "./chunk-HRRPWXRZ.js";
 
 // src/agents.ts
 import crypto from "crypto";
@@ -3869,8 +3870,31 @@ function interpreterFromShebang(content) {
   }
   return basename(parts[0] ?? "");
 }
-function isShellInterpreter(value) {
-  return value === "sh" || value === "bash" || value === "zsh";
+function languageFromInterpreter(interpreter) {
+  switch (interpreter) {
+    case "sh":
+    case "bash":
+    case "zsh":
+    case "dash":
+    case "ksh":
+    case "ash":
+      return "bash";
+    case "node":
+    case "nodejs":
+      return "javascript";
+    case "python":
+    case "python2":
+    case "python3":
+      return "python";
+    case "ruby":
+      return "ruby";
+    case "php":
+      return "php";
+    case "lua":
+      return "lua";
+    default:
+      return void 0;
+  }
 }
 function formatDiagnosticCategory(category) {
   switch (category) {
@@ -4472,8 +4496,11 @@ function inferCodeLanguage(filePath, mimeType = "", options = {}) {
   if ([".cc", ".cpp", ".cxx", ".h", ".hh", ".hpp", ".hxx"].includes(extension)) {
     return "cpp";
   }
-  if (!extension && options.executable && isShellInterpreter(interpreterFromShebang(options.content))) {
-    return "bash";
+  if (!extension && options.executable) {
+    const fromShebang = languageFromInterpreter(interpreterFromShebang(options.content));
+    if (fromShebang) {
+      return fromShebang;
+    }
   }
   return void 0;
 }
@@ -6583,7 +6610,7 @@ function inferKind(mimeType, filePath, detectionOptions = {}) {
   if (mimeType === "text/csv" || mimeType === "text/tab-separated-values" || filePath.toLowerCase().endsWith(".csv") || filePath.toLowerCase().endsWith(".tsv")) {
     return "csv";
   }
-  if (mimeType.startsWith("text/")) {
+  if (mimeType.startsWith("text/") || isStructuredTextMime(mimeType) || isKnownTextPath(filePath)) {
     return "text";
   }
   if (mimeType === "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" || filePath.toLowerCase().endsWith(".xlsx")) {
@@ -6597,6 +6624,26 @@ function inferKind(mimeType, filePath, detectionOptions = {}) {
   }
   return "binary";
 }
+function isStructuredTextMime(mimeType) {
+  switch (mimeType) {
+    case "application/json":
+    case "application/json5":
+    case "application/ld+json":
+    case "application/manifest+json":
+    case "application/xml":
+    case "application/toml":
+    case "application/yaml":
+    case "application/x-yaml":
+    case "application/javascript":
+    case "application/ecmascript":
+    case "application/typescript":
+    case "application/x-sh":
+    case "application/x-shellscript":
+      return true;
+    default:
+      return false;
+  }
+}
 async function localCodeDetectionOptions(absolutePath, payloadBytes) {
   if (path12.extname(absolutePath)) {
     return {};
@@ -6645,7 +6692,129 @@ function guessMimeType(target) {
   if (isRstFilePath(target)) {
     return "text/x-rst";
   }
-  return mime.lookup(target) || "application/octet-stream";
+  const extension = path12.extname(target).toLowerCase();
+  if (extension === ".ts" || extension === ".tsx" || extension === ".mts" || extension === ".cts") {
+    return "text/typescript";
+  }
+  const looked = mime.lookup(target);
+  if (looked) {
+    return looked;
+  }
+  if (isKnownTextPath(target)) {
+    return "text/plain";
+  }
+  return "application/octet-stream";
+}
+var KNOWN_TEXT_DOTFILE_NAMES = /* @__PURE__ */ new Set([
+  ".gitignore",
+  ".gitattributes",
+  ".gitkeep",
+  ".gitmodules",
+  ".editorconfig",
+  ".npmrc",
+  ".yarnrc",
+  ".prettierignore",
+  ".prettierrc",
+  ".dockerignore",
+  ".eslintignore",
+  ".eslintrc",
+  ".nvmrc",
+  ".node-version",
+  ".python-version",
+  ".ruby-version",
+  ".tool-versions"
+]);
+var KNOWN_TEXT_BASENAMES = /* @__PURE__ */ new Set([
+  "readme",
+  "license",
+  "licence",
+  "copying",
+  "unlicense",
+  "notice",
+  "authors",
+  "contributors",
+  "patents",
+  "maintainers",
+  "owners",
+  "codeowners",
+  "changelog",
+  "changes",
+  "history",
+  "news",
+  "todo",
+  "install",
+  "dockerfile",
+  "containerfile",
+  "makefile",
+  "gnumakefile",
+  "rakefile",
+  "gemfile",
+  "procfile",
+  "jenkinsfile",
+  "vagrantfile",
+  "brewfile",
+  "go.mod",
+  "go.sum",
+  "go.work",
+  "go.work.sum",
+  "cargo.lock",
+  "pipfile",
+  "pipfile.lock",
+  "poetry.lock",
+  "uv.lock",
+  "py.typed",
+  "package-lock.json",
+  "yarn.lock",
+  "pnpm-lock.yaml",
+  "composer.lock",
+  "requirements.txt"
+]);
+var KNOWN_TEXT_BASENAME_PREFIXES = ["license", "licence", "copying", "unlicense", "readme", "changelog", "dockerfile", "containerfile"];
+var KNOWN_TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".toml",
+  ".lock",
+  ".tmpl",
+  ".template",
+  ".mustache",
+  ".hbs",
+  ".handlebars",
+  ".ejs",
+  ".njk",
+  ".liquid",
+  ".vim",
+  ".typed",
+  ".env",
+  ".properties",
+  ".ini",
+  ".cfg",
+  ".conf",
+  ".config",
+  ".bazel",
+  ".bzl",
+  ".bat",
+  ".cmd"
+]);
+function isKnownTextPath(target) {
+  const basename = path12.basename(target).toLowerCase();
+  if (KNOWN_TEXT_DOTFILE_NAMES.has(basename)) {
+    return true;
+  }
+  if (basename === ".env" || basename.startsWith(".env.")) {
+    return true;
+  }
+  if (KNOWN_TEXT_BASENAMES.has(basename)) {
+    return true;
+  }
+  for (const prefix of KNOWN_TEXT_BASENAME_PREFIXES) {
+    if (basename === prefix || basename.startsWith(`${prefix}-`) || basename.startsWith(`${prefix}.`)) {
+      return true;
+    }
+  }
+  const extension = path12.extname(target).toLowerCase();
+  if (extension && KNOWN_TEXT_EXTENSIONS.has(extension)) {
+    return true;
+  }
+  return false;
 }
 function sourceGroupIdFor(prepared) {
   const originKey = prepared.originType === "url" ? prepared.url ?? prepared.title : prepared.originalPath ?? prepared.title;
@@ -8564,7 +8733,7 @@ async function collectInboxAttachmentRefs(inputDir, files) {
     const sourceRefs = [];
     for (const ref of refs) {
       const resolved = path12.resolve(path12.dirname(absolutePath), ref);
-      if (!resolved.startsWith(inputDir) || !await fileExists(resolved)) {
+      if (!isPathWithin(inputDir, resolved) || !await fileExists(resolved)) {
         continue;
       }
       sourceRefs.push({
@@ -9099,6 +9268,7 @@ import { z as z7 } from "zod";
 
 // src/analysis.ts
 import path14 from "path";
+import { fromMarkdown } from "mdast-util-from-markdown";
 import { z as z2 } from "zod";
 var ANALYSIS_FORMAT_VERSION = 7;
 var sourceAnalysisSchema = z2.object({
@@ -9158,6 +9328,12 @@ var STOPWORDS = /* @__PURE__ */ new Set([
   "would",
   "your"
 ]);
+var HEURISTIC_SECTION_SOURCE_KINDS = /* @__PURE__ */ new Map([
+  ["transcript", "Transcript"],
+  ["chat_export", "Messages"],
+  ["email", "Message"],
+  ["calendar", "Description"]
+]);
 function extractTopTerms(text, count) {
   const frequency = /* @__PURE__ */ new Map();
   for (const token of text.toLowerCase().match(/[a-z][a-z0-9-]{3,}/g) ?? []) {
@@ -9184,18 +9360,112 @@ function detectPolarity(text) {
   }
   return "neutral";
 }
-function deriveTitle(manifest, text) {
-  const heading = text.match(/^#\s+(.+)$/m)?.[1]?.trim();
-  return heading || manifest.title;
+function parseMarkdownNodes(text) {
+  try {
+    const root = fromMarkdown(text);
+    return Array.isArray(root.children) ? root.children : [];
+  } catch {
+    return [];
+  }
+}
+function markdownNodeText(node) {
+  if (node.type === "text" || node.type === "inlineCode" || node.type === "code") {
+    return normalizeWhitespace(node.value ?? "");
+  }
+  if (node.type === "image") {
+    return normalizeWhitespace(node.alt ?? "");
+  }
+  if (node.type === "break" || node.type === "thematicBreak") {
+    return " ";
+  }
+  return normalizeWhitespace((node.children ?? []).map((child) => markdownNodeText(child)).join(" "));
+}
+function markdownNodesText(nodes) {
+  return normalizeWhitespace(nodes.map((node) => markdownNodeText(node)).join("\n"));
+}
+function stripLeadingTitleNodes(nodes, title) {
+  const normalizedTitle = normalizeWhitespace(title);
+  if (!normalizedTitle || !nodes.length) {
+    return nodes;
+  }
+  for (let index = 0; index < nodes.length; index += 1) {
+    const node = nodes[index];
+    if (!node) {
+      continue;
+    }
+    const nodeText2 = markdownNodeText(node);
+    if (node.type === "heading" && node.depth === 1 && nodeText2 === normalizedTitle) {
+      return nodes.slice(index + 1);
+    }
+    if (node.type === "paragraph" && nodeText2 === normalizedTitle) {
+      return nodes.slice(index + 1);
+    }
+    return nodes;
+  }
+  return nodes;
+}
+function markdownSectionNodes(nodes, heading) {
+  const normalizedHeading = normalizeWhitespace(heading);
+  for (let index = 0; index < nodes.length; index += 1) {
+    const node = nodes[index];
+    if (node?.type !== "heading" || node.depth !== 2) {
+      continue;
+    }
+    if (markdownNodeText(node) !== normalizedHeading) {
+      continue;
+    }
+    const sectionNodes = [];
+    for (let cursor = index + 1; cursor < nodes.length; cursor += 1) {
+      const candidate = nodes[cursor];
+      if (candidate?.type === "heading" && typeof candidate.depth === "number" && candidate.depth <= 2) {
+        break;
+      }
+      if (candidate) {
+        sectionNodes.push(candidate);
+      }
+    }
+    return sectionNodes;
+  }
+  return [];
+}
+function textForHeuristicAnalysis(manifest, text) {
+  const nodes = parseMarkdownNodes(text);
+  if (!nodes.length) {
+    return normalizeWhitespace(text);
+  }
+  const sectionHeading = HEURISTIC_SECTION_SOURCE_KINDS.get(manifest.sourceKind);
+  const scopedNodes = sectionHeading ? markdownSectionNodes(nodes, sectionHeading) : nodes;
+  const relevantNodes = scopedNodes.length ? scopedNodes : nodes;
+  const contentNodes = stripLeadingTitleNodes(relevantNodes, manifest.title);
+  const normalized = markdownNodesText(contentNodes.length ? contentNodes : relevantNodes);
+  return normalized || normalizeWhitespace(text);
+}
+function normalizeAnalysisTitle(manifest, candidate) {
+  if (manifest.sourceKind !== "code") {
+    return manifest.title;
+  }
+  const normalized = normalizeWhitespace(candidate.replace(/^#+\s+/, ""));
+  if (!normalized) {
+    return manifest.title;
+  }
+  if (normalized.length > 140 || normalized.includes(" ## ")) {
+    return manifest.title;
+  }
+  return normalized;
+}
+function normalizeSourceAnalysis(manifest, analysis) {
+  const title = normalizeAnalysisTitle(manifest, analysis.title);
+  return title === analysis.title ? analysis : { ...analysis, title };
 }
 function heuristicAnalysis(manifest, text, schemaHash) {
-  const normalized = normalizeWhitespace(text);
+  const analysisText = textForHeuristicAnalysis(manifest, text);
+  const normalized = normalizeWhitespace(analysisText);
   const concepts = extractTopTerms(normalized, 6).map((term) => ({
     id: `concept:${slugify(term)}`,
     name: term,
     description: `Frequently referenced concept in ${manifest.title}.`
   }));
-  const entities = extractEntities(text, 6).map((term) => ({
+  const entities = extractEntities(analysisText, 6).map((term) => ({
     id: `entity:${slugify(term)}`,
     name: term,
     description: `Named entity mentioned in ${manifest.title}.`
@@ -9208,7 +9478,7 @@ function heuristicAnalysis(manifest, text, schemaHash) {
     semanticHash: manifest.semanticHash,
     extractionHash: manifest.extractionHash,
     schemaHash,
-    title: deriveTitle(manifest, text),
+    title: manifest.title,
     summary: firstSentences(normalized, 3) || truncate(normalized, 280) || `Imported ${manifest.sourceKind} source.`,
     concepts,
     entities,
@@ -9333,7 +9603,11 @@ async function analyzeSource(manifest, extractedText, provider, paths, schema) {
   const cachePath = path14.join(paths.analysesDir, `${manifest.sourceId}.json`);
   const cached = await readJsonFile(cachePath);
   if (cached && cached.analysisVersion === ANALYSIS_FORMAT_VERSION && (cached.semanticHash ?? cached.sourceHash) === manifest.semanticHash && cached.extractionHash === manifest.extractionHash && cached.schemaHash === schema.hash) {
-    return cached;
+    const normalizedCached = normalizeSourceAnalysis(manifest, cached);
+    if (normalizedCached !== cached) {
+      await writeJsonFile(cachePath, normalizedCached);
+    }
+    return normalizedCached;
   }
   const extraction = await readExtractionArtifact(paths.rootDir, manifest);
   const content = normalizeWhitespace(extractedText ?? "");
@@ -9398,8 +9672,9 @@ async function analyzeSource(manifest, extractedText, provider, paths, schema) {
       analysis = heuristicAnalysis(manifest, content, schema.hash);
     }
   }
-  await writeJsonFile(cachePath, analysis);
-  return analysis;
+  const normalized = normalizeSourceAnalysis(manifest, analysis);
+  await writeJsonFile(cachePath, normalized);
+  return normalized;
 }
 function analysisSignature(analysis) {
   return sha256(JSON.stringify(analysis));
@@ -13486,7 +13761,7 @@ async function resolveImageGenerationProvider(rootDir) {
   if (!providerConfig) {
     throw new Error(`No provider configured with id "${preferredProviderId}" for task "imageProvider".`);
   }
-  const { createProvider: createProvider2 } = await import("./registry-TYROWPR5.js");
+  const { createProvider: createProvider2 } = await import("./registry-NBLIJHZT.js");
   return createProvider2(preferredProviderId, providerConfig, rootDir);
 }
 async function generateOutputArtifacts(rootDir, input) {
@@ -17525,9 +17800,16 @@ async function listPages(rootDir) {
   return graph?.pages ?? [];
 }
 async function readPage(rootDir, relativePath) {
+  if (!relativePath) {
+    return null;
+  }
   const { paths } = await loadVaultConfig(rootDir);
   const absolutePath = path23.resolve(paths.wikiDir, relativePath);
-  if (!absolutePath.startsWith(paths.wikiDir) || !await fileExists(absolutePath)) {
+  if (!isPathWithin(paths.wikiDir, absolutePath)) {
+    return null;
+  }
+  const stats = await fs19.stat(absolutePath).catch(() => null);
+  if (!stats?.isFile()) {
     return null;
   }
   const raw = await fs19.readFile(absolutePath, "utf8");
@@ -17556,6 +17838,28 @@ async function getWorkspaceInfo(rootDir) {
     pageCount: pages.length
   };
 }
+function extractClaimSectionLines(content) {
+  const lines = content.split("\n");
+  let inClaims = false;
+  let found = false;
+  const claimLines = [];
+  for (const line of lines) {
+    const trimmed = line.trimEnd();
+    if (trimmed === "## Claims") {
+      inClaims = true;
+      found = true;
+      continue;
+    }
+    if (inClaims) {
+      if (/^#{1,2}\s/.test(trimmed)) {
+        inClaims = false;
+        continue;
+      }
+      claimLines.push(line);
+    }
+  }
+  return found ? claimLines : null;
+}
 function structuralLintFindings(_rootDir, paths, graph, schemas, manifests, sourceProjects) {
   const manifestMap = new Map(manifests.map((manifest) => [manifest.sourceId, manifest]));
   const pageMap2 = new Map(graph.pages.map((page) => [page.id, page]));
@@ -17601,8 +17905,9 @@ function structuralLintFindings(_rootDir, paths, graph, schemas, manifests, sour
       const absolutePath = path23.join(paths.wikiDir, page.path);
       if (await fileExists(absolutePath)) {
         const content = await fs19.readFile(absolutePath, "utf8");
-        if (content.includes("## Claims")) {
-          const uncited = content.split("\n").filter((line) => line.startsWith("- ") && !line.includes("[source:"));
+        const claimLines = extractClaimSectionLines(content);
+        if (claimLines !== null) {
+          const uncited = claimLines.filter((line) => line.startsWith("- ") && !line.includes("[source:"));
           if (uncited.length) {
             findings.push({
               severity: "warning",
@@ -17717,7 +18022,7 @@ async function bootstrapDemo(rootDir, input) {
 }
 
 // src/mcp.ts
-var SERVER_VERSION = "0.6.4";
+var SERVER_VERSION = "0.6.6";
 async function createMcpServer(rootDir) {
   const server = new McpServer({
     name: "swarmvault",
@@ -18052,7 +18357,7 @@ async function createMcpServer(rootDir) {
       const encodedPath = typeof variables.path === "string" ? variables.path : "";
       const relativePath = decodeURIComponent(encodedPath);
       const absolutePath = path24.resolve(paths.sessionsDir, relativePath);
-      if (!absolutePath.startsWith(paths.sessionsDir) || !await fileExists(absolutePath)) {
+      if (!isPathWithin(paths.sessionsDir, absolutePath) || !await fileExists(absolutePath)) {
         return asTextResource(`swarmvault://sessions/${encodedPath}`, `Session not found: ${relativePath}`);
       }
       return asTextResource(`swarmvault://sessions/${encodedPath}`, await fs20.readFile(absolutePath, "utf8"));
@@ -18391,6 +18696,15 @@ var DOCS_HINT_SEGMENTS = /* @__PURE__ */ new Set([
 function uniqueStrings4(values) {
   return uniqueBy(values.filter(Boolean), (value) => value);
 }
+function sourceOutputSchemaHash(schemas, projectIds) {
+  if (!projectIds.length) {
+    return schemas.effective.global.hash;
+  }
+  return composeVaultSchema(
+    schemas.root,
+    uniqueStrings4([...projectIds].sort((left, right) => left.localeCompare(right))).map((projectId) => schemas.projects[projectId]).filter((schema) => Boolean(schema?.hash))
+  ).hash;
+}
 function normalizeManagedStatus(value) {
   return value === "missing" || value === "error" ? value : "ready";
 }
@@ -18974,6 +19288,7 @@ async function writeSourceBriefForScope(rootDir, source) {
     return null;
   }
   const graph = await readJsonFile(paths.graphPath);
+  const schemas = await loadVaultSchemas(rootDir);
   const relatedPages = graph ? scopedSourcePages(graph, source.sourceIds) : [];
   const relatedPageIds = relatedPages.slice(0, 12).map((page) => page.id);
   const relatedNodeIds = graph ? scopedNodeIds(graph, source.sourceIds).slice(0, 20) : [];
@@ -18984,7 +19299,7 @@ async function writeSourceBriefForScope(rootDir, source) {
     question: `Brief ${source.title}`,
     answer: markdown,
     citations: source.sourceIds,
-    schemaHash: graph?.generatedAt ?? "",
+    schemaHash: sourceOutputSchemaHash(schemas, projectIds),
     outputFormat: "report",
     relatedPageIds,
     relatedNodeIds,
@@ -19219,6 +19534,7 @@ async function buildSourceReviewStagedPage(rootDir, scope) {
     throw new Error(`Could not generate a source review for ${scope.id}.`);
   }
   const graph = await readJsonFile(paths.graphPath);
+  const schemas = await loadVaultSchemas(rootDir);
   const scopeManifests = manifestsForScope(graph, scope);
   const relatedPages = graph ? scopedSourcePages(graph, scope.sourceIds) : [];
   const relatedPageIds = relatedPages.slice(0, 16).map((page) => page.id);
@@ -19230,7 +19546,7 @@ async function buildSourceReviewStagedPage(rootDir, scope) {
     question: `Review ${scope.title}`,
     answer: markdown,
     citations: scope.sourceIds,
-    schemaHash: graph?.generatedAt ?? "",
+    schemaHash: sourceOutputSchemaHash(schemas, projectIds),
     outputFormat: "report",
     relatedPageIds,
     relatedNodeIds,
@@ -19464,6 +19780,7 @@ async function buildSourceGuideStagedPage(rootDir, scope) {
     throw new Error(`Could not generate a source guide for ${scope.id}.`);
   }
   const graph = await readJsonFile(paths.graphPath);
+  const schemas = await loadVaultSchemas(rootDir);
   const scopeManifests = manifestsForScope(graph, scope);
   const relatedPages = graph ? scopedSourcePages(graph, scope.sourceIds) : [];
   const contradictions = findContradictionsForScope(scope, await readGraphReport(rootDir));
@@ -19477,7 +19794,7 @@ async function buildSourceGuideStagedPage(rootDir, scope) {
     question: `Guide ${scope.title}`,
     answer: markdown,
     citations: scope.sourceIds,
-    schemaHash: graph?.generatedAt ?? "",
+    schemaHash: sourceOutputSchemaHash(schemas, projectIds),
     outputFormat: "report",
     relatedPageIds,
     relatedNodeIds,
@@ -19566,6 +19883,7 @@ async function buildSourceSessionSavedPage(rootDir, scope, session) {
     await compileVault(rootDir, {});
     graph = await readJsonFile(paths.graphPath);
   }
+  const schemas = await loadVaultSchemas(rootDir);
   const scopeManifests = manifestsForScope(graph, scope);
   const sourcePages = graph ? scopedSourcePages(graph, scope.sourceIds) : [];
   const analyses = await loadSourceAnalyses(rootDir, scope.sourceIds);
@@ -19631,7 +19949,7 @@ async function buildSourceSessionSavedPage(rootDir, scope, session) {
     question: `Guided Session ${scope.title}`,
     answer: sessionMarkdown,
     citations: scope.sourceIds,
-    schemaHash: graph?.generatedAt ?? "",
+    schemaHash: sourceOutputSchemaHash(schemas, projectIds),
     outputFormat: "report",
     relatedPageIds,
     relatedNodeIds,
@@ -19984,6 +20302,15 @@ async function resumeSourceSession(rootDir, id, options = {}) {
 function shouldCompile(changedSources, graphExists, compileRequested) {
   return compileRequested && (!graphExists || changedSources.length > 0);
 }
+async function shouldRefreshBriefForManagedSource(source, options) {
+  if (options.compilePerformed || options.changed) {
+    return true;
+  }
+  if (!source.briefPath) {
+    return true;
+  }
+  return !await fileExists(source.briefPath);
+}
 async function listManagedSourceRecords(rootDir) {
   await ensureManagedSourcesArtifact(rootDir);
   return await loadManagedSources(rootDir);
@@ -20015,12 +20342,15 @@ async function addManagedSource(rootDir, input, options = {}) {
   }
   const graphExists = await loadVaultConfig(rootDir).then(({ paths }) => fileExists(paths.graphPath));
   let compile;
-  if (shouldCompile([synced], graphExists, compileRequested)) {
+  if (shouldCompile(synced.changed ? [synced] : [], graphExists, compileRequested)) {
     compile = await compileVault(rootDir, {});
   }
   let briefGenerated = false;
   let briefPath;
-  if (compileRequested && briefRequested && synced.status === "ready") {
+  if (compileRequested && briefRequested && synced.status === "ready" && await shouldRefreshBriefForManagedSource(synced, {
+    compilePerformed: Boolean(compile),
+    changed: synced.changed
+  })) {
     const briefs = await generateBriefsForSources(rootDir, [synced]);
     briefPath = briefs.get(synced.id);
     briefGenerated = Boolean(briefPath);
@@ -20664,10 +20994,21 @@ async function getWatchStatus(rootDir) {
 
 // src/viewer.ts
 var execFileAsync = promisify(execFile);
+async function isReadableFile(absolutePath) {
+  try {
+    const stats = await fs23.stat(absolutePath);
+    return stats.isFile();
+  } catch {
+    return false;
+  }
+}
 async function readViewerPage(rootDir, relativePath) {
+  if (!relativePath) {
+    return null;
+  }
   const { paths } = await loadVaultConfig(rootDir);
   const absolutePath = path28.resolve(paths.wikiDir, relativePath);
-  if (!absolutePath.startsWith(paths.wikiDir) || !await fileExists(absolutePath)) {
+  if (!isPathWithin(paths.wikiDir, absolutePath) || !await isReadableFile(absolutePath)) {
     return null;
   }
   const raw = await fs23.readFile(absolutePath, "utf8");
@@ -20681,9 +21022,12 @@ async function readViewerPage(rootDir, relativePath) {
   };
 }
 async function readViewerAsset(rootDir, relativePath) {
+  if (!relativePath) {
+    return null;
+  }
   const { paths } = await loadVaultConfig(rootDir);
   const absolutePath = path28.resolve(paths.wikiDir, relativePath);
-  if (!absolutePath.startsWith(paths.wikiDir) || !await fileExists(absolutePath)) {
+  if (!isPathWithin(paths.wikiDir, absolutePath) || !await isReadableFile(absolutePath)) {
     return null;
   }
   return {
@@ -20725,178 +21069,204 @@ async function startGraphServer(rootDir, port, options = {}) {
   await ensureViewerDist(paths.viewerDistDir);
   const server = http.createServer(async (request, response) => {
     const url = new URL(request.url ?? "/", `http://${request.headers.host ?? `localhost:${effectivePort}`}`);
-    if (url.pathname === "/api/graph") {
-      if (!await fileExists(paths.graphPath)) {
-        response.writeHead(404, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: "Graph artifact not found. Run `swarmvault compile` first." }));
+    try {
+      if (url.pathname === "/api/graph") {
+        if (!await fileExists(paths.graphPath)) {
+          response.writeHead(404, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "Graph artifact not found. Run `swarmvault compile` first." }));
+          return;
+        }
+        const graph = await readJsonFile(paths.graphPath);
+        if (!graph) {
+          response.writeHead(404, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "Graph artifact not found. Run `swarmvault compile` first." }));
+          return;
+        }
+        const reportPath = path28.join(paths.wikiDir, "graph", "report.json");
+        const report = await readJsonFile(reportPath) ?? null;
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(buildViewerGraphArtifact(graph, { report, full: options.full ?? false })));
         return;
       }
-      const graph = await readJsonFile(paths.graphPath);
-      if (!graph) {
-        response.writeHead(404, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: "Graph artifact not found. Run `swarmvault compile` first." }));
+      if (url.pathname === "/api/graph/query") {
+        const question = url.searchParams.get("q") ?? "";
+        const traversal = url.searchParams.get("traversal");
+        const budget = Number.parseInt(url.searchParams.get("budget") ?? "12", 10);
+        const result = await queryGraphVault(rootDir, question, {
+          traversal: traversal === "dfs" ? "dfs" : "bfs",
+          budget: Number.isFinite(budget) ? budget : 12
+        });
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(result));
         return;
       }
-      const reportPath = path28.join(paths.wikiDir, "graph", "report.json");
-      const report = await readJsonFile(reportPath) ?? null;
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(buildViewerGraphArtifact(graph, { report, full: options.full ?? false })));
-      return;
-    }
-    if (url.pathname === "/api/graph/query") {
-      const question = url.searchParams.get("q") ?? "";
-      const traversal = url.searchParams.get("traversal");
-      const budget = Number.parseInt(url.searchParams.get("budget") ?? "12", 10);
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(
-        JSON.stringify(
-          await queryGraphVault(rootDir, question, {
-            traversal: traversal === "dfs" ? "dfs" : "bfs",
-            budget: Number.isFinite(budget) ? budget : 12
-          })
-        )
-      );
-      return;
-    }
-    if (url.pathname === "/api/graph/path") {
-      const from = url.searchParams.get("from") ?? "";
-      const to = url.searchParams.get("to") ?? "";
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(await pathGraphVault(rootDir, from, to)));
-      return;
-    }
-    if (url.pathname === "/api/graph/explain") {
-      const target2 = url.searchParams.get("target") ?? "";
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(await explainGraphVault(rootDir, target2)));
-      return;
-    }
-    if (url.pathname === "/api/search") {
-      if (!await fileExists(paths.searchDbPath)) {
-        response.writeHead(404, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: "Search index not found. Run `swarmvault compile` first." }));
+      if (url.pathname === "/api/graph/path") {
+        const from = url.searchParams.get("from") ?? "";
+        const to = url.searchParams.get("to") ?? "";
+        const result = await pathGraphVault(rootDir, from, to);
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(result));
         return;
       }
-      const query = url.searchParams.get("q") ?? "";
-      const limit = Number.parseInt(url.searchParams.get("limit") ?? "10", 10);
-      const kind = url.searchParams.get("kind") ?? "all";
-      const status = url.searchParams.get("status") ?? "all";
-      const project = url.searchParams.get("project") ?? "all";
-      const sourceType = url.searchParams.get("sourceType") ?? "all";
-      const sourceClass = url.searchParams.get("sourceClass") ?? "all";
-      const results = searchPages(paths.searchDbPath, query, {
-        limit: Number.isFinite(limit) ? limit : 10,
-        kind,
-        status,
-        project,
-        sourceType,
-        sourceClass
-      });
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(results));
-      return;
-    }
-    if (url.pathname === "/api/graph-report") {
-      const reportPath = path28.join(paths.wikiDir, "graph", "report.json");
-      if (!await fileExists(reportPath)) {
-        response.writeHead(404, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: "Graph report artifact not found. Run `swarmvault compile` first." }));
+      if (url.pathname === "/api/graph/explain") {
+        const target2 = url.searchParams.get("target") ?? "";
+        if (!target2) {
+          response.writeHead(400, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "Missing explain target." }));
+          return;
+        }
+        try {
+          const result = await explainGraphVault(rootDir, target2);
+          response.writeHead(200, { "content-type": "application/json" });
+          response.end(JSON.stringify(result));
+        } catch (error) {
+          response.writeHead(404, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: error instanceof Error ? error.message : `Could not resolve graph target: ${target2}` }));
+        }
         return;
       }
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(await fs23.readFile(reportPath, "utf8"));
-      return;
-    }
-    if (url.pathname === "/api/watch-status") {
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(await getWatchStatus(rootDir)));
-      return;
-    }
-    if (url.pathname === "/api/page") {
-      const relativePath2 = url.searchParams.get("path") ?? "";
-      const page = await readViewerPage(rootDir, relativePath2);
-      if (!page) {
-        response.writeHead(404, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: `Page not found: ${relativePath2}` }));
+      if (url.pathname === "/api/search") {
+        if (!await fileExists(paths.searchDbPath)) {
+          response.writeHead(404, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "Search index not found. Run `swarmvault compile` first." }));
+          return;
+        }
+        const query = url.searchParams.get("q") ?? "";
+        const limit = Number.parseInt(url.searchParams.get("limit") ?? "10", 10);
+        const kind = url.searchParams.get("kind") ?? "all";
+        const status = url.searchParams.get("status") ?? "all";
+        const project = url.searchParams.get("project") ?? "all";
+        const sourceType = url.searchParams.get("sourceType") ?? "all";
+        const sourceClass = url.searchParams.get("sourceClass") ?? "all";
+        const results = searchPages(paths.searchDbPath, query, {
+          limit: Number.isFinite(limit) ? limit : 10,
+          kind,
+          status,
+          project,
+          sourceType,
+          sourceClass
+        });
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(results));
         return;
       }
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(page));
-      return;
-    }
-    if (url.pathname === "/api/asset") {
-      const relativePath2 = url.searchParams.get("path") ?? "";
-      const asset = await readViewerAsset(rootDir, relativePath2);
-      if (!asset) {
-        response.writeHead(404, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: `Asset not found: ${relativePath2}` }));
+      if (url.pathname === "/api/graph-report") {
+        const reportPath = path28.join(paths.wikiDir, "graph", "report.json");
+        if (!await fileExists(reportPath)) {
+          response.writeHead(404, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "Graph report artifact not found. Run `swarmvault compile` first." }));
+          return;
+        }
+        const body = await fs23.readFile(reportPath, "utf8");
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(body);
         return;
       }
-      response.writeHead(200, { "content-type": asset.mimeType });
-      response.end(asset.buffer);
-      return;
-    }
-    if (url.pathname === "/api/reviews" && request.method === "GET") {
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(await listApprovals(rootDir)));
-      return;
-    }
-    if (url.pathname === "/api/review" && request.method === "GET") {
-      const approvalId = url.searchParams.get("id") ?? "";
-      if (!approvalId) {
-        response.writeHead(400, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: "Missing approval id." }));
+      if (url.pathname === "/api/watch-status") {
+        const watchStatus = await getWatchStatus(rootDir);
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(watchStatus));
         return;
       }
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(await readApproval(rootDir, approvalId)));
-      return;
-    }
-    if (url.pathname === "/api/review" && request.method === "POST") {
-      const body = await readJsonBody(request);
-      const approvalId = typeof body.approvalId === "string" ? body.approvalId : "";
-      const targets = Array.isArray(body.targets) ? body.targets.filter((item) => typeof item === "string") : [];
-      const action = url.searchParams.get("action") ?? "";
-      if (!approvalId || action !== "accept" && action !== "reject") {
-        response.writeHead(400, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: "Missing approval id or invalid review action." }));
+      if (url.pathname === "/api/page") {
+        const relativePath2 = url.searchParams.get("path") ?? "";
+        const page = await readViewerPage(rootDir, relativePath2);
+        if (!page) {
+          response.writeHead(404, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: `Page not found: ${relativePath2}` }));
+          return;
+        }
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(page));
         return;
       }
-      const result = action === "accept" ? await acceptApproval(rootDir, approvalId, targets) : await rejectApproval(rootDir, approvalId, targets);
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(result));
-      return;
-    }
-    if (url.pathname === "/api/candidates" && request.method === "GET") {
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(await listCandidates(rootDir)));
-      return;
-    }
-    if (url.pathname === "/api/candidate" && request.method === "POST") {
-      const body = await readJsonBody(request);
-      const target2 = typeof body.target === "string" ? body.target : "";
-      const action = url.searchParams.get("action") ?? "";
-      if (!target2 || action !== "promote" && action !== "archive") {
-        response.writeHead(400, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: "Missing candidate target or invalid candidate action." }));
+      if (url.pathname === "/api/asset") {
+        const relativePath2 = url.searchParams.get("path") ?? "";
+        const asset = await readViewerAsset(rootDir, relativePath2);
+        if (!asset) {
+          response.writeHead(404, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: `Asset not found: ${relativePath2}` }));
+          return;
+        }
+        response.writeHead(200, { "content-type": asset.mimeType });
+        response.end(asset.buffer);
         return;
       }
-      const result = action === "promote" ? await promoteCandidate(rootDir, target2) : await archiveCandidate(rootDir, target2);
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(result));
-      return;
-    }
-    const relativePath = url.pathname === "/" ? "index.html" : url.pathname.slice(1);
-    const target = path28.join(paths.viewerDistDir, relativePath);
-    const fallback = path28.join(paths.viewerDistDir, "index.html");
-    const filePath = await fileExists(target) ? target : fallback;
-    if (!await fileExists(filePath)) {
-      response.writeHead(503, { "content-type": "text/plain" });
-      response.end("Viewer build not found. Run `pnpm build` first.");
-      return;
+      if (url.pathname === "/api/reviews" && request.method === "GET") {
+        const approvals = await listApprovals(rootDir);
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(approvals));
+        return;
+      }
+      if (url.pathname === "/api/review" && request.method === "GET") {
+        const approvalId = url.searchParams.get("id") ?? "";
+        if (!approvalId) {
+          response.writeHead(400, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "Missing approval id." }));
+          return;
+        }
+        const approval = await readApproval(rootDir, approvalId);
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(approval));
+        return;
+      }
+      if (url.pathname === "/api/review" && request.method === "POST") {
+        const body = await readJsonBody(request);
+        const approvalId = typeof body.approvalId === "string" ? body.approvalId : "";
+        const targets = Array.isArray(body.targets) ? body.targets.filter((item) => typeof item === "string") : [];
+        const action = url.searchParams.get("action") ?? "";
+        if (!approvalId || action !== "accept" && action !== "reject") {
+          response.writeHead(400, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "Missing approval id or invalid review action." }));
+          return;
+        }
+        const result = action === "accept" ? await acceptApproval(rootDir, approvalId, targets) : await rejectApproval(rootDir, approvalId, targets);
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(result));
+        return;
+      }
+      if (url.pathname === "/api/candidates" && request.method === "GET") {
+        const candidates = await listCandidates(rootDir);
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(candidates));
+        return;
+      }
+      if (url.pathname === "/api/candidate" && request.method === "POST") {
+        const body = await readJsonBody(request);
+        const target2 = typeof body.target === "string" ? body.target : "";
+        const action = url.searchParams.get("action") ?? "";
+        if (!target2 || action !== "promote" && action !== "archive") {
+          response.writeHead(400, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "Missing candidate target or invalid candidate action." }));
+          return;
+        }
+        const result = action === "promote" ? await promoteCandidate(rootDir, target2) : await archiveCandidate(rootDir, target2);
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(result));
+        return;
+      }
+      const relativePath = url.pathname === "/" ? "index.html" : url.pathname.slice(1);
+      const target = path28.join(paths.viewerDistDir, relativePath);
+      const fallback = path28.join(paths.viewerDistDir, "index.html");
+      const filePath = await fileExists(target) ? target : fallback;
+      if (!await fileExists(filePath)) {
+        response.writeHead(503, { "content-type": "text/plain" });
+        response.end("Viewer build not found. Run `pnpm build` first.");
+        return;
+      }
+      const staticBody = await fs23.readFile(filePath);
+      response.writeHead(200, { "content-type": mime2.lookup(filePath) || "text/plain" });
+      response.end(staticBody);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`[viewer] ${request.method ?? "GET"} ${url.pathname} failed: ${message}`);
+      if (!response.headersSent) {
+        response.writeHead(500, { "content-type": "application/json" });
+        response.end(JSON.stringify({ error: message }));
+      } else {
+        response.end();
+      }
     }
-    response.writeHead(200, { "content-type": mime2.lookup(filePath) || "text/plain" });
-    response.end(await fs23.readFile(filePath));
   });
   await new Promise((resolve) => {
     server.listen(effectivePort, resolve);