ctxman 3.1.1 → 3.2.7

package/lib/map/rank.js

@@ -117,9 +117,28 @@ export function pageRank(ids, edges, options = {}) {
 }
 
 /**
- * Files of the graph matched by focus paths (a file, or a folder for every file in it)
+ * Split a `file[:symbol]` target into `{ pathPart, symbol }` (ignoring Windows drive colons).
+ * @param {string} entry
+ * @returns {{ pathPart: string, symbol: string | null }}
+ */
+export function splitTargetSymbol(entry) {
+  if (typeof entry !== 'string') return { pathPart: '', symbol: null };
+  const lastColon = entry.lastIndexOf(':');
+  // Ignore Windows drive letters like `C:\foo` (colon at index 1)
+  if (lastColon > 1) {
+    const candidatePath = entry.slice(0, lastColon);
+    const candidateSymbol = entry.slice(lastColon + 1).trim();
+    if (candidatePath && candidateSymbol && !candidateSymbol.includes('/')) {
+      return { pathPart: candidatePath, symbol: candidateSymbol };
+    }
+  }
+  return { pathPart: entry, symbol: null };
+}
+
+/**
+ * Files of the graph matched by focus paths (a file, `file:symbol`, or a folder for every file in it)
  * @param {import('./graph.js').RepoGraph} graph
- * @param {string[]} focus - Absolute or project-relative paths
+ * @param {string[]} focus - Absolute or project-relative paths (optionally with `:symbol`)
  * @returns {{files: string[], unmatched: string[]}}
  * @throws {Error} When a path lies outside the project
  */
