@karmaniverous/jeeves-meta 0.3.0 → 0.3.2

package/dist/cli.js

@@ -386,6 +386,10 @@ function buildMetaFilter(config) {
                 key: 'domains',
                 match: { value: config.metaProperty.domains[0] },
             },
+            {
+                key: 'file_path',
+                match: { text: 'meta.json' },
+            },
         ],
     };
 }
@@ -405,21 +409,95 @@ async function discoverMetas(config, watcher) {
         filter,
         fields: ['file_path'],
     });
-    // Deduplicate by file_path (multi-chunk files)
+    // Deduplicate by .meta/ directory path (handles multi-chunk files)
     const seen = new Set();
     const metaPaths = [];
     for (const sf of scanFiles) {
         const fp = normalizePath$1(sf.file_path);
-        if (seen.has(fp))
-            continue;
-        seen.add(fp);
         // Derive .meta/ directory from file_path (strip /meta.json)
         const metaPath = fp.replace(/\/meta\.json$/, '');
+        if (seen.has(metaPath))
+            continue;
+        seen.add(metaPath);
         metaPaths.push(metaPath);
     }
     return metaPaths;
 }
 
+/**
+ * File-system lock for preventing concurrent synthesis on the same meta.
+ *
+ * Lock file: .meta/.lock containing PID + timestamp.
+ * Stale timeout: 30 minutes.
+ *
+ * @module lock
+ */
+const LOCK_FILE = '.lock';
+const STALE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+/**
+ * Attempt to acquire a lock on a .meta directory.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns True if lock was acquired, false if already locked (non-stale).
+ */
+function acquireLock(metaPath) {
+    const lockPath = join(metaPath, LOCK_FILE);
+    if (existsSync(lockPath)) {
+        try {
+            const raw = readFileSync(lockPath, 'utf8');
+            const data = JSON.parse(raw);
+            const lockAge = Date.now() - new Date(data.startedAt).getTime();
+            if (lockAge < STALE_TIMEOUT_MS) {
+                return false; // Lock is active
+            }
+            // Stale lock — fall through to overwrite
+        }
+        catch {
+            // Corrupt lock file — overwrite
+        }
+    }
+    const lock = {
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+    };
+    writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n');
+    return true;
+}
+/**
+ * Release a lock on a .meta directory.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ */
+function releaseLock(metaPath) {
+    const lockPath = join(metaPath, LOCK_FILE);
+    try {
+        unlinkSync(lockPath);
+    }
+    catch {
+        // Already removed or never existed
+    }
+}
+/**
+ * Check if a .meta directory is currently locked (non-stale).
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns True if locked and not stale.
+ */
+function isLocked(metaPath) {
+    const lockPath = join(metaPath, LOCK_FILE);
+    if (!existsSync(lockPath))
+        return false;
+    try {
+        const raw = readFileSync(lockPath, 'utf8');
+        const data = JSON.parse(raw);
+        const lockAge = Date.now() - new Date(data.startedAt).getTime();
+        return lockAge < STALE_TIMEOUT_MS;
+    }
+    catch {
+        return false; // Corrupt lock = not locked
+    }
+}
+
 /**
  * Build the ownership tree from discovered .meta/ paths.
  *
@@ -497,6 +575,138 @@ function findNode(tree, targetPath) {
     return Array.from(tree.nodes.values()).find((n) => n.metaPath === targetPath || n.ownerPath === targetPath);
 }
 
+/**
+ * Unified meta listing: scan, dedup, enrich.
+ *
+ * Single source of truth for all consumers that need a list of metas
+ * with enriched metadata. Replaces duplicated scan+dedup logic in
+ * plugin tools, CLI, and prompt injection.
+ *
+ * @module discovery/listMetas
+ */
+/**
+ * Discover, deduplicate, and enrich all metas.
+ *
+ * This is the single consolidated function that replaces all duplicated
+ * scan+dedup+enrich logic across the codebase. All enrichment comes from
+ * reading meta.json on disk (the canonical source).
+ *
+ * @param config - Validated synthesis config.
+ * @param watcher - Watcher HTTP client for discovery.
+ * @returns Enriched meta list with summary statistics and ownership tree.
+ */
+async function listMetas(config, watcher) {
+    // Step 1: Discover deduplicated meta paths via watcher scan
+    const metaPaths = await discoverMetas(config, watcher);
+    // Step 2: Build ownership tree
+    const tree = buildOwnershipTree(metaPaths);
+    // Step 3: Read and enrich each meta from disk
+    const entries = [];
+    let staleCount = 0;
+    let errorCount = 0;
+    let lockedCount = 0;
+    let neverSynthesizedCount = 0;
+    let totalArchTokens = 0;
+    let totalBuilderTokens = 0;
+    let totalCriticTokens = 0;
+    let lastSynthPath = null;
+    let lastSynthAt = null;
+    let stalestPath = null;
+    let stalestEffective = -1;
+    for (const node of tree.nodes.values()) {
+        let meta;
+        try {
+            meta = JSON.parse(readFileSync(join(node.metaPath, 'meta.json'), 'utf8'));
+        }
+        catch {
+            // Skip unreadable metas
+            continue;
+        }
+        const depth = meta._depth ?? node.treeDepth;
+        const emphasis = meta._emphasis ?? 1;
+        const hasError = Boolean(meta._error);
+        const locked = isLocked(normalizePath$1(node.metaPath));
+        const neverSynth = !meta._generatedAt;
+        // Compute staleness
+        let stalenessSeconds;
+        if (neverSynth) {
+            stalenessSeconds = Infinity;
+        }
+        else {
+            const genAt = new Date(meta._generatedAt).getTime();
+            stalenessSeconds = Math.max(0, Math.floor((Date.now() - genAt) / 1000));
+        }
+        // Tokens
+        const archTokens = meta._architectTokens ?? 0;
+        const buildTokens = meta._builderTokens ?? 0;
+        const critTokens = meta._criticTokens ?? 0;
+        // Accumulate summary stats
+        if (stalenessSeconds > 0)
+            staleCount++;
+        if (hasError)
+            errorCount++;
+        if (locked)
+            lockedCount++;
+        if (neverSynth)
+            neverSynthesizedCount++;
+        totalArchTokens += archTokens;
+        totalBuilderTokens += buildTokens;
+        totalCriticTokens += critTokens;
+        // Track last synthesized
+        if (meta._generatedAt) {
+            if (!lastSynthAt || meta._generatedAt > lastSynthAt) {
+                lastSynthAt = meta._generatedAt;
+                lastSynthPath = node.metaPath;
+            }
+        }
+        // Track stalest (effective staleness for scheduling)
+        const depthFactor = Math.pow(1 + config.depthWeight, depth);
+        const effectiveStaleness = (stalenessSeconds === Infinity
+            ? Number.MAX_SAFE_INTEGER
+            : stalenessSeconds) *
+            depthFactor *
+            emphasis;
+        if (effectiveStaleness > stalestEffective) {
+            stalestEffective = effectiveStaleness;
+            stalestPath = node.metaPath;
+        }
+        entries.push({
+            path: node.metaPath,
+            depth,
+            emphasis,
+            stalenessSeconds,
+            lastSynthesized: meta._generatedAt ?? null,
+            hasError,
+            locked,
+            architectTokens: archTokens > 0 ? archTokens : null,
+            builderTokens: buildTokens > 0 ? buildTokens : null,
+            criticTokens: critTokens > 0 ? critTokens : null,
+            children: node.children.length,
+            node,
+            meta,
+        });
+    }
+    return {
+        summary: {
+            total: entries.length,
+            stale: staleCount,
+            errors: errorCount,
+            locked: lockedCount,
+            neverSynthesized: neverSynthesizedCount,
+            tokens: {
+                architect: totalArchTokens,
+                builder: totalBuilderTokens,
+                critic: totalCriticTokens,
+            },
+            stalestPath,
+            lastSynthesizedPath: lastSynthPath,
+            lastSynthesizedAt: lastSynthAt,
+        },
+        entries,
+        tree,
+    };
+}
+
 /**
  * Compute the file scope owned by a meta node.
  *
@@ -690,80 +900,6 @@ class GatewayExecutor {
     }
 }
 
-/**
- * File-system lock for preventing concurrent synthesis on the same meta.
- *
- * Lock file: .meta/.lock containing PID + timestamp.
- * Stale timeout: 30 minutes.
- *
- * @module lock
- */
-const LOCK_FILE = '.lock';
-const STALE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
-/**
- * Attempt to acquire a lock on a .meta directory.
- *
- * @param metaPath - Absolute path to the .meta directory.
- * @returns True if lock was acquired, false if already locked (non-stale).
- */
-function acquireLock(metaPath) {
-    const lockPath = join(metaPath, LOCK_FILE);
-    if (existsSync(lockPath)) {
-        try {
-            const raw = readFileSync(lockPath, 'utf8');
-            const data = JSON.parse(raw);
-            const lockAge = Date.now() - new Date(data.startedAt).getTime();
-            if (lockAge < STALE_TIMEOUT_MS) {
-                return false; // Lock is active
-            }
-            // Stale lock — fall through to overwrite
-        }
-        catch {
-            // Corrupt lock file — overwrite
-        }
-    }
-    const lock = {
-        pid: process.pid,
-        startedAt: new Date().toISOString(),
-    };
-    writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n');
-    return true;
-}
-/**
- * Release a lock on a .meta directory.
- *
- * @param metaPath - Absolute path to the .meta directory.
- */
-function releaseLock(metaPath) {
-    const lockPath = join(metaPath, LOCK_FILE);
-    try {
-        unlinkSync(lockPath);
-    }
-    catch {
-        // Already removed or never existed
-    }
-}
-/**
- * Check if a .meta directory is currently locked (non-stale).
- *
- * @param metaPath - Absolute path to the .meta directory.
- * @returns True if locked and not stale.
- */
-function isLocked(metaPath) {
-    const lockPath = join(metaPath, LOCK_FILE);
-    if (!existsSync(lockPath))
-        return false;
-    try {
-        const raw = readFileSync(lockPath, 'utf8');
-        const data = JSON.parse(raw);
-        const lockAge = Date.now() - new Date(data.startedAt).getTime();
-        return lockAge < STALE_TIMEOUT_MS;
-    }
-    catch {
-        return false; // Corrupt lock = not locked
-    }
-}
-
 /**
  * Build the SynthContext for a synthesis cycle.
  *
@@ -1557,16 +1693,31 @@ class HttpWatcherClient {
         throw new Error('Retry exhausted');
     }
     async scan(params) {
-        const body = {};
-        if (params.pathPrefix !== undefined) {
-            body.pathPrefix = params.pathPrefix;
+        // Build Qdrant filter: merge explicit filter with pathPrefix/modifiedAfter
+        const mustClauses = [];
+        // Carry over any existing 'must' clauses from the provided filter
+        if (params.filter) {
+            const existing = params.filter.must;
+            if (Array.isArray(existing)) {
+                mustClauses.push(...existing);
+            }
         }
-        if (params.filter !== undefined) {
-            body.filter = params.filter;
+        // Translate pathPrefix into a Qdrant text match on file_path
+        if (params.pathPrefix !== undefined) {
+            mustClauses.push({
+                key: 'file_path',
+                match: { text: params.pathPrefix },
+            });
         }
+        // Translate modifiedAfter into a Qdrant range filter on modified_at
         if (params.modifiedAfter !== undefined) {
-            body.modifiedAfter = params.modifiedAfter;
+            mustClauses.push({
+                key: 'modified_at',
+                range: { gt: params.modifiedAfter },
+            });
         }
+        const filter = { must: mustClauses };
+        const body = { filter };
         if (params.fields !== undefined) {
             body.fields = params.fields;
         }
@@ -1630,6 +1781,7 @@ var index = /*#__PURE__*/Object.freeze({
     isLocked: isLocked,
     isStale: isStale,
     listArchiveFiles: listArchiveFiles,
+    listMetas: listMetas,
     loadSynthConfig: loadSynthConfig,
     mergeAndWrite: mergeAndWrite,
     metaJsonSchema: metaJsonSchema,
@@ -1700,85 +1852,36 @@ function output(data) {
 }
 async function runStatus(config) {
     const watcher = new HttpWatcherClient({ baseUrl: config.watcherUrl });
-    const metaPaths = await discoverMetas(config, watcher);
-    const tree = buildOwnershipTree(metaPaths);
-    let stale = 0;
-    let errors = 0;
-    let locked = 0;
-    let neverSynth = 0;
-    let archTokens = 0;
-    let buildTokens = 0;
-    let critTokens = 0;
-    for (const node of tree.nodes.values()) {
-        let meta;
-        try {
-            meta = readMeta(node.metaPath);
-        }
-        catch {
-            continue;
-        }
-        const s = actualStaleness(meta);
-        if (s > 0)
-            stale++;
-        if (meta._error)
-            errors++;
-        if (isLocked(normalizePath$1(node.metaPath)))
-            locked++;
-        if (!meta._generatedAt)
-            neverSynth++;
-        if (meta._architectTokens)
-            archTokens += meta._architectTokens;
-        if (meta._builderTokens)
-            buildTokens += meta._builderTokens;
-        if (meta._criticTokens)
-            critTokens += meta._criticTokens;
-    }
-    output({
-        total: tree.nodes.size,
-        stale,
-        errors,
-        locked,
-        neverSynthesized: neverSynth,
-        tokens: { architect: archTokens, builder: buildTokens, critic: critTokens },
-    });
+    const result = await listMetas(config, watcher);
+    output(result.summary);
 }
 async function runList(config) {
     const prefix = getArg('--prefix');
     const filter = getArg('--filter');
     const watcher = new HttpWatcherClient({ baseUrl: config.watcherUrl });
-    const metaPaths = await discoverMetas(config, watcher);
-    const tree = buildOwnershipTree(metaPaths);
-    const rows = [];
-    for (const node of tree.nodes.values()) {
-        if (prefix && !node.metaPath.includes(prefix))
-            continue;
-        let meta;
-        try {
-            meta = readMeta(node.metaPath);
-        }
-        catch {
-            continue;
-        }
-        const s = actualStaleness(meta);
-        const hasError = Boolean(meta._error);
-        const isLockedNow = isLocked(normalizePath$1(node.metaPath));
-        if (filter === 'hasError' && !hasError)
-            continue;
-        if (filter === 'stale' && s <= 0)
-            continue;
-        if (filter === 'locked' && !isLockedNow)
-            continue;
-        if (filter === 'never' && meta._generatedAt)
-            continue;
-        rows.push({
-            path: node.metaPath,
-            depth: meta._depth ?? node.treeDepth,
-            staleness: s === Infinity ? 'never' : String(Math.round(s)) + 's',
-            hasError,
-            locked: isLockedNow,
-            children: node.children.length,
-        });
-    }
+    const result = await listMetas(config, watcher);
+    let entries = result.entries;
+    if (prefix) {
+        entries = entries.filter((e) => e.path.includes(prefix));
+    }
+    if (filter === 'hasError')
+        entries = entries.filter((e) => e.hasError);
+    if (filter === 'stale')
+        entries = entries.filter((e) => e.stalenessSeconds > 0);
+    if (filter === 'locked')
+        entries = entries.filter((e) => e.locked);
+    if (filter === 'never')
+        entries = entries.filter((e) => e.stalenessSeconds === Infinity);
+    const rows = entries.map((e) => ({
+        path: e.path,
+        depth: e.depth,
+        staleness: e.stalenessSeconds === Infinity
+            ? 'never'
+            : String(Math.round(e.stalenessSeconds)) + 's',
+        hasError: e.hasError,
+        locked: e.locked,
+        children: e.children,
+    }));
     output({ total: rows.length, items: rows });
 }
 async function runDetail(config) {
@@ -1789,10 +1892,9 @@ async function runDetail(config) {
     }
     const archiveArg = getArg('--archive');
     const watcher = new HttpWatcherClient({ baseUrl: config.watcherUrl });
-    const metaPaths = await discoverMetas(config, watcher);
-    const tree = buildOwnershipTree(metaPaths);
+    const metaResult = await listMetas(config, watcher);
     const normalized = normalizePath$1(targetPath);
-    const node = findNode(tree, normalized);
+    const node = findNode(metaResult.tree, normalized);
     if (!node) {
         console.error('Meta not found: ' + targetPath);
         process.exit(1);
@@ -1813,33 +1915,26 @@ async function runDetail(config) {
 }
 async function runPreview(config) {
     const targetPath = getArg('--path');
-    const { filterInScope, paginatedScan, readLatestArchive, computeStructureHash, selectCandidate, } = await Promise.resolve().then(function () { return index; });
+    const { filterInScope, paginatedScan, readLatestArchive, computeStructureHash, } = await Promise.resolve().then(function () { return index; });
     const watcher = new HttpWatcherClient({ baseUrl: config.watcherUrl });
-    const metaPaths = await discoverMetas(config, watcher);
-    const tree = buildOwnershipTree(metaPaths);
+    const metaResult = await listMetas(config, watcher);
     let targetNode;
     if (targetPath) {
         const normalized = normalizePath$1(targetPath);
-        targetNode = findNode(tree, normalized);
+        targetNode = findNode(metaResult.tree, normalized);
         if (!targetNode) {
             console.error('Meta not found: ' + targetPath);
             process.exit(1);
         }
     }
     else {
-        const candidates = [];
-        for (const node of tree.nodes.values()) {
-            let meta;
-            try {
-                meta = readMeta(node.metaPath);
-            }
-            catch {
-                continue;
-            }
-            const s = actualStaleness(meta);
-            if (s > 0)
-                candidates.push({ node, meta, actualStaleness: s });
-        }
+        const candidates = metaResult.entries
+            .filter((e) => e.stalenessSeconds > 0)
+            .map((e) => ({
+            node: e.node,
+            meta: e.meta,
+            actualStaleness: e.stalenessSeconds,
+        }));
         const weighted = computeEffectiveStaleness(candidates, config.depthWeight);
         const winner = selectCandidate(weighted);
         if (!winner) {

package/dist/index.d.ts

@@ -389,6 +389,80 @@ interface OwnershipTree {
     roots: MetaNode[];
 }
 
+/**
+ * Unified meta listing: scan, dedup, enrich.
+ *
+ * Single source of truth for all consumers that need a list of metas
+ * with enriched metadata. Replaces duplicated scan+dedup logic in
+ * plugin tools, CLI, and prompt injection.
+ *
+ * @module discovery/listMetas
+ */
+
+/** Enriched meta entry returned by listMetas(). */
+interface MetaEntry {
+    /** Normalized .meta/ directory path. */
+    path: string;
+    /** Tree depth (0 = leaf, higher = more abstract). */
+    depth: number;
+    /** Scheduling emphasis multiplier. */
+    emphasis: number;
+    /** Seconds since last synthesis, or Infinity if never synthesized. */
+    stalenessSeconds: number;
+    /** ISO timestamp of last synthesis, or null. */
+    lastSynthesized: string | null;
+    /** Whether the last synthesis had an error. */
+    hasError: boolean;
+    /** Whether this meta is currently locked. */
+    locked: boolean;
+    /** Cumulative architect tokens, or null if never run. */
+    architectTokens: number | null;
+    /** Cumulative builder tokens, or null if never run. */
+    builderTokens: number | null;
+    /** Cumulative critic tokens, or null if never run. */
+    criticTokens: number | null;
+    /** Number of direct children in the ownership tree. */
+    children: number;
+    /** The underlying MetaNode from the ownership tree. */
+    node: MetaNode;
+    /** The parsed meta.json content. */
+    meta: MetaJson;
+}
+/** Summary statistics computed from the meta list. */
+interface MetaListSummary {
+    total: number;
+    stale: number;
+    errors: number;
+    locked: number;
+    neverSynthesized: number;
+    tokens: {
+        architect: number;
+        builder: number;
+        critic: number;
+    };
+    stalestPath: string | null;
+    lastSynthesizedPath: string | null;
+    lastSynthesizedAt: string | null;
+}
+/** Full result from listMetas(). */
+interface MetaListResult {
+    summary: MetaListSummary;
+    entries: MetaEntry[];
+    tree: OwnershipTree;
+}
+/**
+ * Discover, deduplicate, and enrich all metas.
+ *
+ * This is the single consolidated function that replaces all duplicated
+ * scan+dedup+enrich logic across the codebase. All enrichment comes from
+ * reading meta.json on disk (the canonical source).
+ *
+ * @param config - Validated synthesis config.
+ * @param watcher - Watcher HTTP client for discovery.
+ * @returns Enriched meta list with summary statistics and ownership tree.
+ */
+declare function listMetas(config: SynthConfig, watcher: WatcherClient): Promise<MetaListResult>;
+
 /**
  * Build the ownership tree from discovered .meta/ paths.
  *
@@ -895,5 +969,5 @@ declare class HttpWatcherClient implements WatcherClient {
     unregisterRules(source: string): Promise<void>;
 }
 
-export { GatewayExecutor, HttpWatcherClient, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildMetaFilter, buildOwnershipTree, computeEffectiveStaleness, computeEma, computeStructureHash, createSnapshot, discoverMetas, filterInScope, findNode, getScopePrefix, hasSteerChanged, isArchitectTriggered, isLocked, isStale, listArchiveFiles, loadSynthConfig, mergeAndWrite, metaJsonSchema, normalizePath, orchestrate, paginatedScan, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, releaseLock, resolveConfigPath, selectCandidate, synthConfigSchema, synthErrorSchema, toSynthError };
-export type { BuilderOutput, GatewayExecutorOptions, HttpWatcherClientOptions, InferenceRuleSpec, MergeOptions, MetaJson, MetaNode, OrchestrateResult, OwnershipTree, ScanFile, ScanParams, ScanResponse, StalenessCandidate, SynthConfig, SynthContext, SynthError, SynthExecutor, SynthSpawnOptions, SynthSpawnResult, WatcherClient };
+export { GatewayExecutor, HttpWatcherClient, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildMetaFilter, buildOwnershipTree, computeEffectiveStaleness, computeEma, computeStructureHash, createSnapshot, discoverMetas, filterInScope, findNode, getScopePrefix, hasSteerChanged, isArchitectTriggered, isLocked, isStale, listArchiveFiles, listMetas, loadSynthConfig, mergeAndWrite, metaJsonSchema, normalizePath, orchestrate, paginatedScan, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, releaseLock, resolveConfigPath, selectCandidate, synthConfigSchema, synthErrorSchema, toSynthError };
+export type { BuilderOutput, GatewayExecutorOptions, HttpWatcherClientOptions, InferenceRuleSpec, MergeOptions, MetaEntry, MetaJson, MetaListResult, MetaListSummary, MetaNode, OrchestrateResult, OwnershipTree, ScanFile, ScanParams, ScanResponse, StalenessCandidate, SynthConfig, SynthContext, SynthError, SynthExecutor, SynthSpawnOptions, SynthSpawnResult, WatcherClient };

package/dist/index.js

@@ -371,6 +371,10 @@ function buildMetaFilter(config) {
                 key: 'domains',
                 match: { value: config.metaProperty.domains[0] },
             },
+            {
+                key: 'file_path',
+                match: { text: 'meta.json' },
+            },
         ],
     };
 }
@@ -390,21 +394,95 @@ async function discoverMetas(config, watcher) {
         filter,
         fields: ['file_path'],
     });
-    // Deduplicate by file_path (multi-chunk files)
+    // Deduplicate by .meta/ directory path (handles multi-chunk files)
     const seen = new Set();
     const metaPaths = [];
     for (const sf of scanFiles) {
         const fp = normalizePath$1(sf.file_path);
-        if (seen.has(fp))
-            continue;
-        seen.add(fp);
         // Derive .meta/ directory from file_path (strip /meta.json)
         const metaPath = fp.replace(/\/meta\.json$/, '');
+        if (seen.has(metaPath))
+            continue;
+        seen.add(metaPath);
         metaPaths.push(metaPath);
     }
     return metaPaths;
 }
 
+/**
+ * File-system lock for preventing concurrent synthesis on the same meta.
+ *
+ * Lock file: .meta/.lock containing PID + timestamp.
+ * Stale timeout: 30 minutes.
+ *
+ * @module lock
+ */
+const LOCK_FILE = '.lock';
+const STALE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+/**
+ * Attempt to acquire a lock on a .meta directory.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns True if lock was acquired, false if already locked (non-stale).
+ */
+function acquireLock(metaPath) {
+    const lockPath = join(metaPath, LOCK_FILE);
+    if (existsSync(lockPath)) {
+        try {
+            const raw = readFileSync(lockPath, 'utf8');
+            const data = JSON.parse(raw);
+            const lockAge = Date.now() - new Date(data.startedAt).getTime();
+            if (lockAge < STALE_TIMEOUT_MS) {
+                return false; // Lock is active
+            }
+            // Stale lock — fall through to overwrite
+        }
+        catch {
+            // Corrupt lock file — overwrite
+        }
+    }
+    const lock = {
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+    };
+    writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n');
+    return true;
+}
+/**
+ * Release a lock on a .meta directory.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ */
+function releaseLock(metaPath) {
+    const lockPath = join(metaPath, LOCK_FILE);
+    try {
+        unlinkSync(lockPath);
+    }
+    catch {
+        // Already removed or never existed
+    }
+}
+/**
+ * Check if a .meta directory is currently locked (non-stale).
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns True if locked and not stale.
+ */
+function isLocked(metaPath) {
+    const lockPath = join(metaPath, LOCK_FILE);
+    if (!existsSync(lockPath))
+        return false;
+    try {
+        const raw = readFileSync(lockPath, 'utf8');
+        const data = JSON.parse(raw);
+        const lockAge = Date.now() - new Date(data.startedAt).getTime();
+        return lockAge < STALE_TIMEOUT_MS;
+    }
+    catch {
+        return false; // Corrupt lock = not locked
+    }
+}
+
 /**
  * Build the ownership tree from discovered .meta/ paths.
  *
@@ -482,6 +560,138 @@ function findNode(tree, targetPath) {
     return Array.from(tree.nodes.values()).find((n) => n.metaPath === targetPath || n.ownerPath === targetPath);
 }
 
+/**
+ * Unified meta listing: scan, dedup, enrich.
+ *
+ * Single source of truth for all consumers that need a list of metas
+ * with enriched metadata. Replaces duplicated scan+dedup logic in
+ * plugin tools, CLI, and prompt injection.
+ *
+ * @module discovery/listMetas
+ */
+/**
+ * Discover, deduplicate, and enrich all metas.
+ *
+ * This is the single consolidated function that replaces all duplicated
+ * scan+dedup+enrich logic across the codebase. All enrichment comes from
+ * reading meta.json on disk (the canonical source).
+ *
+ * @param config - Validated synthesis config.
+ * @param watcher - Watcher HTTP client for discovery.
+ * @returns Enriched meta list with summary statistics and ownership tree.
+ */
+async function listMetas(config, watcher) {
+    // Step 1: Discover deduplicated meta paths via watcher scan
+    const metaPaths = await discoverMetas(config, watcher);
+    // Step 2: Build ownership tree
+    const tree = buildOwnershipTree(metaPaths);
+    // Step 3: Read and enrich each meta from disk
+    const entries = [];
+    let staleCount = 0;
+    let errorCount = 0;
+    let lockedCount = 0;
+    let neverSynthesizedCount = 0;
+    let totalArchTokens = 0;
+    let totalBuilderTokens = 0;
+    let totalCriticTokens = 0;
+    let lastSynthPath = null;
+    let lastSynthAt = null;
+    let stalestPath = null;
+    let stalestEffective = -1;
+    for (const node of tree.nodes.values()) {
+        let meta;
+        try {
+            meta = JSON.parse(readFileSync(join(node.metaPath, 'meta.json'), 'utf8'));
+        }
+        catch {
+            // Skip unreadable metas
+            continue;
+        }
+        const depth = meta._depth ?? node.treeDepth;
+        const emphasis = meta._emphasis ?? 1;
+        const hasError = Boolean(meta._error);
+        const locked = isLocked(normalizePath$1(node.metaPath));
+        const neverSynth = !meta._generatedAt;
+        // Compute staleness
+        let stalenessSeconds;
+        if (neverSynth) {
+            stalenessSeconds = Infinity;
+        }
+        else {
+            const genAt = new Date(meta._generatedAt).getTime();
+            stalenessSeconds = Math.max(0, Math.floor((Date.now() - genAt) / 1000));
+        }
+        // Tokens
+        const archTokens = meta._architectTokens ?? 0;
+        const buildTokens = meta._builderTokens ?? 0;
+        const critTokens = meta._criticTokens ?? 0;
+        // Accumulate summary stats
+        if (stalenessSeconds > 0)
+            staleCount++;
+        if (hasError)
+            errorCount++;
+        if (locked)
+            lockedCount++;
+        if (neverSynth)
+            neverSynthesizedCount++;
+        totalArchTokens += archTokens;
+        totalBuilderTokens += buildTokens;
+        totalCriticTokens += critTokens;
+        // Track last synthesized
+        if (meta._generatedAt) {
+            if (!lastSynthAt || meta._generatedAt > lastSynthAt) {
+                lastSynthAt = meta._generatedAt;
+                lastSynthPath = node.metaPath;
+            }
+        }
+        // Track stalest (effective staleness for scheduling)
+        const depthFactor = Math.pow(1 + config.depthWeight, depth);
+        const effectiveStaleness = (stalenessSeconds === Infinity
+            ? Number.MAX_SAFE_INTEGER
+            : stalenessSeconds) *
+            depthFactor *
+            emphasis;
+        if (effectiveStaleness > stalestEffective) {
+            stalestEffective = effectiveStaleness;
+            stalestPath = node.metaPath;
+        }
+        entries.push({
+            path: node.metaPath,
+            depth,
+            emphasis,
+            stalenessSeconds,
+            lastSynthesized: meta._generatedAt ?? null,
+            hasError,
+            locked,
+            architectTokens: archTokens > 0 ? archTokens : null,
+            builderTokens: buildTokens > 0 ? buildTokens : null,
+            criticTokens: critTokens > 0 ? critTokens : null,
+            children: node.children.length,
+            node,
+            meta,
+        });
+    }
+    return {
+        summary: {
+            total: entries.length,
+            stale: staleCount,
+            errors: errorCount,
+            locked: lockedCount,
+            neverSynthesized: neverSynthesizedCount,
+            tokens: {
+                architect: totalArchTokens,
+                builder: totalBuilderTokens,
+                critic: totalCriticTokens,
+            },
+            stalestPath,
+            lastSynthesizedPath: lastSynthPath,
+            lastSynthesizedAt: lastSynthAt,
+        },
+        entries,
+        tree,
+    };
+}
+
 /**
  * Compute the file scope owned by a meta node.
  *
@@ -675,80 +885,6 @@ class GatewayExecutor {
     }
 }
 
-/**
- * File-system lock for preventing concurrent synthesis on the same meta.
- *
- * Lock file: .meta/.lock containing PID + timestamp.
- * Stale timeout: 30 minutes.
- *
- * @module lock
- */
-const LOCK_FILE = '.lock';
-const STALE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
-/**
- * Attempt to acquire a lock on a .meta directory.
- *
- * @param metaPath - Absolute path to the .meta directory.
- * @returns True if lock was acquired, false if already locked (non-stale).
- */
-function acquireLock(metaPath) {
-    const lockPath = join(metaPath, LOCK_FILE);
-    if (existsSync(lockPath)) {
-        try {
-            const raw = readFileSync(lockPath, 'utf8');
-            const data = JSON.parse(raw);
-            const lockAge = Date.now() - new Date(data.startedAt).getTime();
-            if (lockAge < STALE_TIMEOUT_MS) {
-                return false; // Lock is active
-            }
-            // Stale lock — fall through to overwrite
-        }
-        catch {
-            // Corrupt lock file — overwrite
-        }
-    }
-    const lock = {
-        pid: process.pid,
-        startedAt: new Date().toISOString(),
-    };
-    writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n');
-    return true;
-}
-/**
- * Release a lock on a .meta directory.
- *
- * @param metaPath - Absolute path to the .meta directory.
- */
-function releaseLock(metaPath) {
-    const lockPath = join(metaPath, LOCK_FILE);
-    try {
-        unlinkSync(lockPath);
-    }
-    catch {
-        // Already removed or never existed
-    }
-}
-/**
- * Check if a .meta directory is currently locked (non-stale).
- *
- * @param metaPath - Absolute path to the .meta directory.
- * @returns True if locked and not stale.
- */
-function isLocked(metaPath) {
-    const lockPath = join(metaPath, LOCK_FILE);
-    if (!existsSync(lockPath))
-        return false;
-    try {
-        const raw = readFileSync(lockPath, 'utf8');
-        const data = JSON.parse(raw);
-        const lockAge = Date.now() - new Date(data.startedAt).getTime();
-        return lockAge < STALE_TIMEOUT_MS;
-    }
-    catch {
-        return false; // Corrupt lock = not locked
-    }
-}
-
 /**
  * Build the SynthContext for a synthesis cycle.
  *
@@ -1542,16 +1678,31 @@ class HttpWatcherClient {
         throw new Error('Retry exhausted');
     }
     async scan(params) {
-        const body = {};
-        if (params.pathPrefix !== undefined) {
-            body.pathPrefix = params.pathPrefix;
+        // Build Qdrant filter: merge explicit filter with pathPrefix/modifiedAfter
+        const mustClauses = [];
+        // Carry over any existing 'must' clauses from the provided filter
+        if (params.filter) {
+            const existing = params.filter.must;
+            if (Array.isArray(existing)) {
+                mustClauses.push(...existing);
+            }
         }
-        if (params.filter !== undefined) {
-            body.filter = params.filter;
+        // Translate pathPrefix into a Qdrant text match on file_path
+        if (params.pathPrefix !== undefined) {
+            mustClauses.push({
+                key: 'file_path',
+                match: { text: params.pathPrefix },
+            });
         }
+        // Translate modifiedAfter into a Qdrant range filter on modified_at
         if (params.modifiedAfter !== undefined) {
-            body.modifiedAfter = params.modifiedAfter;
+            mustClauses.push({
+                key: 'modified_at',
+                range: { gt: params.modifiedAfter },
+            });
         }
+        const filter = { must: mustClauses };
+        const body = { filter };
         if (params.fields !== undefined) {
             body.fields = params.fields;
         }
@@ -1584,4 +1735,4 @@ class HttpWatcherClient {
     }
 }
 
-export { GatewayExecutor, HttpWatcherClient, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildMetaFilter, buildOwnershipTree, computeEffectiveStaleness, computeEma, computeStructureHash, createSnapshot, discoverMetas, filterInScope, findNode, getScopePrefix, hasSteerChanged, isArchitectTriggered, isLocked, isStale, listArchiveFiles, loadSynthConfig, mergeAndWrite, metaJsonSchema, normalizePath$1 as normalizePath, orchestrate, paginatedScan, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, releaseLock, resolveConfigPath, selectCandidate, synthConfigSchema, synthErrorSchema, toSynthError };
+export { GatewayExecutor, HttpWatcherClient, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildMetaFilter, buildOwnershipTree, computeEffectiveStaleness, computeEma, computeStructureHash, createSnapshot, discoverMetas, filterInScope, findNode, getScopePrefix, hasSteerChanged, isArchitectTriggered, isLocked, isStale, listArchiveFiles, listMetas, loadSynthConfig, mergeAndWrite, metaJsonSchema, normalizePath$1 as normalizePath, orchestrate, paginatedScan, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, releaseLock, resolveConfigPath, selectCandidate, synthConfigSchema, synthErrorSchema, toSynthError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/jeeves-meta",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "author": "Jason Williscroft",
   "description": "Knowledge synthesis engine for the Jeeves platform",
   "license": "BSD-3-Clause",