@@ -127,11 +146,22 @@ export function resolveFocus(graph, focus = []) {
   const files = new Set();
   const unmatched = [];
   const nodePaths = graph.nodes.map((node) => node.path);
+  const nodeMap = new Map(graph.nodes.map((node) => [node.path, node]));
   for (const entry of focus) {
-    const relative = toProjectPath(graph.root, entry);
-    const matches = nodePaths.filter(
+    const { pathPart, symbol } = splitTargetSymbol(entry);
+    const relative = toProjectPath(graph.root, pathPart);
+    let matches = nodePaths.filter(
       (file) => relative === '' || file === relative || file.startsWith(`${relative}/`)
     );
+    if (symbol && matches.length === 1) {
+      const node = nodeMap.get(matches[0]);
+      if (node && Array.isArray(node.methods) && node.methods.length > 0) {
+        const hasSymbol = node.methods.some(
+          (m) => m.name === symbol || m.name.replace(/^(?:get|set)\s+/, '') === symbol
+        );
+        if (!hasSymbol) matches = [];
+      }
+    }
     if (matches.length === 0) unmatched.push(entry);
     for (const file of matches) files.add(file);
   }
@@ -160,7 +190,8 @@ export function toProjectPath(root, entry) {
  * Rank the files of a graph, best first
  * @param {import('./graph.js').RepoGraph} graph
  * @param {Object} [options]
- * @param {string[]} [options.focus] - Files or folders to personalise PageRank toward
+ * @param {string[]} [options.focus] - Files, `file:symbol` targets, or folders to personalise PageRank toward
+ * @param {boolean} [options.callGraph=false] - Blend cross-file AST symbol call edges into PageRank
  * @param {{pagerank?: number, history?: number, symbols?: number}} [options.weights]
  * @param {number} [options.damping=0.85]
  * @returns {Array<{path: string, rank: number, score: number, pagerank: number,
@@ -171,12 +202,19 @@ export function rankFiles(graph, options = {}) {
   const weights = { ...DEFAULT_WEIGHTS, ...options.weights };
   const ids = graph.nodes.map((node) => node.path);
   const focus = new Set(resolveFocus(graph, options.focus || []).files);
+  const activeEdges =
+    options.callGraph && Array.isArray(graph.callEdges) && graph.callEdges.length > 0
+      ? [
+          ...graph.edges,
+          ...graph.callEdges.map(({ from, to, weight }) => ({ from, to, weight: weight ?? 1 })),
+        ]
+      : graph.edges;
 
   let personalization = null;
   if (focus.size > 0) {
     const preference = new Map();
     for (const file of focus) preference.set(file, FOCUS_WEIGHT);
-    for (const { from, to } of graph.edges) {
+    for (const { from, to } of activeEdges) {
       for (const [a, b] of [
         [from, to],
         [to, from],
@@ -196,7 +234,7 @@ export function rankFiles(graph, options = {}) {
     );
   }
 
-  const { scores } = pageRank(ids, graph.edges, {
+  const { scores } = pageRank(ids, activeEdges, {
     damping: options.damping ?? DEFAULT_DAMPING,
     personalization,
   });

package/lib/map/render.js

@@ -1,6 +1,6 @@
 /**
  * Rendering for `ctxman map`: the ranked files with their function signatures, trimmed
- * to a token budget, or the dependency graph itself
+ * to a token budget, or the dependency & cross-file call graph itself
  */
 
 import fs from 'fs';
@@ -37,6 +37,7 @@ export function normalizeMapOptions(options = {}) {
     importantLast: Boolean(options.importantLast),
     style: options.style ?? 'text',
     graph: Boolean(options.graph),
+    callGraph: Boolean(options.callGraph),
     redact: options.redact !== false,
     weights: { ...DEFAULT_WEIGHTS, ...options.weights },
     damping: options.damping ?? DEFAULT_DAMPING,
@@ -77,6 +78,7 @@ export function normalizeMapOptions(options = {}) {
  * @param {boolean} [options.importantLast=false] - Highest-ranked file at the end
  * @param {'text'|'markdown'|'json'|'dot'} [options.style='text']
  * @param {boolean} [options.graph=false] - Render the dependency edges instead of the map
+ * @param {boolean} [options.callGraph=false] - Include cross-file AST symbol call graph edges
  * @param {boolean} [options.redact=true] - Mask secrets in signatures
  * @param {{pagerank?: number, history?: number, symbols?: number}} [options.weights]
  * @returns {{output: string, style: string, budget: number, tokens: number,
@@ -102,6 +104,7 @@ export function renderRepoMap(root, options = {}) {
   let timer = performance.now();
   const ranked = rankFiles(graph, {
     focus: focus.files,
+    callGraph: opts.callGraph,
     weights: opts.weights,
     damping: opts.damping,
   });
@@ -116,7 +119,7 @@ export function renderRepoMap(root, options = {}) {
     warnings,
   };
   if (opts.graph || opts.style === 'dot') {
-    result.output = renderGraph(graph, ranked, opts.style);
+    result.output = renderGraph(graph, ranked, opts.style, { callGraph: opts.callGraph });
     result.tokens = countTokens(result.output);
     result.files = [];
     result.skipped = 0;
@@ -174,13 +177,18 @@ function selectFiles(graph, ranked, opts) {
       path: row.path,
       score: row.score,
       tokens: 0,
-      methods: node.methods.map((method) => ({ ...method, tokens: 0 })),
+      methods: node.methods.map((method) => ({
+        line: method.line,
+        name: method.name,
+        signature: method.signature,
+        tokens: 0,
+      })),
     });
     if (countTokens(skeleton + separator) > remaining) {
       skipped++;
       continue;
     }
-    const entry = describeFile(graph, node, row, analyzer);
+    const entry = describeFile(graph, node, row, analyzer, opts);
     const block = renderBlock(style, entry);
     const cost = countTokens(block + separator);
     if (cost > remaining) {
@@ -216,7 +224,7 @@ function displayOrder(chosen, opts) {
 }
 
 /** Map entry of a file: its tokens and the tokens of each of its methods */
-function describeFile(graph, node, row, analyzer) {
+function describeFile(graph, node, row, analyzer, opts = {}) {
   const absolute = path.join(graph.root, node.path);
   let content = '';
   try {
@@ -225,17 +233,37 @@ function describeFile(graph, node, row, analyzer) {
     // Deleted since the scan: keep the signatures, count nothing
   }
   const sources = content ? analyzer.extractMethodSources(content, node.methods, absolute) : [];
+  const outgoingCallsByMethod = new Map();
+  if (opts.callGraph && Array.isArray(graph.callEdges)) {
+    for (const edge of graph.callEdges) {
+      if (edge.from !== node.path) continue;
+      const key = `${edge.caller}:${edge.callerLine}`;
+      let list = outgoingCallsByMethod.get(key);
+      if (!list) {
+        list = [];
+        outgoingCallsByMethod.set(key, list);
+      }
+      list.push(`${edge.to}:${edge.callee}`);
+    }
+  }
   return {
     path: node.path,
     rank: row.rank,
     score: row.score,
     tokens: content ? TokenUtils.calculate(content, absolute) : 0,
-    methods: node.methods.map((method, i) => ({
-      line: method.line,
-      name: method.name,
-      signature: method.signature,
-      tokens: sources[i] ? TokenUtils.calculate(sources[i], absolute) : 0,
-    })),
+    methods: node.methods.map((method, i) => {
+      const item = {
+        line: method.line,
+        name: method.name,
+        signature: method.signature,
+        tokens: sources[i] ? TokenUtils.calculate(sources[i], absolute) : 0,
+      };
+      if (opts.callGraph) {
+        const targets = outgoingCallsByMethod.get(`${method.name}:${method.line}`) || [];
+        if (targets.length > 0) item.calls = targets;
+      }
+      return item;
+    }),
   };
 }
 
@@ -246,13 +274,23 @@ export function renderBlock(style, entry) {
     const lines = [`## ${entry.path}`, `score ${score} · ${entry.tokens} tokens`];
     if (entry.methods.length > 0) lines.push('');
     for (const method of entry.methods) {
-      lines.push(`- L${method.line} ${inlineCode(method.signature)} (${method.tokens} tokens)`);
+      const callSuffix =
+        Array.isArray(method.calls) && method.calls.length > 0
+          ? ` -> ${method.calls.join(', ')}`
+          : '';
+      lines.push(
+        `- L${method.line} ${inlineCode(method.signature)} (${method.tokens} tokens)${callSuffix}`
+      );
     }
     return lines.join('\n');
   }
   const lines = [`${entry.path} (score ${score}, ${entry.tokens} tokens)`];
   for (const method of entry.methods) {
-    lines.push(`  ${method.line}: ${method.signature} [${method.tokens} tok]`);
+    const callSuffix =
+      Array.isArray(method.calls) && method.calls.length > 0
+        ? ` -> ${method.calls.join(', ')}`
+        : '';
+    lines.push(`  ${method.line}: ${method.signature} [${method.tokens} tok]${callSuffix}`);
   }
   return lines.join('\n');
 }
@@ -265,6 +303,10 @@ function inlineCode(text) {
 
 function renderJson(graph, ranked, selection, opts) {
   const included = new Set(selection.files.map((file) => file.path));
+  const callEdges = (graph.callEdges || []).map((edge) => ({
+    ...edge,
+    weight: round(edge.weight, 6),
+  }));
   const document = {
     root: graph.root,
     budget: opts.tokens,
@@ -290,9 +332,11 @@ function renderJson(graph, ranked, selection, opts) {
       included: included.has(row.path),
     })),
     edges: graph.edges.map((edge) => ({ ...edge, weight: round(edge.weight, 6) })),
+    callEdges,
     stats: {
       files: graph.stats.files,
       edges: graph.stats.edges,
+      callEdges: graph.stats.callEdges ?? callEdges.length,
       unresolvedImports: graph.stats.unresolvedImports,
       skippedFiles: graph.stats.skipped,
     },
@@ -302,24 +346,28 @@ function renderJson(graph, ranked, selection, opts) {
 
 /**
  * The dependency edges: `a -> b` lines (text), a fenced block (markdown), nodes and edges
- * (json) or a Graphviz digraph (dot)
+ * (json) or a Graphviz digraph (dot). When `options.callGraph` is true, cross-file AST
+ * symbol call edges (`from:caller -> to:callee`) are also included.
  */
-export function renderGraph(graph, ranked, style) {
+export function renderGraph(graph, ranked, style, options = {}) {
+  const includeCalls = Boolean(options.callGraph);
   const weightNote = (edge) => (edge.weight === 1 ? '' : ` (${round(edge.weight, 3)})`);
+  const callEdges = graph.callEdges || [];
+
   if (style === 'json') {
-    return `${JSON.stringify(
-      {
-        root: graph.root,
-        nodes: ranked.map((row) => ({
-          path: row.path,
-          rank: row.rank,
-          score: round(row.score, 6),
-        })),
-        edges: graph.edges.map((edge) => ({ ...edge, weight: round(edge.weight, 6) })),
-      },
-      null,
-      2
-    )}\n`;
+    const payload = {
+      root: graph.root,
+      nodes: ranked.map((row) => ({
+        path: row.path,
+        rank: row.rank,
+        score: round(row.score, 6),
+      })),
+      edges: graph.edges.map((edge) => ({ ...edge, weight: round(edge.weight, 6) })),
+    };
+    if (includeCalls) {
+      payload.callEdges = callEdges.map((edge) => ({ ...edge, weight: round(edge.weight, 6) }));
+    }
+    return `${JSON.stringify(payload, null, 2)}\n`;
   }
   if (style === 'dot') {
     const escape = (value) => value.replace(/["\\]/g, '\\$&');
@@ -335,10 +383,23 @@ export function renderGraph(graph, ranked, style) {
       const attributes = edge.weight === 1 ? '' : ` [weight=${round(edge.weight, 3)}]`;
       lines.push(`  ${quote(edge.from)} -> ${quote(edge.to)}${attributes};`);
     }
+    if (includeCalls) {
+      for (const edge of callEdges) {
+        const callLabel = `"${escape(`${edge.caller}->${edge.callee}`)}"`;
+        lines.push(
+          `  ${quote(edge.from)} -> ${quote(edge.to)} [style=dashed, label=${callLabel}];`
+        );
+      }
+    }
     lines.push('}');
     return `${lines.join('\n')}\n`;
   }
   const lines = graph.edges.map((edge) => `${edge.from} -> ${edge.to}${weightNote(edge)}`);
+  if (includeCalls) {
+    for (const edge of callEdges) {
+      lines.push(`${edge.from}:${edge.caller} -> ${edge.to}:${edge.callee}${weightNote(edge)}`);
+    }
+  }
   if (style === 'markdown') {
     return `# Dependency graph\n\n\`\`\`text\n${lines.join('\n')}${lines.length ? '\n' : ''}\`\`\`\n`;
   }

package/lib/pack/index.js

@@ -95,6 +95,7 @@ function normalizeOptions(options) {
     include: stringList(options.include, 'include'),
     exclude: stringList(options.exclude, 'exclude'),
     files: options.files ? stringList(options.files, 'files') : null,
+    rankOrder: options.rankOrder ? stringList(options.rankOrder, 'rankOrder') : null,
     cwd: options.cwd,
     excludeFiles: stringList(options.excludeFiles, 'excludeFiles'),
     maxFileSize: positiveInteger(options.maxFileSize, 'maxFileSize') ?? DEFAULT_MAX_FILE_SIZE,
@@ -209,6 +210,23 @@ function modelFit(profile, tokens, encoding) {
   };
 }
 
+/**
+ * Order entries according to an explicit priority list, falling back to `rankEntries()`
+ * for any entry not named in `rankOrder`.
+ */
+function orderEntriesByPriority(root, entries, rankOrder) {
+  if (!rankOrder || rankOrder.length === 0) {
+    return rankEntries(root, entries).ranked;
+  }
+  const priority = new Map(rankOrder.map((p, idx) => [p, idx]));
+  const named = entries
+    .filter((entry) => priority.has(entry.path))
+    .sort((a, b) => priority.get(a.path) - priority.get(b.path));
+  const unnamed = entries.filter((entry) => !priority.has(entry.path));
+  if (unnamed.length === 0) return named;
+  return [...named, ...rankEntries(root, unnamed).ranked];
+}
+
 /**
  * Pack the contents of a project's files into one document
  * @param {string} root - Project root
@@ -217,6 +235,7 @@ function modelFit(profile, tokens, encoding) {
  * @param {string[]} [options.include] - Gitignore-style globs: keep only matching files
  * @param {string[]} [options.exclude] - Gitignore-style globs: leave matching files out
  * @param {string[]} [options.files] - Explicit file list instead of scanning the root
+ * @param {string[]} [options.rankOrder] - Explicit priority order for budget trimming
  * @param {string} [options.cwd] - Base for relative `files` entries (default: root)
  * @param {string[]} [options.excludeFiles] - Absolute paths to leave out
  * @param {number} [options.maxFileSize=1048576] - Skip larger files (bytes)
@@ -269,7 +288,7 @@ export async function packContext(root, options = {}) {
   let omitted = [];
   let rendered;
   if (opts.budget) {
-    const { ranked } = rankEntries(selection.root, entries);
+    const ranked = orderEntriesByPriority(selection.root, entries, opts.rankOrder);
     const separator = count('\n\n');
     const wrapperCost = (entry) =>
       opts.style === 'json'

package/lib/pack/select.js

@@ -128,11 +128,14 @@ function isIgnored(scanner, rootPath, relativePath) {
 
 /**
  * An explicit list, in the given order. A path that leaves the root (`..`, an absolute path
- * elsewhere, a symlink pointing out) is an error; files the ignore rules exclude are skipped.
+ * elsewhere, a symlink pointing out) is an error; files the ignore rules or export policy
+ * exclude are skipped.
  */
 function listedFiles(rootPath, entries, cwd, skipped) {
   const realRoot = fs.realpathSync(rootPath);
   const scanner = new Scanner(rootPath);
+  const policy = scanner.getPolicy();
+  scanner.getIgnoreFileRules();
   const files = [];
   const seen = new Set();
   for (const entry of entries) {
@@ -165,6 +168,10 @@ function listedFiles(rootPath, entries, cwd, skipped) {
       skipped.push({ path: relativePath, reason: 'not-a-file' });
       continue;
     }
+    if (policy?.isAuditLog(relative) || scanner.isDenied(relative)) {
+      skipped.push({ path: relativePath, reason: 'denied' });
+      continue;
+    }
     if (isIgnored(scanner, rootPath, relative)) {
       skipped.push({ path: relativePath, reason: 'ignored' });
       continue;

package/lib/policy/audit.js

@@ -270,7 +270,7 @@ export function filterAuditEvents(events, { since = null, limit = null } = {}) {
 const fit = (value, width, { keepEnd = false } = {}) => {
   const text = value === null || value === undefined || value === '' ? '-' : String(value);
   if (text.length <= width) return text.padEnd(width);
-  return keepEnd ? `…${text.slice(-(width - 1))}` : `${text.slice(0, width - 1)}…`;
+  return keepEnd ? `\u2026${text.slice(-(width - 1))}` : `${text.slice(0, width - 1)}\u2026`;
 };
 
 // A file destination inside the exported project is shown relative to it
@@ -289,9 +289,11 @@ const destinationOf = (event) => {
  * @returns {string}
  */
 export function formatAuditTable(events) {
+  const hasRepo = events.some((e) => typeof e?.repo === 'string' && e.repo.length > 0);
   const columns = [
     ['TIME (UTC)', 20, (e) => String(e.timestamp ?? '').replace(/\.\d+Z$/, 'Z')],
     ['RESULT', 8, (e) => e.outcome],
+    ...(hasRepo ? [['REPO', 14, (e) => e.repo]] : []),
     ['USER', 12, (e) => e.user],
     ['COMMAND', 26, (e) => e.command],
     ['DESTINATION', 28, destinationOf, { keepEnd: true }],

package/lib/policy/index.js

@@ -51,3 +51,8 @@ export {
   loadIgnoreFileRules,
   IgnoreFileRules,
 } from './ignore-files.js';
+export {
+  resolvePolicyWorkspaceDirs,
+  checkWorkspacePolicies,
+  readWorkspaceAuditLogs,
+} from './workspace.js';

package/lib/policy/workspace.js

@@ -0,0 +1,254 @@
+/**
+ * Multi-repository workspace policy inspection & audit log aggregation
+ *
+ * Unlike `resolveWorkspaceRepos()`, `resolvePolicyWorkspaceDirs()` does NOT abort on the
+ * first invalid `.ctxman/policy.json` file so `ctxman policy check --repo ...` and MCP
+ * `check_policy` / `audit_log` can inspect and report all repositories in one pass.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { loadPolicy, PolicyConfigError } from './policy.js';
+import { auditLogFiles, readAuditLog, filterAuditEvents } from './audit.js';
+
+function sanitizeAlias(raw) {
+  const cleaned = String(raw || 'repo')
+    .trim()
+    .replace(/[\\/]+/g, '-')
+    .replace(/^\.+/, '');
+  return cleaned || 'repo';
+}
+
+function buildWorkspaceInputs(primaryRoot, extraRepos = []) {
+  const resolvedPrimary = path.resolve(primaryRoot || process.cwd());
+  if (!Array.isArray(extraRepos) || extraRepos.length === 0) {
+    return [resolvedPrimary];
+  }
+  const realPrimary = fs.existsSync(resolvedPrimary)
+    ? fs.realpathSync(resolvedPrimary)
+    : resolvedPrimary;
+  const isContainerOfExtra = extraRepos.some((item) => {
+    const raw = typeof item === 'string' ? item : item?.path;
+    if (typeof raw !== 'string' || !raw.trim()) return false;
+    const resolved = path.resolve(raw);
+    const real = fs.existsSync(resolved) ? fs.realpathSync(resolved) : resolved;
+    return real !== realPrimary && real.startsWith(realPrimary + path.sep);
+  });
+  return isContainerOfExtra ? [...extraRepos] : [resolvedPrimary, ...extraRepos];
+}
+
+/**
+ * Resolve, validate directory existence, deduplicate, and assign unique aliases without
+ * failing on invalid policy files.
+ *
+ * @param {string} primaryRoot
+ * @param {Array<string|{path: string, alias?: string}>} [extraRepos]
+ * @returns {Array<{alias: string, root: string, realRoot: string}>}
+ */
+export function resolvePolicyWorkspaceDirs(primaryRoot, extraRepos = []) {
+  const inputs = buildWorkspaceInputs(primaryRoot, extraRepos);
+  const rawEntries = [];
+  const seenRealRoots = new Set();
+
+  for (const item of inputs) {
+    const rawPath = typeof item === 'string' ? item : item?.path;
+    const explicitAlias = typeof item === 'object' && item !== null ? item.alias : undefined;
+    if (typeof rawPath !== 'string' || !rawPath.trim()) {
+      throw new Error('Repository path must be a non-empty string');
+    }
+    const resolved = path.resolve(rawPath);
+    if (!fs.statSync(resolved, { throwIfNoEntry: false })?.isDirectory()) {
+      throw new Error(`Not a directory: ${rawPath}`);
+    }
+    const realRoot = fs.realpathSync(resolved);
+    if (seenRealRoots.has(realRoot)) continue;
+    seenRealRoots.add(realRoot);
+
+    rawEntries.push({
+      root: resolved,
+      realRoot,
+      explicitAlias: explicitAlias ? sanitizeAlias(explicitAlias) : null,
+      baseName: sanitizeAlias(path.basename(resolved) || path.basename(realRoot) || 'repo'),
+      parentName: sanitizeAlias(path.basename(path.dirname(resolved))),
+    });
+  }
+
+  const baseCounts = new Map();
+  for (const entry of rawEntries) {
+    const candidate = entry.explicitAlias ?? entry.baseName;
+    baseCounts.set(candidate, (baseCounts.get(candidate) ?? 0) + 1);
+  }
+
+  const usedAliases = new Set();
+  return rawEntries.map((entry) => {
+    let candidate = entry.explicitAlias ?? entry.baseName;
+    if (!entry.explicitAlias && (baseCounts.get(candidate) ?? 0) > 1 && entry.parentName) {
+      candidate = `${entry.parentName}-${entry.baseName}`;
+    }
+    let unique = candidate;
+    let suffix = 2;
+    while (usedAliases.has(unique)) {
+      unique = `${candidate}-${suffix++}`;
+    }
+    usedAliases.add(unique);
+    return {
+      alias: unique,
+      root: entry.root,
+      realRoot: entry.realRoot,
+    };
+  });
+}
+
+/**
+ * Validate and summarize export policies across a multi-repository workspace.
+ *
+ * @param {string} primaryRoot
+ * @param {Array<string|{path: string, alias?: string}>} [extraRepos]
+ * @param {object} [options]
+ * @param {object} [options.env=process.env]
+ * @returns {object}
+ */
+export function checkWorkspacePolicies(primaryRoot, extraRepos = [], { env = process.env } = {}) {
+  const dirs = resolvePolicyWorkspaceDirs(primaryRoot, extraRepos);
+  const repoResults = [];
+  const validPolicies = [];
+
+  for (const { alias, root } of dirs) {
+    try {
+      const policy = loadPolicy(root, { env });
+      validPolicies.push({ alias, policy });
+      repoResults.push({
+        alias,
+        valid: true,
+        ...policy.toJSON(),
+      });
+    } catch (error) {
+      if (!(error instanceof PolicyConfigError)) throw error;
+      repoResults.push({
+        alias,
+        root,
+        valid: false,
+        file: error.file,
+        errors: error.errors,
+        message: error.message,
+      });
+    }
+  }
+
+  const valid = repoResults.every((r) => r.valid);
+  const active = validPolicies.some(({ policy }) => policy.active);
+  const requireRedaction = validPolicies.some(({ policy }) => policy.requireRedaction);
+  const tokenLimits = validPolicies
+    .map(({ policy }) => policy.maxExportTokens)
+    .filter((n) => typeof n === 'number');
+  const maxExportTokens = tokenLimits.length > 0 ? Math.min(...tokenLimits) : null;
+
+  const modelRules = validPolicies.flatMap(({ alias, policy }) =>
+    policy.modelRules.map(({ scope, file, patterns }) => ({
+      repo: alias,
+      scope,
+      file,
+      patterns,
+    }))
+  );
+  const ignoreFiles = [...new Set(validPolicies.flatMap(({ policy }) => policy.ignoreFiles))];
+
+  return {
+    valid,
+    active,
+    requireRedaction,
+    maxExportTokens,
+    allowedTargetModels: modelRules.length > 0 ? modelRules : null,
+    ignoreFiles,
+    repos: repoResults,
+  };
+}
+
+/**
+ * Read, tag with `repo`, deduplicate, and chronologically merge export audit logs across
+ * a multi-repository workspace.
+ *
+ * @param {string} primaryRoot
+ * @param {Array<string|{path: string, alias?: string}>} [extraRepos]
+ * @param {object} [options]
+ * @param {Date|null} [options.since=null]
+ * @param {number|null} [options.limit=null]
+ * @param {object} [options.env=process.env]
+ * @returns {object}
+ */
+export function readWorkspaceAuditLogs(
+  primaryRoot,
+  extraRepos = [],
+  { since = null, limit = null, env = process.env } = {}
+) {
+  const dirs = resolvePolicyWorkspaceDirs(primaryRoot, extraRepos);
+  const aliasByRoot = new Map();
+  for (const dir of dirs) {
+    aliasByRoot.set(dir.root, dir.alias);
+    aliasByRoot.set(dir.realRoot, dir.alias);
+  }
+
+  const seenEventIds = new Set();
+  const seenFiles = new Set();
+  const allFiles = [];
+  const existingFiles = [];
+  const missingFiles = [];
+  const policyErrors = [];
+  const mergedEvents = [];
+  let skippedLines = 0;
+
+  for (const { alias, root } of dirs) {
+    const { files, error } = auditLogFiles(root, { env });
+    if (error) {
+      policyErrors.push({ repo: alias, root, message: error.message });
+    }
+
+    const unreadFiles = files.filter((file) => {
+      const resolvedFile = path.resolve(file);
+      if (seenFiles.has(resolvedFile)) return false;
+      seenFiles.add(resolvedFile);
+      allFiles.push(file);
+      return true;
+    });
+    if (unreadFiles.length === 0) continue;
+
+    const { events, skipped, missing } = readAuditLog(unreadFiles);
+    skippedLines += skipped;
+    for (const file of unreadFiles) {
+      if (missing.includes(file)) missingFiles.push(file);
+      else existingFiles.push(file);
+    }
+
+    for (const event of events) {
+      if (event.id && seenEventIds.has(event.id)) continue;
+      if (event.id) seenEventIds.add(event.id);
+      let eventRepo = event.repo ?? null;
+      if (!eventRepo && typeof event.root === 'string') {
+        const resolvedEventRoot = path.resolve(event.root);
+        const realEventRoot = fs.existsSync(resolvedEventRoot)
+          ? fs.realpathSync(resolvedEventRoot)
+          : resolvedEventRoot;
+        eventRepo = aliasByRoot.get(resolvedEventRoot) ?? aliasByRoot.get(realEventRoot) ?? null;
+      }
+      mergedEvents.push({
+        repo: eventRepo ?? alias,
+        ...event,
+      });
+    }
+  }
+
+  mergedEvents.sort((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)));
+  const matching = filterAuditEvents(mergedEvents, { since });
+  const selected = filterAuditEvents(matching, { limit });
+
+  return {
+    repos: dirs.map(({ alias, root }) => ({ alias, root })),
+    files: existingFiles,
+    allFiles,
+    missing: missingFiles,
+    total: matching.length,
+    events: selected,
+    skippedLines,
+    policyErrors,
+  };
+}