@karmaniverous/jeeves-meta 0.17.0 → 0.18.0-1

package/dist/cli/jeeves-meta/index.js

@@ -2,125 +2,18 @@
 import { sleepAsync, fetchWithTimeout, createConfigQueryHandler, atomicWrite, createStatusHandler, getBindAddress, fetchJson, postJson, getServiceUrl, jeevesComponentDescriptorSchema, createServiceCli } from '@karmaniverous/jeeves';
 import { normalizePath, metaConfigSchema, getEndpoint, META_COMPONENT } from '@karmaniverous/jeeves-meta-core';
 import fs, { unlinkSync, writeFileSync, existsSync, readFileSync, statSync, mkdirSync, readdirSync, watchFile } from 'node:fs';
-import path, { join, dirname, relative, posix, resolve } from 'node:path';
+import path, { join, dirname, relative, posix, sep, resolve } from 'node:path';
 import { readFile, unlink, mkdir, writeFile, copyFile } from 'node:fs/promises';
 import { z } from 'zod';
 import { randomUUID, createHash } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import pino from 'pino';
-import Handlebars from 'handlebars';
 import { fileURLToPath } from 'node:url';
 import process$1 from 'node:process';
+import Handlebars from 'handlebars';
 import { Cron } from 'croner';
 import Fastify from 'fastify';
 
-/**
- * Compute summary statistics from an array of MetaEntry objects.
- *
- * Shared between listMetas() (full list) and route handlers (filtered lists).
- *
- * @module discovery/computeSummary
- */
-/**
- * Compute summary statistics from a list of meta entries.
- *
- * @param entries - Enriched meta entries (full or filtered).
- * @param depthWeight - Config depth weight for effective staleness calculation.
- * @returns Aggregated summary statistics.
- */
-function computeSummary(entries, depthWeight) {
-    let staleCount = 0;
-    let errorCount = 0;
-    let lockedCount = 0;
-    let disabledCount = 0;
-    let neverSynthesizedCount = 0;
-    let totalArchitectTokens = 0;
-    let totalBuilderTokens = 0;
-    let totalCriticTokens = 0;
-    let stalestPath = null;
-    let stalestEffective = -1;
-    let lastSynthesizedPath = null;
-    let lastSynthesizedAt = null;
-    for (const e of entries) {
-        if (e.stalenessSeconds > 0)
-            staleCount++;
-        if (e.hasError)
-            errorCount++;
-        if (e.locked)
-            lockedCount++;
-        if (e.disabled)
-            disabledCount++;
-        if (e.lastSynthesized === null)
-            neverSynthesizedCount++;
-        totalArchitectTokens += e.architectTokens ?? 0;
-        totalBuilderTokens += e.builderTokens ?? 0;
-        totalCriticTokens += e.criticTokens ?? 0;
-        // Track last synthesized
-        if (e.lastSynthesized &&
-            (!lastSynthesizedAt || e.lastSynthesized > lastSynthesizedAt)) {
-            lastSynthesizedAt = e.lastSynthesized;
-            lastSynthesizedPath = e.path;
-        }
-        // Track stalest (effective staleness for scheduling)
-        const depthFactor = Math.pow(1 + depthWeight, e.depth);
-        const effectiveStaleness = e.stalenessSeconds * depthFactor * e.emphasis;
-        if (effectiveStaleness > stalestEffective) {
-            stalestEffective = effectiveStaleness;
-            stalestPath = e.path;
-        }
-    }
-    return {
-        total: entries.length,
-        stale: staleCount,
-        errors: errorCount,
-        locked: lockedCount,
-        disabled: disabledCount,
-        neverSynthesized: neverSynthesizedCount,
-        tokens: {
-            architect: totalArchitectTokens,
-            builder: totalBuilderTokens,
-            critic: totalCriticTokens,
-        },
-        stalestPath,
-        lastSynthesizedPath,
-        lastSynthesizedAt,
-    };
-}
-
-/**
- * Discover .meta/ directories via watcher `/walk` endpoint.
- *
- * Uses filesystem enumeration through the watcher (not Qdrant) to find
- * all `.meta/meta.json` files and returns deduplicated meta directory paths.
- *
- * @module discovery/discoverMetas
- */
-/**
- * Discover all .meta/ directories via watcher walk.
- *
- * Uses the watcher's `/walk` endpoint to find all `.meta/meta.json` files
- * and returns deduplicated meta directory paths.
- *
- * @param watcher - WatcherClient for walk queries.
- * @returns Array of normalized .meta/ directory paths.
- */
-async function discoverMetas(watcher) {
-    const allPaths = await watcher.walk(['**/.meta/meta.json']);
-    // Deduplicate by .meta/ directory path (handles multi-chunk files)
-    const seen = new Set();
-    const metaPaths = [];
-    for (const filePath of allPaths) {
-        const fp = normalizePath(filePath);
-        // 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;
-}
-
 /**
  * Retrieve the nearest ancestor meta node from the ownership tree.
  *
@@ -426,6 +319,113 @@ function computeStalenessScore(stalenessSeconds, depth, emphasis, depthWeight) {
     return Math.min(1, (stalenessSeconds * depthFactor * emphasis) / (30 * 86400));
 }
 
+/**
+ * Compute summary statistics from an array of MetaEntry objects.
+ *
+ * Shared between listMetas() (full list) and route handlers (filtered lists).
+ *
+ * @module discovery/computeSummary
+ */
+/**
+ * Compute summary statistics from a list of meta entries.
+ *
+ * @param entries - Enriched meta entries (full or filtered).
+ * @param depthWeight - Config depth weight for effective staleness calculation.
+ * @returns Aggregated summary statistics.
+ */
+function computeSummary(entries, depthWeight) {
+    let staleCount = 0;
+    let errorCount = 0;
+    let lockedCount = 0;
+    let disabledCount = 0;
+    let neverSynthesizedCount = 0;
+    let totalArchitectTokens = 0;
+    let totalBuilderTokens = 0;
+    let totalCriticTokens = 0;
+    let stalestPath = null;
+    let stalestEffective = -1;
+    let lastSynthesizedPath = null;
+    let lastSynthesizedAt = null;
+    for (const e of entries) {
+        if (e.stalenessSeconds > 0)
+            staleCount++;
+        if (e.hasError)
+            errorCount++;
+        if (e.locked)
+            lockedCount++;
+        if (e.disabled)
+            disabledCount++;
+        if (e.lastSynthesized === null)
+            neverSynthesizedCount++;
+        totalArchitectTokens += e.architectTokens ?? 0;
+        totalBuilderTokens += e.builderTokens ?? 0;
+        totalCriticTokens += e.criticTokens ?? 0;
+        // Track last synthesized
+        if (e.lastSynthesized &&
+            (!lastSynthesizedAt || e.lastSynthesized > lastSynthesizedAt)) {
+            lastSynthesizedAt = e.lastSynthesized;
+            lastSynthesizedPath = e.path;
+        }
+        // Track stalest (effective staleness for scheduling)
+        const depthFactor = Math.pow(1 + depthWeight, e.depth);
+        const effectiveStaleness = e.stalenessSeconds * depthFactor * e.emphasis;
+        if (effectiveStaleness > stalestEffective) {
+            stalestEffective = effectiveStaleness;
+            stalestPath = e.path;
+        }
+    }
+    return {
+        total: entries.length,
+        stale: staleCount,
+        errors: errorCount,
+        locked: lockedCount,
+        disabled: disabledCount,
+        neverSynthesized: neverSynthesizedCount,
+        tokens: {
+            architect: totalArchitectTokens,
+            builder: totalBuilderTokens,
+            critic: totalCriticTokens,
+        },
+        stalestPath,
+        lastSynthesizedPath,
+        lastSynthesizedAt,
+    };
+}
+
+/**
+ * Discover .meta/ directories via watcher `/walk` endpoint.
+ *
+ * Uses filesystem enumeration through the watcher (not Qdrant) to find
+ * all `.meta/meta.json` files and returns deduplicated meta directory paths.
+ *
+ * @module discovery/discoverMetas
+ */
+/**
+ * Discover all .meta/ directories via watcher walk.
+ *
+ * Uses the watcher's `/walk` endpoint to find all `.meta/meta.json` files
+ * and returns deduplicated meta directory paths.
+ *
+ * @param watcher - WatcherClient for walk queries.
+ * @returns Array of normalized .meta/ directory paths.
+ */
+async function discoverMetas(watcher) {
+    const allPaths = await watcher.walk(['**/.meta/meta.json']);
+    // Deduplicate by .meta/ directory path (handles multi-chunk files)
+    const seen = new Set();
+    const metaPaths = [];
+    for (const filePath of allPaths) {
+        const fp = normalizePath(filePath);
+        // 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;
+}
+
 /**
  * Build the ownership tree from discovered .meta/ paths.
  *
@@ -1251,1284 +1251,1233 @@ function createLogger(config) {
     return pino({ level });
 }
 
-const toPath = urlOrPath => urlOrPath instanceof URL ? fileURLToPath(urlOrPath) : urlOrPath;
-
-function findUpSync(name, {
-	cwd = process$1.cwd(),
-	type = 'file',
-	stopAt,
-} = {}) {
-	let directory = path.resolve(toPath(cwd) ?? '');
-	const {root} = path.parse(directory);
-	stopAt = path.resolve(directory, toPath(stopAt) ?? root);
-	const isAbsoluteName = path.isAbsolute(name);
-
-	while (directory) {
-		const filePath = isAbsoluteName ? name : path.join(directory, name);
-
-		try {
-			const stats = fs.statSync(filePath, {throwIfNoEntry: false});
-			if ((type === 'file' && stats?.isFile()) || (type === 'directory' && stats?.isDirectory())) {
-				return filePath;
-			}
-		} catch {}
-
-		if (directory === stopAt || directory === root) {
-			break;
-		}
-
-		directory = path.dirname(directory);
-	}
-}
-
-const isTypeOnlyPackageJsonData = packageData => {
-	if (!packageData || typeof packageData !== 'object' || Array.isArray(packageData)) {
-		return false;
-	}
-
-	const keys = Object.keys(packageData);
-	return keys.length === 1 && keys[0] === 'type' && typeof packageData.type === 'string';
-};
-
-const isTypeOnlyPackageJsonSync = filePath => {
-	let fileContents;
-
-	try {
-		fileContents = fs.readFileSync(filePath, 'utf8');
-	} catch {
-		return false;
-	}
-
-	try {
-		return isTypeOnlyPackageJsonData(JSON.parse(fileContents));
-	} catch {
-		return false;
-	}
-};
-
-const getNextSearchDirectory = filePath => {
-	const packageDirectoryPath = path.dirname(filePath);
-	const parentDirectoryPath = path.dirname(packageDirectoryPath);
-	return parentDirectoryPath === packageDirectoryPath ? undefined : parentDirectoryPath;
-};
-
-const findPackageDirectorySync = (directory, ignoreTypeOnlyPackageJson) => {
-	const filePath = findUpSync('package.json', {cwd: directory});
-	if (!filePath) {
-		return undefined;
-	}
-
-	const packageDirectoryPath = path.dirname(filePath);
-	if (!ignoreTypeOnlyPackageJson) {
-		return packageDirectoryPath;
-	}
-
-	if (!isTypeOnlyPackageJsonSync(filePath)) {
-		return packageDirectoryPath;
-	}
-
-	const nextDirectory = getNextSearchDirectory(filePath);
-	if (!nextDirectory) {
-		return undefined;
-	}
-
-	return findPackageDirectorySync(nextDirectory, ignoreTypeOnlyPackageJson);
-};
-
-function packageDirectorySync({cwd, ignoreTypeOnlyPackageJson} = {}) {
-	return findPackageDirectorySync(cwd ?? process$1.cwd(), ignoreTypeOnlyPackageJson);
-}
-
 /**
- * Built-in default prompts for the synthesis pipeline.
+ * Build a minimal MetaNode from a known meta path using watcher walk.
  *
- * Prompts ship as .md files bundled into dist/prompts/ via rollup-plugin-copy.
- * Loaded at runtime relative to the compiled module location.
+ * Used for targeted synthesis (when a specific path is requested) to avoid
+ * the full discovery + ownership tree build. Discovers only immediate child
+ * `.meta/` directories.
  *
- * @module prompts
+ * @module discovery/buildMinimalNode
  */
-const packageRoot = packageDirectorySync({
-    cwd: fileURLToPath(import.meta.url),
-});
-const promptDir = join(packageRoot, 'dist', 'prompts');
-/** Built-in default architect prompt. */
-const DEFAULT_ARCHITECT_PROMPT = readFileSync(join(promptDir, 'architect.md'), 'utf8');
-/** Built-in default critic prompt. */
-const DEFAULT_CRITIC_PROMPT = readFileSync(join(promptDir, 'critic.md'), 'utf8');
-
 /**
- * List archive snapshot files in chronological order.
+ * Build a minimal MetaNode for a known meta path.
  *
- * @module archive/listArchive
- */
-/**
- * List archive .json files sorted chronologically (oldest first).
+ * Walks the owner directory for child `.meta/meta.json` files and constructs
+ * a shallow ownership tree (self + direct children only).
  *
- * @param metaPath - Absolute path to the .meta directory.
- * @returns Array of absolute paths to archive files, or empty if none.
+ * @param metaPath - Absolute path to the `.meta/` directory.
+ * @param watcher - WatcherClient for filesystem enumeration.
+ * @returns MetaNode with direct children wired.
  */
-function listArchiveFiles(metaPath) {
-    const archiveDir = join(metaPath, 'archive');
-    try {
-        return readdirSync(archiveDir)
-            .filter((f) => f.endsWith('.json'))
-            .sort()
-            .map((f) => join(archiveDir, f));
+async function buildMinimalNode(metaPath, watcher) {
+    const normalized = normalizePath(metaPath);
+    const ownerPath = posix.dirname(normalized);
+    // Find child metas using watcher walk.
+    // We include only *direct* children (nearest descendants in the ownership tree)
+    // to match the ownership semantics used elsewhere.
+    const rawMetaJsonPaths = await watcher.walk([
+        `${escapeGlob(ownerPath)}/**/.meta/meta.json`,
+    ]);
+    const candidateMetaPaths = [
+        ...new Set(rawMetaJsonPaths.map((p) => posix.dirname(normalizePath(p)))),
+    ].filter((p) => p !== normalized);
+    const candidates = candidateMetaPaths
+        .map((mp) => ({ metaPath: mp, ownerPath: posix.dirname(mp) }))
+        .sort((a, b) => a.ownerPath.length - b.ownerPath.length);
+    const directChildren = [];
+    for (const c of candidates) {
+        const nestedUnderExisting = directChildren.some((d) => c.ownerPath === d.ownerPath ||
+            c.ownerPath.startsWith(d.ownerPath + '/'));
+        if (!nestedUnderExisting)
+            directChildren.push(c);
     }
-    catch {
-        return [];
+    const children = directChildren.map((c) => ({
+        metaPath: c.metaPath,
+        ownerPath: c.ownerPath,
+        treeDepth: 1,
+        children: [],
+        parent: null,
+    }));
+    const node = {
+        metaPath: normalized,
+        ownerPath,
+        treeDepth: 0,
+        children,
+        parent: null,
+    };
+    for (const child of children) {
+        child.parent = node;
     }
+    return node;
 }
 
 /**
- * Prune old archive snapshots beyond maxArchive.
+ * Pure phase-state transition functions.
  *
- * @module archive/prune
+ * Implements every row of the §8 "Transitions and invalidation cascade" table.
+ * No I/O — pure functions over PhaseState and documented inputs.
+ *
+ * @module phaseState/phaseTransitions
  */
 /**
- * Prune archive directory to keep at most maxArchive snapshots.
- * Removes the oldest files.
- *
- * @param metaPath - Absolute path to the .meta directory.
- * @param maxArchive - Maximum snapshots to retain.
- * @returns Number of files pruned.
+ * Create a fresh (fully-complete) phase state.
  */
-async function pruneArchive(metaPath, maxArchive) {
-    const files = listArchiveFiles(metaPath);
-    const toRemove = files.length - maxArchive;
-    if (toRemove <= 0)
-        return 0;
-    await Promise.all(files.slice(0, toRemove).map(unlink));
-    return toRemove;
+function freshPhaseState() {
+    return { architect: 'fresh', builder: 'fresh', critic: 'fresh' };
 }
-
 /**
- * Archive reading helpers — watcher scan with filesystem fallback.
- *
- * Used by the GET /metas/:path route to retrieve archive history.
- * Prefers watcher scan for performance; falls back to disk reads
- * when the watcher is unavailable.
- *
- * @module archive/readArchive
+ * Create a phase state for a never-synthesized meta (all pending from architect).
  */
-/** Build a Qdrant filter for archive points under a given meta path. */
-function buildArchiveScanFilter(metaPath, metaArchiveProperty) {
-    const must = [
-        {
-            key: 'file_path',
-            match: { text: normalizePath(join(metaPath, 'archive')) },
-        },
-    ];
-    for (const [key, value] of Object.entries(metaArchiveProperty)) {
-        must.push({ key, match: { value } });
-    }
-    return { must };
-}
-/** Extract file_path from a scan point payload. */
-function getArchiveFilePath(point) {
-    const value = point.payload?.file_path;
-    return typeof value === 'string' ? value : '';
-}
-/** Project archive metadata, stripping indexing-internal fields. */
-function projectArchivePayload(point, projectMeta) {
-    const payload = point.payload ?? {};
-    if (Object.keys(payload).length === 0)
-        return null;
-    const archiveMeta = { ...payload };
-    delete archiveMeta.file_path;
-    delete archiveMeta.chunk_text;
-    delete archiveMeta.chunk_index;
-    delete archiveMeta.total_chunks;
-    delete archiveMeta.content_hash;
-    delete archiveMeta.matched_rules;
-    return projectMeta(archiveMeta);
+function initialPhaseState() {
+    return { architect: 'pending', builder: 'stale', critic: 'stale' };
 }
 /**
- * Read archive history via watcher scan.
+ * Enforce the per-meta invariant: at most one phase is pending or running,
+ * and it is the first non-fresh phase in pipeline order.
  *
- * @param watcher - WatcherClient with scan support.
- * @param metaPath - Absolute path to the .meta/ directory.
- * @param metaArchiveProperty - Additional filter properties for archive points.
- * @param limit - Max entries to return (newest first). Undefined = all.
- * @param projectMeta - Field projection function.
- * @returns Array of projected archive entries, newest first.
+ * Stale phases that become the first non-fresh phase are promoted to pending.
  */
-async function readArchiveFromWatcher(watcher, metaPath, metaArchiveProperty, limit, projectMeta) {
-    if (limit === 0)
-        return [];
-    if (!watcher.scan) {
-        throw new Error('Watcher scan not available');
+function enforceInvariant(state) {
+    const result = { ...state };
+    let foundNonFresh = false;
+    for (const phase of ['architect', 'builder', 'critic']) {
+        const s = result[phase];
+        if (s === 'fresh')
+            continue;
+        if (!foundNonFresh) {
+            foundNonFresh = true;
+            // First non-fresh: if stale, promote to pending
+            if (s === 'stale') {
+                result[phase] = 'pending';
+            }
+            // pending, running, failed stay as-is
+        }
+        else {
+            // Subsequent non-fresh: must not be pending or running
+            if (s === 'pending') {
+                result[phase] = 'stale';
+            }
+            // running in non-first position would be a bug, but don't mask it
+        }
     }
-    const points = [];
-    let cursor;
-    do {
-        const result = await watcher.scan({
-            filter: buildArchiveScanFilter(metaPath, metaArchiveProperty),
-            limit: 100,
-            cursor,
-        });
-        points.push(...result.points);
-        cursor = result.cursor ?? undefined;
-    } while (cursor);
-    const sorted = points.sort((a, b) => getArchiveFilePath(a).localeCompare(getArchiveFilePath(b)));
-    return sorted
-        .slice(limit ? -limit : 0)
-        .reverse()
-        .map((point) => projectArchivePayload(point, projectMeta))
-        .filter((value) => value !== null);
+    return result;
 }
+// ── Invalidation cascades ──────────────────────────────────────────────
 /**
- * Read archive history from disk (fallback).
- *
- * @param metaPath - Absolute path to the .meta/ directory.
- * @param limit - Max entries to return (newest first). Undefined = all.
- * @param projectMeta - Field projection function.
- * @returns Array of projected archive entries, newest first.
+ * Architect invalidated: architect → pending; builder, critic → stale.
+ * Triggers: first run, _structureHash change, _steer change,
+ * _crossRefs declaration change, _synthesisCount \>= architectEvery.
  */
-async function readArchiveFromDisk(metaPath, limit, projectMeta) {
-    if (limit === 0)
-        return [];
-    const archiveFiles = listArchiveFiles(metaPath);
-    const selected = (limit ? archiveFiles.slice(-limit) : archiveFiles).reverse();
-    return Promise.all(selected.map(async (archiveFile) => {
-        const raw = await readFile(archiveFile, 'utf8');
-        return projectMeta(JSON.parse(raw));
-    }));
+function invalidateArchitect(state) {
+    return enforceInvariant({
+        architect: state.architect === 'failed' ? 'failed' : 'pending',
+        builder: state.builder === 'fresh' ? 'stale' : state.builder,
+        critic: state.critic === 'fresh' ? 'stale' : state.critic,
+    });
 }
-
 /**
- * Read the latest archive snapshot for steer change detection.
- *
- * @module archive/readLatest
+ * Builder invalidated (scope mtime or cross-ref _content change):
+ * builder → pending; critic → stale.
+ * Only applies when architect is fresh; otherwise, builder stays stale.
  */
+function invalidateBuilder(state) {
+    if (state.architect !== 'fresh') {
+        // Architect is not fresh — builder stays stale (or whatever it is)
+        return enforceInvariant({
+            ...state,
+            builder: state.builder === 'fresh' || state.builder === 'stale'
+                ? 'stale'
+                : state.builder,
+            critic: state.critic === 'fresh' ? 'stale' : state.critic,
+        });
+    }
+    return enforceInvariant({
+        ...state,
+        builder: state.builder === 'failed' ? 'failed' : 'pending',
+        critic: state.critic === 'fresh' ? 'stale' : state.critic,
+    });
+}
+// ── Phase success transitions ──────────────────────────────────────────
 /**
- * Read the most recent archive snapshot.
- *
- * @param metaPath - Absolute path to the .meta directory.
- * @returns The latest archived meta, or null if no archives exist.
+ * Architect completes successfully.
+ * architect → fresh; builder → pending; critic → stale.
  */
-async function readLatestArchive(metaPath) {
-    const files = listArchiveFiles(metaPath);
-    if (files.length === 0)
-        return null;
-    const raw = await readFile(files[files.length - 1], 'utf8');
-    return JSON.parse(raw);
+function architectSuccess(state) {
+    return enforceInvariant({
+        architect: 'fresh',
+        builder: state.builder === 'failed' ? 'failed' : 'pending',
+        critic: state.critic === 'fresh' ? 'stale' : state.critic,
+    });
 }
-
 /**
- * Create archive snapshots of meta.json.
- *
- * Copies current meta.json to archive/\{ISO-timestamp\}.json with
- * _archived: true and _archivedAt added.
- *
- * @module archive/snapshot
+ * Builder completes successfully.
+ * builder → fresh; critic → pending.
  */
+function builderSuccess(state) {
+    return enforceInvariant({
+        ...state,
+        builder: 'fresh',
+        critic: state.critic === 'failed' ? 'failed' : 'pending',
+    });
+}
 /**
- * Create an archive snapshot of the current meta.json.
- *
- * @param metaPath - Absolute path to the .meta directory.
- * @param meta - Current meta.json content.
- * @returns The archive file path.
+ * Critic completes successfully.
+ * critic → fresh. Meta becomes fully fresh.
  */
-async function createSnapshot(metaPath, meta) {
-    const archiveDir = join(metaPath, 'archive');
-    await mkdir(archiveDir, { recursive: true });
-    const now = new Date().toISOString().replace(/[:.]/g, '-');
-    const archiveFile = join(archiveDir, now + '.json');
-    const archived = {
-        ...meta,
-        _archived: true,
-        _archivedAt: new Date().toISOString(),
-    };
-    await writeFile(archiveFile, JSON.stringify(archived, null, 2) + '\n');
-    return archiveFile;
+function criticSuccess(state) {
+    return enforceInvariant({
+        ...state,
+        critic: 'fresh',
+    });
 }
-
+// ── Failure transition ─────────────────────────────────────────────────
 /**
- * Build the MetaContext for a synthesis cycle.
- *
- * Computes shared inputs once: scope files, delta files, child meta outputs,
- * previous content/feedback, steer, and archive paths.
- *
- * @module orchestrator/contextPackage
+ * A phase fails (error, timeout, or abort).
+ * Target phase → failed; upstream and downstream unchanged.
  */
+function phaseFailed(state, phase) {
+    return enforceInvariant({
+        ...state,
+        [phase]: 'failed',
+    });
+}
+// ── Surgical retry ─────────────────────────────────────────────────────
 /**
- * Condense a file list into glob-like summaries.
- * Groups by directory + extension pattern.
- *
- * @param files - Array of file paths.
- * @param maxIndividual - Show individual files up to this count.
- * @returns Condensed summary string.
+ * Retry a failed phase: failed → pending.
+ * Only valid when the phase is currently failed.
  */
-function condenseScopeFiles(files, maxIndividual = 30) {
-    if (files.length <= maxIndividual)
-        return files.join('\n');
-    // Group by dir + extension
-    const groups = new Map();
-    for (const f of files) {
-        const dir = f.substring(0, f.lastIndexOf('/') + 1) || './';
-        const ext = f.includes('.') ? f.substring(f.lastIndexOf('.')) : '(no ext)';
-        const key = dir + '*' + ext;
-        groups.set(key, (groups.get(key) ?? 0) + 1);
-    }
-    // Sort by count descending
-    const sorted = [...groups.entries()].sort((a, b) => b[1] - a[1]);
-    return sorted
-        .map(([pattern, count]) => pattern + ' (' + count.toString() + ' files)')
-        .join('\n');
+function retryPhase(state, phase) {
+    if (state[phase] !== 'failed')
+        return state;
+    return enforceInvariant({
+        ...state,
+        [phase]: 'pending',
+    });
 }
 /**
- * Read a meta.json file and extract `_content` and `_generatedAt`.
- *
- * @param metaJsonPath - Absolute path to a meta.json file.
- * @returns Parsed fields, or defaults if missing/unreadable.
+ * Retry all failed phases: each failed phase → pending.
+ * Used by scheduler ticks and queue reads to auto-promote failed phases.
  */
-async function readChildMeta(metaJsonPath) {
-    try {
-        const raw = await readFile(metaJsonPath, 'utf8');
-        const meta = JSON.parse(raw);
-        return {
-            content: meta._content ?? null,
-            generatedAt: meta._generatedAt,
-        };
+function retryAllFailed(state) {
+    let result = state;
+    for (const phase of ['architect', 'builder', 'critic']) {
+        if (result[phase] === 'failed') {
+            result = retryPhase(result, phase);
+        }
     }
-    catch {
-        return { content: null, generatedAt: undefined };
+    return result;
+}
+// ── Running transition ─────────────────────────────────────────────────
+/**
+ * Mark a phase as running (scheduler picks it).
+ */
+function phaseRunning(state, phase) {
+    return {
+        ...state,
+        [phase]: 'running',
+    };
+}
+// ── Query helpers ──────────────────────────────────────────────────────
+/**
+ * Get the owed phase: first non-fresh phase in pipeline order, or null.
+ */
+function getOwedPhase(state) {
+    for (const phase of ['architect', 'builder', 'critic']) {
+        if (state[phase] !== 'fresh')
+            return phase;
     }
+    return null;
 }
 /**
- * Read a meta.json file and extract its `_content` field.
- *
- * @param metaJsonPath - Absolute path to a meta.json file.
- * @returns The `_content` string, or null if missing/unreadable.
+ * Check if a meta is fully fresh (all phases fresh).
  */
-async function readMetaContent(metaJsonPath) {
-    const info = await readChildMeta(metaJsonPath);
-    return info.content;
+function isFullyFresh(state) {
+    return (state.architect === 'fresh' &&
+        state.builder === 'fresh' &&
+        state.critic === 'fresh');
 }
 /**
- * Build the context package for a synthesis cycle.
+ * Get the scheduler priority band for a meta's owed phase.
+ * 1 = critic (highest), 2 = builder, 3 = architect, null = fully fresh.
+ */
+function getPriorityBand(state) {
+    const owed = getOwedPhase(state);
+    if (!owed)
+        return null;
+    if (owed === 'critic')
+        return 1;
+    if (owed === 'builder')
+        return 2;
+    return 3;
+}
+
+/**
+ * Backward-compatible derivation of _phaseState from existing meta fields.
  *
- * @param node - The meta node being synthesized.
- * @param meta - Current meta.json content.
- * @param watcher - WatcherClient for scope enumeration.
- * @returns The computed context package.
+ * When a meta is loaded from disk without _phaseState, this reconstructs
+ * the phase state from _content, _builder, _state, _error.step, and
+ * the architect-invalidating inputs.
+ *
+ * @module phaseState/derivePhaseState
  */
-async function buildContextPackage(node, meta, watcher, logger) {
-    // Scope and delta files via watcher walk
-    const scopeStart = Date.now();
-    const { scopeFiles } = await getScopeFiles(node, watcher, logger);
-    const deltaFiles = getDeltaFiles(meta._generatedAt, scopeFiles);
-    logger?.debug({
-        scopeFiles: scopeFiles.length,
-        deltaFiles: deltaFiles.length,
-        durationMs: Date.now() - scopeStart,
-    }, 'scope and delta files computed');
-    // Child meta outputs (parallel reads, delta-aware).
-    // Only include full _content for children synthesized AFTER the parent's
-    // _generatedAt. Non-delta children are already folded into the parent's
-    // previous _content and are listed as path-only references (#169).
-    const parentGeneratedAt = meta._generatedAt;
-    const childMetas = {};
-    const childEntries = await Promise.all(node.children.map(async (child) => {
-        const info = await readChildMeta(join(child.metaPath, 'meta.json'));
-        return [child.ownerPath, info];
-    }));
-    let deltaChildCount = 0;
-    for (const [path, info] of childEntries) {
-        // Delta child: no parent timestamp (first run), or child synthesized
-        // after parent. Include full content.
-        if (!parentGeneratedAt ||
-            !info.generatedAt ||
-            info.generatedAt > parentGeneratedAt) {
-            childMetas[path] = info.content ?? undefined;
-            deltaChildCount++;
-        }
-        else {
-            // Non-delta: already incorporated in previous synthesis.
-            // Include path with null content so the builder knows it exists.
-            childMetas[path] = null;
-        }
-    }
-    logger?.debug({
-        totalChildren: childEntries.length,
-        deltaChildren: deltaChildCount,
-    }, 'child metas filtered by delta');
-    // Cross-referenced meta outputs (parallel reads)
-    const crossRefMetas = {};
-    const seen = new Set();
-    const crossRefPaths = [];
-    for (const refPath of meta._crossRefs ?? []) {
-        if (refPath === node.ownerPath || refPath === node.metaPath)
-            continue;
-        if (seen.has(refPath))
-            continue;
-        seen.add(refPath);
-        crossRefPaths.push(refPath);
-    }
-    const crossRefEntries = await Promise.all(crossRefPaths.map(async (refPath) => {
-        const content = await readMetaContent(join(refPath, '.meta', 'meta.json'));
-        return [refPath, content];
-    }));
-    for (const [path, content] of crossRefEntries) {
-        crossRefMetas[path] = content;
-    }
-    // Archive paths
-    const archives = listArchiveFiles(node.metaPath);
-    // Nearest ancestor _builder output
-    let ancestorBuilder;
-    const ancestor = getAncestorMeta(node);
-    if (ancestor) {
-        try {
-            const raw = await readFile(join(ancestor.metaPath, 'meta.json'), 'utf8');
-            const ancestorMeta = JSON.parse(raw);
-            if (ancestorMeta._builder) {
-                ancestorBuilder = ancestorMeta._builder;
+/**
+ * Derive _phaseState from existing meta fields.
+ *
+ * If the meta already has _phaseState, returns it as-is.
+ *
+ * Otherwise, reconstructs from available fields:
+ * - Never-synthesized meta (no _content, no _builder): all phases start pending/stale.
+ * - Errored meta: the failed phase is mapped from _error.step.
+ * - Mid-cycle meta with cached _builder but no _content: builder pending.
+ * - Fully-fresh meta: all phases fresh.
+ * - Meta with stale architect inputs: architect pending, downstream stale.
+ *
+ * @param meta - The meta.json content.
+ * @param inputs - Optional derivation inputs. If not provided, a simpler
+ *   heuristic is used (no architect invalidation check).
+ * @returns The derived PhaseState.
+ */
+function derivePhaseState(meta, inputs) {
+    // Already has _phaseState — use it
+    if (meta._phaseState)
+        return meta._phaseState;
+    // Check for errors first — _error.step maps directly to failed phase
+    if (meta._error) {
+        const failedPhase = meta._error.step;
+        const state = freshPhaseState();
+        state[failedPhase] = 'failed';
+        // If architect failed and no _builder, downstream is stale
+        if (failedPhase === 'architect') {
+            if (!meta._builder) {
+                state.builder = 'stale';
+                state.critic = 'stale';
             }
         }
-        catch {
-            // Ancestor meta.json unreadable — skip
+        // If builder failed, critic is stale
+        if (failedPhase === 'builder') {
+            state.critic = 'stale';
         }
+        return state;
     }
-    return {
-        path: node.metaPath,
-        scopeFiles,
-        deltaFiles,
-        childMetas,
-        crossRefMetas,
-        previousContent: meta._content ?? null,
-        previousFeedback: meta._feedback ?? null,
-        steer: meta._steer ?? null,
-        previousState: meta._state ?? null,
-        archives,
-        ancestorBuilder,
-    };
+    // Never synthesized: no _content AND no _builder (and no error)
+    if (!meta._content && !meta._builder) {
+        return initialPhaseState();
+    }
+    // Has _builder but no _content: builder is pending
+    if (meta._builder && !meta._content) {
+        return {
+            architect: 'fresh',
+            builder: 'pending',
+            critic: 'stale',
+        };
+    }
+    // Has _content but no _feedback: critic is pending
+    if (meta._content && !meta._feedback) {
+        return {
+            architect: 'fresh',
+            builder: 'fresh',
+            critic: 'pending',
+        };
+    }
+    // Default: fully fresh
+    return freshPhaseState();
 }
 
 /**
- * Build task prompts for each synthesis step.
- *
- * Prompts are compiled as Handlebars templates with access to config,
- * meta, and scope context. The architect can write template expressions
- * into its _builder output; these resolve when the builder task is compiled.
+ * List archive snapshot files in chronological order.
  *
- * @module orchestrator/buildTask
+ * @module archive/listArchive
  */
-Handlebars.registerHelper('gt', (a, b) => a > b);
-/** Build the template context from synthesis inputs. */
-function buildTemplateContext(ctx, meta, config) {
-    return {
-        config,
-        meta,
-        scope: {
-            fileCount: ctx.scopeFiles.length,
-            deltaCount: ctx.deltaFiles.length,
-            childCount: Object.keys(ctx.childMetas).length,
-            crossRefCount: Object.keys(ctx.crossRefMetas).length,
-        },
-    };
-}
 /**
- * Compile a string as a Handlebars template with the given context.
- * Returns the original string unchanged if compilation fails.
+ * List archive .json files sorted chronologically (oldest first).
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns Array of absolute paths to archive files, or empty if none.
  */
-function compileTemplate(text, context) {
+function listArchiveFiles(metaPath) {
+    const archiveDir = join(metaPath, 'archive');
     try {
-        return Handlebars.compile(text, { noEscape: true })(context);
+        return readdirSync(archiveDir)
+            .filter((f) => f.endsWith('.json'))
+            .sort()
+            .map((f) => join(archiveDir, f));
     }
     catch {
-        return text;
+        return [];
     }
 }
+
 /**
- * Append a keyed record of meta outputs as subsections, if non-empty.
+ * Prune old archive snapshots beyond maxArchive.
  *
- * @param condenseMissing - When true, null entries are condensed into a
- *   path listing (delta-aware child metas). When false, null entries get
- *   individual subsections with "(not yet synthesized)" (cross-refs).
+ * @module archive/prune
  */
-function appendMetaSections(sections, heading, metas, condenseMissing = false) {
-    if (Object.keys(metas).length === 0)
-        return;
-    if (!condenseMissing) {
-        // Original behavior: every entry gets a subsection.
-        sections.push('', heading);
-        for (const [path, content] of Object.entries(metas)) {
-            sections.push(`### ${path}`, typeof content === 'string' ? content : '(not yet synthesized)');
-        }
-        return;
-    }
-    // Delta-aware: separate entries into three categories (#169).
-    // - string content → full subsection (delta child with content)
-    // - null → non-delta, already folded into previous synthesis
-    // - undefined → delta child not yet synthesized
-    const withContent = [];
-    const unchanged = [];
-    const notYetSynthesized = [];
-    for (const [path, content] of Object.entries(metas)) {
-        if (typeof content === 'string') {
-            withContent.push([path, content]);
-        }
-        else if (content === null) {
-            unchanged.push(path);
-        }
-        else {
-            notYetSynthesized.push(path);
-        }
-    }
-    sections.push('', heading);
-    for (const [path, content] of withContent) {
-        sections.push(`### ${path}`, content);
-    }
-    if (notYetSynthesized.length > 0) {
-        sections.push('', `### Not yet synthesized (${notYetSynthesized.length.toString()})`, ...notYetSynthesized.map((p) => `- ${p}`));
-    }
-    if (unchanged.length > 0) {
-        sections.push('', `### Other children (${unchanged.length.toString()} \u2014 unchanged since last synthesis)`, ...unchanged.map((p) => `- ${p}`));
-    }
-}
-/** Inject nearest ancestor's organizational context, if available. */
-function appendAncestorContext(sections, ctx) {
-    if (ctx.ancestorBuilder) {
-        sections.push('', '## PARENT ORGANIZATIONAL CONTEXT', ctx.ancestorBuilder);
-    }
-}
-/** Append optional context sections shared across all step prompts. */
-function appendSharedSections(sections, ctx, options) {
-    const opts = {
-        includeSteer: true,
-        includePreviousContent: true,
-        includePreviousFeedback: true,
-        feedbackHeading: '## PREVIOUS FEEDBACK',
-        includeChildMetas: true,
-        includeCrossRefs: true,
-        ...options,
-    };
-    if (opts.includeSteer && ctx.steer) {
-        sections.push('', '## STEERING PROMPT', ctx.steer);
-    }
-    if (opts.includePreviousContent && ctx.previousContent) {
-        sections.push('', '## PREVIOUS SYNTHESIS', ctx.previousContent);
-    }
-    if (opts.includePreviousFeedback && ctx.previousFeedback) {
-        sections.push('', opts.feedbackHeading, ctx.previousFeedback);
-    }
-    if (opts.includeChildMetas) {
-        appendMetaSections(sections, '## CHILD META OUTPUTS', ctx.childMetas, true);
-    }
-    if (opts.includeCrossRefs) {
-        appendMetaSections(sections, '## CROSS-REFERENCED METAS', ctx.crossRefMetas);
-    }
+/**
+ * Prune archive directory to keep at most maxArchive snapshots.
+ * Removes the oldest files.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @param maxArchive - Maximum snapshots to retain.
+ * @returns Number of files pruned.
+ */
+async function pruneArchive(metaPath, maxArchive) {
+    const files = listArchiveFiles(metaPath);
+    const toRemove = files.length - maxArchive;
+    if (toRemove <= 0)
+        return 0;
+    await Promise.all(files.slice(0, toRemove).map(unlink));
+    return toRemove;
 }
+
 /**
- * Build the architect task prompt.
+ * Read the latest archive snapshot for steer change detection.
  *
- * @param ctx - Synthesis context.
- * @param meta - Current meta.json.
- * @param config - Synthesis config.
- * @returns The architect task prompt string.
+ * @module archive/readLatest
  */
-function buildArchitectTask(ctx, meta, config) {
-    const sections = [
-        `# jeeves-meta · ARCHITECT · ${ctx.path}`,
-        '',
-        DEFAULT_ARCHITECT_PROMPT,
-        '',
-        '## SCOPE',
-        `Path: ${ctx.path}`,
-        `Total files in scope: ${ctx.scopeFiles.length.toString()}`,
-        `Files changed since last synthesis: ${ctx.deltaFiles.length.toString()}`,
-        '',
-        '### File listing (scope)',
-        condenseScopeFiles(ctx.scopeFiles),
-    ];
-    appendAncestorContext(sections, ctx);
-    // Inject previous _builder so architect can see its own prior output
-    if (meta._builder) {
-        sections.push('', '## PREVIOUS TASK BRIEF', meta._builder);
-    }
-    appendSharedSections(sections, ctx);
-    if (ctx.archives.length > 0) {
-        sections.push('', '## ARCHIVE HISTORY', `${ctx.archives.length.toString()} previous synthesis snapshots available in .meta/archive/.`, 'Review these to understand how the synthesis has evolved over time.');
-    }
-    return compileTemplate(sections.join('\n'), buildTemplateContext(ctx, meta, config));
-}
 /**
- * Build the builder task prompt.
+ * Read the most recent archive snapshot.
  *
- * @param ctx - Synthesis context.
- * @param meta - Current meta.json.
- * @param config - Synthesis config.
- * @returns The builder task prompt string.
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns The latest archived meta, or null if no archives exist.
  */
-function buildBuilderTask(ctx, meta, config) {
-    const sections = [
-        `# jeeves-meta · BUILDER · ${ctx.path}`,
-        '',
-        '## TASK BRIEF (from Architect)',
-        meta._builder ?? '(No architect brief available)',
-        '',
-        '## SCOPE',
-        `Path: ${ctx.path}`,
-        `Delta files (${ctx.deltaFiles.length.toString()} changed):`,
-        ...ctx.deltaFiles.slice(0, config.maxLines).map((f) => `- ${f}`),
-    ];
-    appendAncestorContext(sections, ctx);
-    if (ctx.previousState != null) {
-        sections.push('', '## PREVIOUS STATE', 'The following opaque state was returned by the previous synthesis cycle.', 'Use it to continue progressive work. Update `_state` in your output to', 'reflect your progress.', '', '```json', JSON.stringify(ctx.previousState, null, 2), '```');
-    }
-    appendSharedSections(sections, ctx, {
-        includeSteer: false,
-        feedbackHeading: '## FEEDBACK FROM CRITIC',
-    });
-    sections.push('', '## OUTPUT FORMAT', '', 'Respond with ONLY a JSON object. No explanation, no markdown fences, no text before or after.', '', 'Required schema:', '{', '  "type": "object",', '  "required": ["_content"],', '  "properties": {', '    "_content": { "type": "string", "description": "Markdown narrative synthesis" },', '    "_state": { "description": "Opaque state object for progressive work across cycles" }', '  },', '  "additionalProperties": true', '}', '', 'Add any structured fields that capture important facts about this entity', '(e.g. status, risks, dependencies, metrics). Use descriptive key names without underscore prefix.', 'The _content field is the only required key — everything else is domain-driven.', '_state is optional: set it to carry state across synthesis cycles for progressive work.', '', 'DIAGRAMS: When diagrams would aid understanding, use PlantUML in fenced code blocks (```plantuml).', 'PlantUML is rendered natively by the serving infrastructure. NEVER use ASCII art diagrams.', '', 'IMPORTANT: Do not call sessions_spawn or sessions_yield. Read all files directly using the tools', 'available in your session. Do not attempt to parallelize work by spawning sub-agents.');
-    return compileTemplate(sections.join('\n'), buildTemplateContext(ctx, meta, config));
+async function readLatestArchive(metaPath) {
+    const files = listArchiveFiles(metaPath);
+    if (files.length === 0)
+        return null;
+    const raw = await readFile(files[files.length - 1], 'utf8');
+    return JSON.parse(raw);
 }
+
 /**
- * Build the critic task prompt.
+ * Create archive snapshots of meta.json.
  *
- * @param ctx - Synthesis context.
- * @param meta - Current meta.json (with _content already set by builder).
- * @param config - Synthesis config.
- * @returns The critic task prompt string.
+ * Copies current meta.json to archive/\{ISO-timestamp\}.json with
+ * _archived: true and _archivedAt added.
+ *
+ * @module archive/snapshot
  */
-function buildCriticTask(ctx, meta, config) {
-    const sections = [
-        `# jeeves-meta · CRITIC · ${ctx.path}`,
-        '',
-        DEFAULT_CRITIC_PROMPT,
-        '',
-        '## SYNTHESIS TO EVALUATE',
-        meta._content ?? '(No content produced)',
-        '',
-        '## SCOPE',
-        `Path: ${ctx.path}`,
-        `Files in scope: ${ctx.scopeFiles.length.toString()}`,
-    ];
-    appendSharedSections(sections, ctx, {
-        includePreviousContent: false,
-        feedbackHeading: '## YOUR PREVIOUS FEEDBACK',
-        includeChildMetas: false,
-        includeCrossRefs: false,
-    });
-    sections.push('', '## OUTPUT FORMAT', 'Return your evaluation as Markdown text. Be specific and actionable.');
-    return compileTemplate(sections.join('\n'), buildTemplateContext(ctx, meta, config));
+/**
+ * Create an archive snapshot of the current meta.json.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @param meta - Current meta.json content.
+ * @returns The archive file path.
+ */
+async function createSnapshot(metaPath, meta) {
+    const archiveDir = join(metaPath, 'archive');
+    await mkdir(archiveDir, { recursive: true });
+    const now = new Date().toISOString().replace(/[:.]/g, '-');
+    const archiveFile = join(archiveDir, now + '.json');
+    const archived = {
+        ...meta,
+        _archived: true,
+        _archivedAt: new Date().toISOString(),
+    };
+    await writeFile(archiveFile, JSON.stringify(archived, null, 2) + '\n');
+    return archiveFile;
+}
+
+const toPath = urlOrPath => urlOrPath instanceof URL ? fileURLToPath(urlOrPath) : urlOrPath;
+
+function findUpSync(name, {
+	cwd = process$1.cwd(),
+	type = 'file',
+	stopAt,
+} = {}) {
+	let directory = path.resolve(toPath(cwd) ?? '');
+	const {root} = path.parse(directory);
+	stopAt = path.resolve(directory, toPath(stopAt) ?? root);
+	const isAbsoluteName = path.isAbsolute(name);
+
+	while (directory) {
+		const filePath = isAbsoluteName ? name : path.join(directory, name);
+
+		try {
+			const stats = fs.statSync(filePath, {throwIfNoEntry: false});
+			if ((type === 'file' && stats?.isFile()) || (type === 'directory' && stats?.isDirectory())) {
+				return filePath;
+			}
+		} catch {}
+
+		if (directory === stopAt || directory === root) {
+			break;
+		}
+
+		directory = path.dirname(directory);
+	}
+}
+
+const isTypeOnlyPackageJsonData = packageData => {
+	if (!packageData || typeof packageData !== 'object' || Array.isArray(packageData)) {
+		return false;
+	}
+
+	const keys = Object.keys(packageData);
+	return keys.length === 1 && keys[0] === 'type' && typeof packageData.type === 'string';
+};
+
+const isTypeOnlyPackageJsonSync = filePath => {
+	let fileContents;
+
+	try {
+		fileContents = fs.readFileSync(filePath, 'utf8');
+	} catch {
+		return false;
+	}
+
+	try {
+		return isTypeOnlyPackageJsonData(JSON.parse(fileContents));
+	} catch {
+		return false;
+	}
+};
+
+const getNextSearchDirectory = filePath => {
+	const packageDirectoryPath = path.dirname(filePath);
+	const parentDirectoryPath = path.dirname(packageDirectoryPath);
+	return parentDirectoryPath === packageDirectoryPath ? undefined : parentDirectoryPath;
+};
+
+const findPackageDirectorySync = (directory, ignoreTypeOnlyPackageJson) => {
+	const filePath = findUpSync('package.json', {cwd: directory});
+	if (!filePath) {
+		return undefined;
+	}
+
+	const packageDirectoryPath = path.dirname(filePath);
+	if (!ignoreTypeOnlyPackageJson) {
+		return packageDirectoryPath;
+	}
+
+	if (!isTypeOnlyPackageJsonSync(filePath)) {
+		return packageDirectoryPath;
+	}
+
+	const nextDirectory = getNextSearchDirectory(filePath);
+	if (!nextDirectory) {
+		return undefined;
+	}
+
+	return findPackageDirectorySync(nextDirectory, ignoreTypeOnlyPackageJson);
+};
+
+function packageDirectorySync({cwd, ignoreTypeOnlyPackageJson} = {}) {
+	return findPackageDirectorySync(cwd ?? process$1.cwd(), ignoreTypeOnlyPackageJson);
 }
 
 /**
- * Build a minimal MetaNode from a known meta path using watcher walk.
+ * Built-in default prompts for the synthesis pipeline.
  *
- * Used for targeted synthesis (when a specific path is requested) to avoid
- * the full discovery + ownership tree build. Discovers only immediate child
- * `.meta/` directories.
+ * Prompts live as `.md` files next to this module in `src/prompts/`. The
+ * CLI build copies them into `dist/prompts/` (rollup-plugin-copy), and a
+ * build-time assertion verifies the copy.
  *
- * @module discovery/buildMinimalNode
+ * The prompt directory is resolved relative to the executing module, so
+ * running from source (e.g. vitest) reads `src/prompts/` and the published
+ * bundle reads `dist/prompts/`. Prompts are read lazily on first use, so a
+ * missing file surfaces as one clear error instead of an import-time crash.
+ *
+ * @module prompts
  */
 /**
- * Build a minimal MetaNode for a known meta path.
- *
- * Walks the owner directory for child `.meta/meta.json` files and constructs
- * a shallow ownership tree (self + direct children only).
+ * Resolve the directory holding the built-in prompt files for a module.
  *
- * @param metaPath - Absolute path to the `.meta/` directory.
- * @param watcher - WatcherClient for filesystem enumeration.
- * @returns MetaNode with direct children wired.
+ * @param moduleFile - Absolute path of the executing module.
+ * @returns `<package root>/src/prompts` when the module lives under
+ *   `src/`, otherwise `<package root>/dist/prompts` (published bundle).
  */
-async function buildMinimalNode(metaPath, watcher) {
-    const normalized = normalizePath(metaPath);
-    const ownerPath = posix.dirname(normalized);
-    // Find child metas using watcher walk.
-    // We include only *direct* children (nearest descendants in the ownership tree)
-    // to match the ownership semantics used elsewhere.
-    const rawMetaJsonPaths = await watcher.walk([
-        `${escapeGlob(ownerPath)}/**/.meta/meta.json`,
-    ]);
-    const candidateMetaPaths = [
-        ...new Set(rawMetaJsonPaths.map((p) => posix.dirname(normalizePath(p)))),
-    ].filter((p) => p !== normalized);
-    const candidates = candidateMetaPaths
-        .map((mp) => ({ metaPath: mp, ownerPath: posix.dirname(mp) }))
-        .sort((a, b) => a.ownerPath.length - b.ownerPath.length);
-    const directChildren = [];
-    for (const c of candidates) {
-        const nestedUnderExisting = directChildren.some((d) => c.ownerPath === d.ownerPath ||
-            c.ownerPath.startsWith(d.ownerPath + '/'));
-        if (!nestedUnderExisting)
-            directChildren.push(c);
+function resolvePromptDir(moduleFile) {
+    const packageRoot = packageDirectorySync({ cwd: dirname(moduleFile) });
+    if (!packageRoot) {
+        throw new Error(`jeeves-meta: cannot locate package root for prompt module ${moduleFile}`);
     }
-    const children = directChildren.map((c) => ({
-        metaPath: c.metaPath,
-        ownerPath: c.ownerPath,
-        treeDepth: 1,
-        children: [],
-        parent: null,
-    }));
-    const node = {
-        metaPath: normalized,
-        ownerPath,
-        treeDepth: 0,
-        children,
-        parent: null,
-    };
-    for (const child of children) {
-        child.parent = node;
+    const [topLevel] = relative(packageRoot, moduleFile).split(sep);
+    return join(packageRoot, topLevel === 'src' ? 'src' : 'dist', 'prompts');
+}
+const cache = new Map();
+function loadPrompt(file) {
+    const cached = cache.get(file);
+    if (cached !== undefined)
+        return cached;
+    const path = join(getPromptDir(), file);
+    let content;
+    try {
+        content = readFileSync(path, 'utf8');
     }
-    return node;
+    catch (err) {
+        throw new Error(`jeeves-meta: built-in prompt not found at ${path}`, {
+            cause: err,
+        });
+    }
+    cache.set(file, content);
+    return content;
+}
+/** Directory the built-in prompts are read from for this module. */
+function getPromptDir() {
+    return resolvePromptDir(fileURLToPath(import.meta.url));
+}
+/** Built-in default architect prompt (read on first use, then cached). */
+function getDefaultArchitectPrompt() {
+    return loadPrompt('architect.md');
+}
+/** Built-in default critic prompt (read on first use, then cached). */
+function getDefaultCriticPrompt() {
+    return loadPrompt('critic.md');
 }
 
 /**
- * Pure phase-state transition functions.
+ * Compute a structure hash from a sorted file listing.
  *
- * Implements every row of the §8 "Transitions and invalidation cascade" table.
- * No I/O — pure functions over PhaseState and documented inputs.
+ * Used to detect when directory structure changes, triggering
+ * an architect re-run.
  *
- * @module phaseState/phaseTransitions
+ * @module structureHash
  */
 /**
- * Create a fresh (fully-complete) phase state.
+ * Compute a SHA-256 hash of a sorted file listing.
+ *
+ * @param filePaths - Array of file paths in scope.
+ * @returns Hex-encoded SHA-256 hash of the sorted, newline-joined paths.
  */
-function freshPhaseState() {
-    return { architect: 'fresh', builder: 'fresh', critic: 'fresh' };
+function computeStructureHash(filePaths) {
+    const sorted = [...filePaths].sort();
+    const content = sorted.join('\n');
+    return createHash('sha256').update(content).digest('hex');
 }
+
 /**
- * Create a phase state for a never-synthesized meta (all pending from architect).
+ * Per-tick invalidation pass.
+ *
+ * Computes architect-invalidating and builder-invalidating inputs for a meta,
+ * then applies the cascade to update _phaseState.
+ *
+ * @module phaseState/invalidate
  */
-function initialPhaseState() {
-    return { architect: 'pending', builder: 'stale', critic: 'stale' };
+/**
+ * Check whether a persisted prompt snapshot mismatches the currently-resolved prompt.
+ * Returns true when the snapshot exists and differs from the resolved prompt.
+ * This is informational only — it does NOT trigger invalidation.
+ */
+function isPromptStale(snapshot, resolved) {
+    return snapshot !== undefined && snapshot !== resolved;
 }
 /**
- * Enforce the per-meta invariant: at most one phase is pending or running,
- * and it is the first non-fresh phase in pipeline order.
+ * Compute invalidation inputs and apply cascade for a single meta.
  *
- * Stale phases that become the first non-fresh phase are promoted to pending.
+ * @param meta - Current meta.json content with existing _phaseState.
+ * @param scopeFiles - Sorted file list from scope.
+ * @param config - MetaConfig for architectEvery.
+ * @param node - MetaNode for archive access.
+ * @param crossRefMetas - Map of cross-ref owner paths to their current _content.
+ * @param archiveCrossRefContent - Map of cross-ref owner paths to their archived _content.
+ * @returns Updated phase state and invalidation details.
  */
-function enforceInvariant(state) {
-    const result = { ...state };
-    let foundNonFresh = false;
-    for (const phase of ['architect', 'builder', 'critic']) {
-        const s = result[phase];
-        if (s === 'fresh')
-            continue;
-        if (!foundNonFresh) {
-            foundNonFresh = true;
-            // First non-fresh: if stale, promote to pending
-            if (s === 'stale') {
-                result[phase] = 'pending';
-            }
-            // pending, running, failed stay as-is
+async function computeInvalidation(meta, scopeFiles, config, node, crossRefMetas, archiveCrossRefContent) {
+    let phaseState = meta._phaseState ?? {
+        architect: 'fresh',
+        builder: 'fresh',
+        critic: 'fresh',
+    };
+    // ── Architect-level inputs ──
+    const structureHash = computeStructureHash(scopeFiles);
+    const structureChanged = structureHash !== meta._structureHash;
+    const latestArchive = await readLatestArchive(node.metaPath);
+    const steerChanged = hasSteerChanged(meta._steer, latestArchive?._steer, Boolean(latestArchive));
+    // Prompt staleness detection: compare persisted prompt snapshots against
+    // currently-resolved prompts.  This is INFORMATIONAL ONLY — reported via
+    // inputStatus so /preview can surface it, but it must NEVER feed into
+    // the invalidation cascade.  When a meta naturally reaches architectEvery
+    // through real builder cycles, architect runs with the current prompt and
+    // the snapshot updates.  Coupling prompt changes to invalidation causes a
+    // corpus-wide synthesis storm (see #163).
+    const architectChanged = isPromptStale(meta._architect, getDefaultArchitectPrompt());
+    const criticChanged = isPromptStale(meta._critic, getDefaultCriticPrompt());
+    const effectiveSynthesisCount = meta._synthesisCount ?? 0;
+    // _crossRefs declaration change
+    const currentRefs = (meta._crossRefs ?? []).slice().sort().join(',');
+    const archiveRefs = (latestArchive?._crossRefs ?? [])
+        .slice()
+        .sort()
+        .join(',');
+    const crossRefsDeclChanged = latestArchive
+        ? currentRefs !== archiveRefs
+        : currentRefs.length > 0;
+    const architectInvalidators = [];
+    if (structureChanged) {
+        if (meta._state !== undefined) {
+            // Progressive entity: new files → builder only (cursor handles incremental)
+            phaseState = invalidateBuilder(phaseState);
         }
         else {
-            // Subsequent non-fresh: must not be pending or running
-            if (s === 'pending') {
-                result[phase] = 'stale';
-            }
-            // running in non-first position would be a bug, but don't mask it
+            architectInvalidators.push('structureHash');
         }
     }
-    return result;
+    if (steerChanged)
+        architectInvalidators.push('steer');
+    if (crossRefsDeclChanged)
+        architectInvalidators.push('_crossRefs');
+    if (effectiveSynthesisCount >= config.architectEvery) {
+        architectInvalidators.push('architectEvery');
+    }
+    if (!meta._builder)
+        architectInvalidators.push('firstRun');
+    if (architectInvalidators.length > 0) {
+        phaseState = invalidateArchitect(phaseState);
+    }
+    // ── Builder-level inputs ──
+    // Cross-ref _content change (builder-invalidating)
+    let crossRefContentChanged = false;
+    return {
+        phaseState,
+        architectInvalidators,
+        inputStatus: {
+            structureHash,
+            steerChanged,
+            architectChanged,
+            criticChanged,
+            crossRefsDeclChanged,
+            crossRefContentChanged,
+        },
+    };
 }
-// ── Invalidation cascades ──────────────────────────────────────────────
+
 /**
- * Architect invalidated: architect → pending; builder, critic → stale.
- * Triggers: first run, _structureHash change, _steer change,
- * _crossRefs declaration change, _synthesisCount \>= architectEvery.
+ * Weighted staleness formula for candidate selection.
+ *
+ * effectiveStaleness = actualStaleness * (normalizedDepth + 1) ^ (depthWeight * emphasis)
+ *
+ * @module scheduling/weightedFormula
  */
-function invalidateArchitect(state) {
-    return enforceInvariant({
-        architect: state.architect === 'failed' ? 'failed' : 'pending',
-        builder: state.builder === 'fresh' ? 'stale' : state.builder,
-        critic: state.critic === 'fresh' ? 'stale' : state.critic,
-    });
-}
 /**
- * Builder invalidated (scope mtime or cross-ref _content change):
- * builder → pending; critic → stale.
- * Only applies when architect is fresh; otherwise, builder stays stale.
+ * Compute effective staleness for a set of candidates.
+ *
+ * Normalizes depths so the minimum becomes 0, then applies the formula:
+ * effectiveStaleness = actualStaleness * (normalizedDepth + 1) ^ (depthWeight * emphasis)
+ *
+ * Per-meta _emphasis (default 1) multiplies depthWeight, allowing individual
+ * metas to tune how much their tree position affects scheduling.
+ *
+ * @param candidates - Array of \{ node, meta, actualStaleness \}.
+ * @param depthWeight - Exponent for depth weighting (0 = pure staleness).
+ * @returns Same array with effectiveStaleness computed.
  */
-function invalidateBuilder(state) {
-    if (state.architect !== 'fresh') {
-        // Architect is not fresh — builder stays stale (or whatever it is)
-        return enforceInvariant({
-            ...state,
-            builder: state.builder === 'fresh' || state.builder === 'stale'
-                ? 'stale'
-                : state.builder,
-            critic: state.critic === 'fresh' ? 'stale' : state.critic,
-        });
-    }
-    return enforceInvariant({
-        ...state,
-        builder: state.builder === 'failed' ? 'failed' : 'pending',
-        critic: state.critic === 'fresh' ? 'stale' : state.critic,
+function computeEffectiveStaleness(candidates, depthWeight) {
+    if (candidates.length === 0)
+        return [];
+    // Get depth for each candidate: use _depth override or tree depth
+    const depths = candidates.map((c) => c.meta._depth ?? c.node.treeDepth);
+    // Normalize: shift so minimum becomes 0
+    const minDepth = Math.min(...depths);
+    const normalizedDepths = depths.map((d) => Math.max(0, d - minDepth));
+    return candidates.map((c, i) => {
+        const emphasis = c.meta._emphasis ?? 1;
+        return {
+            ...c,
+            effectiveStaleness: c.actualStaleness *
+                Math.pow(normalizedDepths[i] + 1, depthWeight * emphasis),
+        };
     });
 }
-// ── Phase success transitions ──────────────────────────────────────────
+
 /**
- * Architect completes successfully.
- * architect → fresh; builder → pending; critic → stale.
+ * Corpus-wide phase scheduler.
+ *
+ * Selects the highest-priority ready phase across all metas.
+ * Priority: critic (band 1) \> builder (band 2) \> architect (band 3).
+ * Tiebreak within band: weighted staleness (§3.9).
+ *
+ * @module phaseState/phaseScheduler
  */
-function architectSuccess(state) {
-    return enforceInvariant({
-        architect: 'fresh',
-        builder: state.builder === 'failed' ? 'failed' : 'pending',
-        critic: state.critic === 'fresh' ? 'stale' : state.critic,
-    });
-}
 /**
- * Builder completes successfully.
- * builder → fresh; critic → pending.
+ * Build phase candidates from listMetas entries.
+ *
+ * Derives phase state, auto-retries failed phases, and applies Tier 1
+ * cheap-invalidation (no I/O) for metas with persisted _phaseState.
+ * Used by orchestratePhase, queue route, and status route.
  */
-function builderSuccess(state) {
-    return enforceInvariant({
-        ...state,
-        builder: 'fresh',
-        critic: state.critic === 'failed' ? 'failed' : 'pending',
+function buildPhaseCandidates(entries, architectEvery) {
+    return entries.map((entry) => {
+        let ps = retryAllFailed(derivePhaseState(entry.meta));
+        // Tier 1 cheap invalidation for metas with persisted _phaseState
+        if (entry.meta._phaseState) {
+            const needsArchitect = !entry.meta._builder ||
+                (entry.meta._synthesisCount ?? 0) >= architectEvery;
+            if (needsArchitect && isFullyFresh(ps)) {
+                ps = { architect: 'pending', builder: 'stale', critic: 'stale' };
+            }
+        }
+        return {
+            node: entry.node,
+            meta: entry.meta,
+            phaseState: ps,
+            actualStaleness: entry.stalenessSeconds,
+            locked: entry.locked,
+            disabled: entry.disabled,
+        };
     });
 }
 /**
- * Critic completes successfully.
- * critic → fresh. Meta becomes fully fresh.
+ * Rank all eligible phase candidates by priority.
+ *
+ * Filters to pending phases, computes effective staleness, and sorts by
+ * band (ascending: critic first) then effective staleness (descending).
+ *
+ * Used by selectPhaseCandidate (returns first) and the queue route (returns all).
  */
-function criticSuccess(state) {
-    return enforceInvariant({
-        ...state,
-        critic: 'fresh',
+function rankPhaseCandidates(metas, depthWeight) {
+    // Filter to metas with a pending (scheduler-eligible) phase
+    const eligible = metas.filter((m) => {
+        if (m.locked)
+            return false;
+        if (m.disabled && !m.isOverride)
+            return false;
+        const owed = getOwedPhase(m.phaseState);
+        if (!owed)
+            return false;
+        return m.phaseState[owed] === 'pending';
     });
-}
-// ── Failure transition ─────────────────────────────────────────────────
-/**
- * A phase fails (error, timeout, or abort).
- * Target phase → failed; upstream and downstream unchanged.
- */
-function phaseFailed(state, phase) {
-    return enforceInvariant({
-        ...state,
-        [phase]: 'failed',
+    if (eligible.length === 0)
+        return [];
+    // Compute effective staleness for tiebreaking
+    const withStaleness = computeEffectiveStaleness(eligible.map((m) => ({
+        node: m.node,
+        meta: m.meta,
+        actualStaleness: m.actualStaleness,
+    })), depthWeight);
+    // Build candidates with band info
+    const candidates = withStaleness.map((ws, i) => {
+        const m = eligible[i];
+        const owedPhase = getOwedPhase(m.phaseState);
+        return {
+            node: ws.node,
+            meta: ws.meta,
+            phaseState: m.phaseState,
+            owedPhase,
+            band: getPriorityBand(m.phaseState),
+            actualStaleness: ws.actualStaleness,
+            effectiveStaleness: ws.effectiveStaleness,
+        };
     });
-}
-// ── Surgical retry ─────────────────────────────────────────────────────
-/**
- * Retry a failed phase: failed → pending.
- * Only valid when the phase is currently failed.
- */
-function retryPhase(state, phase) {
-    if (state[phase] !== 'failed')
-        return state;
-    return enforceInvariant({
-        ...state,
-        [phase]: 'pending',
+    // Sort by band (ascending = critic first) then effective staleness (descending)
+    candidates.sort((a, b) => {
+        if (a.band !== b.band)
+            return a.band - b.band;
+        return b.effectiveStaleness - a.effectiveStaleness;
     });
+    return candidates;
 }
 /**
- * Retry all failed phases: each failed phase → pending.
- * Used by scheduler ticks and queue reads to auto-promote failed phases.
- */
-function retryAllFailed(state) {
-    let result = state;
-    for (const phase of ['architect', 'builder', 'critic']) {
-        if (result[phase] === 'failed') {
-            result = retryPhase(result, phase);
-        }
-    }
-    return result;
-}
-// ── Running transition ─────────────────────────────────────────────────
-/**
- * Mark a phase as running (scheduler picks it).
+ * Select the best phase candidate across the corpus.
+ *
+ * @param metas - Array of (node, meta, phaseState, stalenessSeconds) tuples.
+ * @param depthWeight - Config depthWeight for staleness tiebreak.
+ * @returns The winning candidate, or null if no phase is ready.
  */
-function phaseRunning(state, phase) {
-    return {
-        ...state,
-        [phase]: 'running',
-    };
+function selectPhaseCandidate(metas, depthWeight) {
+    return rankPhaseCandidates(metas, depthWeight)[0] ?? null;
 }
-// ── Query helpers ──────────────────────────────────────────────────────
 /**
- * Get the owed phase: first non-fresh phase in pipeline order, or null.
+ * Select all fully-fresh, non-disabled, non-locked metas sorted by staleness
+ * (descending — stalest first) for Tier 2 invalidation scanning.
  */
-function getOwedPhase(state) {
-    for (const phase of ['architect', 'builder', 'critic']) {
-        if (state[phase] !== 'fresh')
-            return phase;
-    }
-    return null;
+function selectAllTier2Candidates(metas) {
+    return metas
+        .filter((m) => !m.locked && !m.disabled && isFullyFresh(m.phaseState))
+        .sort((a, b) => b.actualStaleness - a.actualStaleness)
+        .map((m) => ({ node: m.node, meta: m.meta }));
 }
+
 /**
- * Check if a meta is fully fresh (all phases fresh).
+ * Shared error utilities.
+ *
+ * @module errors
  */
-function isFullyFresh(state) {
-    return (state.architect === 'fresh' &&
-        state.builder === 'fresh' &&
-        state.critic === 'fresh');
-}
 /**
- * Get the scheduler priority band for a meta's owed phase.
- * 1 = critic (highest), 2 = builder, 3 = architect, null = fully fresh.
+ * Wrap an unknown caught value into a MetaError.
+ *
+ * @param step - Which synthesis step failed.
+ * @param err - The caught error value.
+ * @param code - Error classification code.
+ * @returns A structured MetaError.
  */
-function getPriorityBand(state) {
-    const owed = getOwedPhase(state);
-    if (!owed)
-        return null;
-    if (owed === 'critic')
-        return 1;
-    if (owed === 'builder')
-        return 2;
-    return 3;
+function toMetaError(step, err, code = 'FAILED') {
+    return {
+        step,
+        code,
+        message: err instanceof Error ? err.message : String(err),
+    };
 }
 
 /**
- * Backward-compatible derivation of _phaseState from existing meta fields.
+ * Build the MetaContext for a synthesis cycle.
  *
- * When a meta is loaded from disk without _phaseState, this reconstructs
- * the phase state from _content, _builder, _state, _error.step, and
- * the architect-invalidating inputs.
+ * Computes shared inputs once: scope files, delta files, child meta outputs,
+ * previous content/feedback, steer, and archive paths.
  *
- * @module phaseState/derivePhaseState
+ * @module orchestrator/contextPackage
  */
 /**
- * Derive _phaseState from existing meta fields.
- *
- * If the meta already has _phaseState, returns it as-is.
- *
- * Otherwise, reconstructs from available fields:
- * - Never-synthesized meta (no _content, no _builder): all phases start pending/stale.
- * - Errored meta: the failed phase is mapped from _error.step.
- * - Mid-cycle meta with cached _builder but no _content: builder pending.
- * - Fully-fresh meta: all phases fresh.
- * - Meta with stale architect inputs: architect pending, downstream stale.
+ * Condense a file list into glob-like summaries.
+ * Groups by directory + extension pattern.
  *
- * @param meta - The meta.json content.
- * @param inputs - Optional derivation inputs. If not provided, a simpler
- *   heuristic is used (no architect invalidation check).
- * @returns The derived PhaseState.
+ * @param files - Array of file paths.
+ * @param maxIndividual - Show individual files up to this count.
+ * @returns Condensed summary string.
  */
-function derivePhaseState(meta, inputs) {
-    // Already has _phaseState — use it
-    if (meta._phaseState)
-        return meta._phaseState;
-    // Check for errors first — _error.step maps directly to failed phase
-    if (meta._error) {
-        const failedPhase = meta._error.step;
-        const state = freshPhaseState();
-        state[failedPhase] = 'failed';
-        // If architect failed and no _builder, downstream is stale
-        if (failedPhase === 'architect') {
-            if (!meta._builder) {
-                state.builder = 'stale';
-                state.critic = 'stale';
-            }
-        }
-        // If builder failed, critic is stale
-        if (failedPhase === 'builder') {
-            state.critic = 'stale';
-        }
-        return state;
-    }
-    // Never synthesized: no _content AND no _builder (and no error)
-    if (!meta._content && !meta._builder) {
-        return initialPhaseState();
+function condenseScopeFiles(files, maxIndividual = 30) {
+    if (files.length <= maxIndividual)
+        return files.join('\n');
+    // Group by dir + extension
+    const groups = new Map();
+    for (const f of files) {
+        const dir = f.substring(0, f.lastIndexOf('/') + 1) || './';
+        const ext = f.includes('.') ? f.substring(f.lastIndexOf('.')) : '(no ext)';
+        const key = dir + '*' + ext;
+        groups.set(key, (groups.get(key) ?? 0) + 1);
     }
-    // Has _builder but no _content: builder is pending
-    if (meta._builder && !meta._content) {
+    // Sort by count descending
+    const sorted = [...groups.entries()].sort((a, b) => b[1] - a[1]);
+    return sorted
+        .map(([pattern, count]) => pattern + ' (' + count.toString() + ' files)')
+        .join('\n');
+}
+/**
+ * Read a meta.json file and extract `_content` and `_generatedAt`.
+ *
+ * @param metaJsonPath - Absolute path to a meta.json file.
+ * @returns Parsed fields, or defaults if missing/unreadable.
+ */
+async function readChildMeta(metaJsonPath) {
+    try {
+        const raw = await readFile(metaJsonPath, 'utf8');
+        const meta = JSON.parse(raw);
         return {
-            architect: 'fresh',
-            builder: 'pending',
-            critic: 'stale',
+            content: meta._content ?? null,
+            generatedAt: meta._generatedAt,
         };
     }
-    // Has _content but no _feedback: critic is pending
-    if (meta._content && !meta._feedback) {
-        return {
-            architect: 'fresh',
-            builder: 'fresh',
-            critic: 'pending',
-        };
+    catch {
+        return { content: null, generatedAt: undefined };
     }
-    // Default: fully fresh
-    return freshPhaseState();
 }
-
-/**
- * Compute a structure hash from a sorted file listing.
- *
- * Used to detect when directory structure changes, triggering
- * an architect re-run.
- *
- * @module structureHash
- */
 /**
- * Compute a SHA-256 hash of a sorted file listing.
+ * Read a meta.json file and extract its `_content` field.
  *
- * @param filePaths - Array of file paths in scope.
- * @returns Hex-encoded SHA-256 hash of the sorted, newline-joined paths.
+ * @param metaJsonPath - Absolute path to a meta.json file.
+ * @returns The `_content` string, or null if missing/unreadable.
  */
-function computeStructureHash(filePaths) {
-    const sorted = [...filePaths].sort();
-    const content = sorted.join('\n');
-    return createHash('sha256').update(content).digest('hex');
+async function readMetaContent(metaJsonPath) {
+    const info = await readChildMeta(metaJsonPath);
+    return info.content;
 }
-
 /**
- * Per-tick invalidation pass.
- *
- * Computes architect-invalidating and builder-invalidating inputs for a meta,
- * then applies the cascade to update _phaseState.
+ * Build the context package for a synthesis cycle.
  *
- * @module phaseState/invalidate
- */
-/**
- * Check whether a persisted prompt snapshot mismatches the currently-resolved prompt.
- * Returns true when the snapshot exists and differs from the resolved prompt.
- * This is informational only — it does NOT trigger invalidation.
+ * @param node - The meta node being synthesized.
+ * @param meta - Current meta.json content.
+ * @param watcher - WatcherClient for scope enumeration.
+ * @returns The computed context package.
  */
-function isPromptStale(snapshot, resolved) {
-    return snapshot !== undefined && snapshot !== resolved;
-}
-/**
- * Compute invalidation inputs and apply cascade for a single meta.
- *
- * @param meta - Current meta.json content with existing _phaseState.
- * @param scopeFiles - Sorted file list from scope.
- * @param config - MetaConfig for architectEvery.
- * @param node - MetaNode for archive access.
- * @param crossRefMetas - Map of cross-ref owner paths to their current _content.
- * @param archiveCrossRefContent - Map of cross-ref owner paths to their archived _content.
- * @returns Updated phase state and invalidation details.
- */
-async function computeInvalidation(meta, scopeFiles, config, node, crossRefMetas, archiveCrossRefContent) {
-    let phaseState = meta._phaseState ?? {
-        architect: 'fresh',
-        builder: 'fresh',
-        critic: 'fresh',
-    };
-    // ── Architect-level inputs ──
-    const structureHash = computeStructureHash(scopeFiles);
-    const structureChanged = structureHash !== meta._structureHash;
-    const latestArchive = await readLatestArchive(node.metaPath);
-    const steerChanged = hasSteerChanged(meta._steer, latestArchive?._steer, Boolean(latestArchive));
-    // Prompt staleness detection: compare persisted prompt snapshots against
-    // currently-resolved prompts.  This is INFORMATIONAL ONLY — reported via
-    // inputStatus so /preview can surface it, but it must NEVER feed into
-    // the invalidation cascade.  When a meta naturally reaches architectEvery
-    // through real builder cycles, architect runs with the current prompt and
-    // the snapshot updates.  Coupling prompt changes to invalidation causes a
-    // corpus-wide synthesis storm (see #163).
-    const architectChanged = isPromptStale(meta._architect, DEFAULT_ARCHITECT_PROMPT);
-    const criticChanged = isPromptStale(meta._critic, DEFAULT_CRITIC_PROMPT);
-    const effectiveSynthesisCount = meta._synthesisCount ?? 0;
-    // _crossRefs declaration change
-    const currentRefs = (meta._crossRefs ?? []).slice().sort().join(',');
-    const archiveRefs = (latestArchive?._crossRefs ?? [])
-        .slice()
-        .sort()
-        .join(',');
-    const crossRefsDeclChanged = latestArchive
-        ? currentRefs !== archiveRefs
-        : currentRefs.length > 0;
-    const architectInvalidators = [];
-    if (structureChanged) {
-        if (meta._state !== undefined) {
-            // Progressive entity: new files → builder only (cursor handles incremental)
-            phaseState = invalidateBuilder(phaseState);
+async function buildContextPackage(node, meta, watcher, logger) {
+    // Scope and delta files via watcher walk
+    const scopeStart = Date.now();
+    const { scopeFiles } = await getScopeFiles(node, watcher, logger);
+    const deltaFiles = getDeltaFiles(meta._generatedAt, scopeFiles);
+    logger?.debug({
+        scopeFiles: scopeFiles.length,
+        deltaFiles: deltaFiles.length,
+        durationMs: Date.now() - scopeStart,
+    }, 'scope and delta files computed');
+    // Child meta outputs (parallel reads, delta-aware).
+    // Only include full _content for children synthesized AFTER the parent's
+    // _generatedAt. Non-delta children are already folded into the parent's
+    // previous _content and are listed as path-only references (#169).
+    const parentGeneratedAt = meta._generatedAt;
+    const childMetas = {};
+    const childEntries = await Promise.all(node.children.map(async (child) => {
+        const info = await readChildMeta(join(child.metaPath, 'meta.json'));
+        return [child.ownerPath, info];
+    }));
+    let deltaChildCount = 0;
+    for (const [path, info] of childEntries) {
+        // Delta child: no parent timestamp (first run), or child synthesized
+        // after parent. Include full content.
+        if (!parentGeneratedAt ||
+            !info.generatedAt ||
+            info.generatedAt > parentGeneratedAt) {
+            childMetas[path] = info.content ?? undefined;
+            deltaChildCount++;
         }
         else {
-            architectInvalidators.push('structureHash');
+            // Non-delta: already incorporated in previous synthesis.
+            // Include path with null content so the builder knows it exists.
+            childMetas[path] = null;
         }
     }
-    if (steerChanged)
-        architectInvalidators.push('steer');
-    if (crossRefsDeclChanged)
-        architectInvalidators.push('_crossRefs');
-    if (effectiveSynthesisCount >= config.architectEvery) {
-        architectInvalidators.push('architectEvery');
+    logger?.debug({
+        totalChildren: childEntries.length,
+        deltaChildren: deltaChildCount,
+    }, 'child metas filtered by delta');
+    // Cross-referenced meta outputs (parallel reads)
+    const crossRefMetas = {};
+    const seen = new Set();
+    const crossRefPaths = [];
+    for (const refPath of meta._crossRefs ?? []) {
+        if (refPath === node.ownerPath || refPath === node.metaPath)
+            continue;
+        if (seen.has(refPath))
+            continue;
+        seen.add(refPath);
+        crossRefPaths.push(refPath);
     }
-    if (!meta._builder)
-        architectInvalidators.push('firstRun');
-    if (architectInvalidators.length > 0) {
-        phaseState = invalidateArchitect(phaseState);
+    const crossRefEntries = await Promise.all(crossRefPaths.map(async (refPath) => {
+        const content = await readMetaContent(join(refPath, '.meta', 'meta.json'));
+        return [refPath, content];
+    }));
+    for (const [path, content] of crossRefEntries) {
+        crossRefMetas[path] = content;
+    }
+    // Archive paths
+    const archives = listArchiveFiles(node.metaPath);
+    // Nearest ancestor _builder output
+    let ancestorBuilder;
+    const ancestor = getAncestorMeta(node);
+    if (ancestor) {
+        try {
+            const raw = await readFile(join(ancestor.metaPath, 'meta.json'), 'utf8');
+            const ancestorMeta = JSON.parse(raw);
+            if (ancestorMeta._builder) {
+                ancestorBuilder = ancestorMeta._builder;
+            }
+        }
+        catch {
+            // Ancestor meta.json unreadable — skip
+        }
     }
-    // ── Builder-level inputs ──
-    // Cross-ref _content change (builder-invalidating)
-    let crossRefContentChanged = false;
     return {
-        phaseState,
-        architectInvalidators,
-        inputStatus: {
-            structureHash,
-            steerChanged,
-            architectChanged,
-            criticChanged,
-            crossRefsDeclChanged,
-            crossRefContentChanged,
-        },
+        path: node.metaPath,
+        scopeFiles,
+        deltaFiles,
+        childMetas,
+        crossRefMetas,
+        previousContent: meta._content ?? null,
+        previousFeedback: meta._feedback ?? null,
+        steer: meta._steer ?? null,
+        previousState: meta._state ?? null,
+        archives,
+        ancestorBuilder,
     };
 }
 
 /**
- * Weighted staleness formula for candidate selection.
- *
- * effectiveStaleness = actualStaleness * (normalizedDepth + 1) ^ (depthWeight * emphasis)
- *
- * @module scheduling/weightedFormula
- */
-/**
- * Compute effective staleness for a set of candidates.
- *
- * Normalizes depths so the minimum becomes 0, then applies the formula:
- * effectiveStaleness = actualStaleness * (normalizedDepth + 1) ^ (depthWeight * emphasis)
+ * Build task prompts for each synthesis step.
  *
- * Per-meta _emphasis (default 1) multiplies depthWeight, allowing individual
- * metas to tune how much their tree position affects scheduling.
+ * Prompts are compiled as Handlebars templates with access to config,
+ * meta, and scope context. The architect can write template expressions
+ * into its _builder output; these resolve when the builder task is compiled.
  *
- * @param candidates - Array of \{ node, meta, actualStaleness \}.
- * @param depthWeight - Exponent for depth weighting (0 = pure staleness).
- * @returns Same array with effectiveStaleness computed.
+ * @module orchestrator/buildTask
  */
-function computeEffectiveStaleness(candidates, depthWeight) {
-    if (candidates.length === 0)
-        return [];
-    // Get depth for each candidate: use _depth override or tree depth
-    const depths = candidates.map((c) => c.meta._depth ?? c.node.treeDepth);
-    // Normalize: shift so minimum becomes 0
-    const minDepth = Math.min(...depths);
-    const normalizedDepths = depths.map((d) => Math.max(0, d - minDepth));
-    return candidates.map((c, i) => {
-        const emphasis = c.meta._emphasis ?? 1;
-        return {
-            ...c,
-            effectiveStaleness: c.actualStaleness *
-                Math.pow(normalizedDepths[i] + 1, depthWeight * emphasis),
-        };
-    });
+Handlebars.registerHelper('gt', (a, b) => a > b);
+/** Build the template context from synthesis inputs. */
+function buildTemplateContext(ctx, meta, config) {
+    return {
+        config,
+        meta,
+        scope: {
+            fileCount: ctx.scopeFiles.length,
+            deltaCount: ctx.deltaFiles.length,
+            childCount: Object.keys(ctx.childMetas).length,
+            crossRefCount: Object.keys(ctx.crossRefMetas).length,
+        },
+    };
 }
-
 /**
- * Corpus-wide phase scheduler.
- *
- * Selects the highest-priority ready phase across all metas.
- * Priority: critic (band 1) \> builder (band 2) \> architect (band 3).
- * Tiebreak within band: weighted staleness (§3.9).
- *
- * @module phaseState/phaseScheduler
+ * Compile a string as a Handlebars template with the given context.
+ * Returns the original string unchanged if compilation fails.
  */
+function compileTemplate(text, context) {
+    try {
+        return Handlebars.compile(text, { noEscape: true })(context);
+    }
+    catch {
+        return text;
+    }
+}
 /**
- * Build phase candidates from listMetas entries.
+ * Append a keyed record of meta outputs as subsections, if non-empty.
  *
- * Derives phase state, auto-retries failed phases, and applies Tier 1
- * cheap-invalidation (no I/O) for metas with persisted _phaseState.
- * Used by orchestratePhase, queue route, and status route.
+ * @param condenseMissing - When true, null entries are condensed into a
+ *   path listing (delta-aware child metas). When false, null entries get
+ *   individual subsections with "(not yet synthesized)" (cross-refs).
  */
-function buildPhaseCandidates(entries, architectEvery) {
-    return entries.map((entry) => {
-        let ps = retryAllFailed(derivePhaseState(entry.meta));
-        // Tier 1 cheap invalidation for metas with persisted _phaseState
-        if (entry.meta._phaseState) {
-            const needsArchitect = !entry.meta._builder ||
-                (entry.meta._synthesisCount ?? 0) >= architectEvery;
-            if (needsArchitect && isFullyFresh(ps)) {
-                ps = { architect: 'pending', builder: 'stale', critic: 'stale' };
-            }
+function appendMetaSections(sections, heading, metas, condenseMissing = false) {
+    if (Object.keys(metas).length === 0)
+        return;
+    if (!condenseMissing) {
+        // Original behavior: every entry gets a subsection.
+        sections.push('', heading);
+        for (const [path, content] of Object.entries(metas)) {
+            sections.push(`### ${path}`, typeof content === 'string' ? content : '(not yet synthesized)');
         }
-        return {
-            node: entry.node,
-            meta: entry.meta,
-            phaseState: ps,
-            actualStaleness: entry.stalenessSeconds,
-            locked: entry.locked,
-            disabled: entry.disabled,
-        };
-    });
+        return;
+    }
+    // Delta-aware: separate entries into three categories (#169).
+    // - string content → full subsection (delta child with content)
+    // - null → non-delta, already folded into previous synthesis
+    // - undefined → delta child not yet synthesized
+    const withContent = [];
+    const unchanged = [];
+    const notYetSynthesized = [];
+    for (const [path, content] of Object.entries(metas)) {
+        if (typeof content === 'string') {
+            withContent.push([path, content]);
+        }
+        else if (content === null) {
+            unchanged.push(path);
+        }
+        else {
+            notYetSynthesized.push(path);
+        }
+    }
+    sections.push('', heading);
+    for (const [path, content] of withContent) {
+        sections.push(`### ${path}`, content);
+    }
+    if (notYetSynthesized.length > 0) {
+        sections.push('', `### Not yet synthesized (${notYetSynthesized.length.toString()})`, ...notYetSynthesized.map((p) => `- ${p}`));
+    }
+    if (unchanged.length > 0) {
+        sections.push('', `### Other children (${unchanged.length.toString()} \u2014 unchanged since last synthesis)`, ...unchanged.map((p) => `- ${p}`));
+    }
+}
+/** Inject nearest ancestor's organizational context, if available. */
+function appendAncestorContext(sections, ctx) {
+    if (ctx.ancestorBuilder) {
+        sections.push('', '## PARENT ORGANIZATIONAL CONTEXT', ctx.ancestorBuilder);
+    }
+}
+/** Append optional context sections shared across all step prompts. */
+function appendSharedSections(sections, ctx, options) {
+    const opts = {
+        includeSteer: true,
+        includePreviousContent: true,
+        includePreviousFeedback: true,
+        feedbackHeading: '## PREVIOUS FEEDBACK',
+        includeChildMetas: true,
+        includeCrossRefs: true,
+        ...options,
+    };
+    if (opts.includeSteer && ctx.steer) {
+        sections.push('', '## STEERING PROMPT', ctx.steer);
+    }
+    if (opts.includePreviousContent && ctx.previousContent) {
+        sections.push('', '## PREVIOUS SYNTHESIS', ctx.previousContent);
+    }
+    if (opts.includePreviousFeedback && ctx.previousFeedback) {
+        sections.push('', opts.feedbackHeading, ctx.previousFeedback);
+    }
+    if (opts.includeChildMetas) {
+        appendMetaSections(sections, '## CHILD META OUTPUTS', ctx.childMetas, true);
+    }
+    if (opts.includeCrossRefs) {
+        appendMetaSections(sections, '## CROSS-REFERENCED METAS', ctx.crossRefMetas);
+    }
 }
 /**
- * Rank all eligible phase candidates by priority.
- *
- * Filters to pending phases, computes effective staleness, and sorts by
- * band (ascending: critic first) then effective staleness (descending).
+ * Build the architect task prompt.
  *
- * Used by selectPhaseCandidate (returns first) and the queue route (returns all).
+ * @param ctx - Synthesis context.
+ * @param meta - Current meta.json.
+ * @param config - Synthesis config.
+ * @returns The architect task prompt string.
  */
-function rankPhaseCandidates(metas, depthWeight) {
-    // Filter to metas with a pending (scheduler-eligible) phase
-    const eligible = metas.filter((m) => {
-        if (m.locked)
-            return false;
-        if (m.disabled && !m.isOverride)
-            return false;
-        const owed = getOwedPhase(m.phaseState);
-        if (!owed)
-            return false;
-        return m.phaseState[owed] === 'pending';
-    });
-    if (eligible.length === 0)
-        return [];
-    // Compute effective staleness for tiebreaking
-    const withStaleness = computeEffectiveStaleness(eligible.map((m) => ({
-        node: m.node,
-        meta: m.meta,
-        actualStaleness: m.actualStaleness,
-    })), depthWeight);
-    // Build candidates with band info
-    const candidates = withStaleness.map((ws, i) => {
-        const m = eligible[i];
-        const owedPhase = getOwedPhase(m.phaseState);
-        return {
-            node: ws.node,
-            meta: ws.meta,
-            phaseState: m.phaseState,
-            owedPhase,
-            band: getPriorityBand(m.phaseState),
-            actualStaleness: ws.actualStaleness,
-            effectiveStaleness: ws.effectiveStaleness,
-        };
-    });
-    // Sort by band (ascending = critic first) then effective staleness (descending)
-    candidates.sort((a, b) => {
-        if (a.band !== b.band)
-            return a.band - b.band;
-        return b.effectiveStaleness - a.effectiveStaleness;
-    });
-    return candidates;
+function buildArchitectTask(ctx, meta, config) {
+    const sections = [
+        `# jeeves-meta · ARCHITECT · ${ctx.path}`,
+        '',
+        getDefaultArchitectPrompt(),
+        '',
+        '## SCOPE',
+        `Path: ${ctx.path}`,
+        `Total files in scope: ${ctx.scopeFiles.length.toString()}`,
+        `Files changed since last synthesis: ${ctx.deltaFiles.length.toString()}`,
+        '',
+        '### File listing (scope)',
+        condenseScopeFiles(ctx.scopeFiles),
+    ];
+    appendAncestorContext(sections, ctx);
+    // Inject previous _builder so architect can see its own prior output
+    if (meta._builder) {
+        sections.push('', '## PREVIOUS TASK BRIEF', meta._builder);
+    }
+    appendSharedSections(sections, ctx);
+    if (ctx.archives.length > 0) {
+        sections.push('', '## ARCHIVE HISTORY', `${ctx.archives.length.toString()} previous synthesis snapshots available in .meta/archive/.`, 'Review these to understand how the synthesis has evolved over time.');
+    }
+    return compileTemplate(sections.join('\n'), buildTemplateContext(ctx, meta, config));
 }
 /**
- * Select the best phase candidate across the corpus.
+ * Build the builder task prompt.
  *
- * @param metas - Array of (node, meta, phaseState, stalenessSeconds) tuples.
- * @param depthWeight - Config depthWeight for staleness tiebreak.
- * @returns The winning candidate, or null if no phase is ready.
- */
-function selectPhaseCandidate(metas, depthWeight) {
-    return rankPhaseCandidates(metas, depthWeight)[0] ?? null;
-}
-/**
- * Select all fully-fresh, non-disabled, non-locked metas sorted by staleness
- * (descending — stalest first) for Tier 2 invalidation scanning.
+ * @param ctx - Synthesis context.
+ * @param meta - Current meta.json.
+ * @param config - Synthesis config.
+ * @returns The builder task prompt string.
  */
-function selectAllTier2Candidates(metas) {
-    return metas
-        .filter((m) => !m.locked && !m.disabled && isFullyFresh(m.phaseState))
-        .sort((a, b) => b.actualStaleness - a.actualStaleness)
-        .map((m) => ({ node: m.node, meta: m.meta }));
+function buildBuilderTask(ctx, meta, config) {
+    const sections = [
+        `# jeeves-meta · BUILDER · ${ctx.path}`,
+        '',
+        '## TASK BRIEF (from Architect)',
+        meta._builder ?? '(No architect brief available)',
+        '',
+        '## SCOPE',
+        `Path: ${ctx.path}`,
+        `Delta files (${ctx.deltaFiles.length.toString()} changed):`,
+        ...ctx.deltaFiles.slice(0, config.maxLines).map((f) => `- ${f}`),
+    ];
+    appendAncestorContext(sections, ctx);
+    if (ctx.previousState != null) {
+        sections.push('', '## PREVIOUS STATE', 'The following opaque state was returned by the previous synthesis cycle.', 'Use it to continue progressive work. Update `_state` in your output to', 'reflect your progress.', '', '```json', JSON.stringify(ctx.previousState, null, 2), '```');
+    }
+    appendSharedSections(sections, ctx, {
+        includeSteer: false,
+        feedbackHeading: '## FEEDBACK FROM CRITIC',
+    });
+    sections.push('', '## OUTPUT FORMAT', '', 'Respond with ONLY a JSON object. No explanation, no markdown fences, no text before or after.', '', 'Required schema:', '{', '  "type": "object",', '  "required": ["_content"],', '  "properties": {', '    "_content": { "type": "string", "description": "Markdown narrative synthesis" },', '    "_state": { "description": "Opaque state object for progressive work across cycles" }', '  },', '  "additionalProperties": true', '}', '', 'Add any structured fields that capture important facts about this entity', '(e.g. status, risks, dependencies, metrics). Use descriptive key names without underscore prefix.', 'The _content field is the only required key — everything else is domain-driven.', '_state is optional: set it to carry state across synthesis cycles for progressive work.', '', 'DIAGRAMS: When diagrams would aid understanding, use PlantUML in fenced code blocks (```plantuml).', 'PlantUML is rendered natively by the serving infrastructure. NEVER use ASCII art diagrams.', '', 'IMPORTANT: Do not call sessions_spawn or sessions_yield. Read all files directly using the tools', 'available in your session. Do not attempt to parallelize work by spawning sub-agents.');
+    return compileTemplate(sections.join('\n'), buildTemplateContext(ctx, meta, config));
 }
-
-/**
- * Shared error utilities.
- *
- * @module errors
- */
 /**
- * Wrap an unknown caught value into a MetaError.
+ * Build the critic task prompt.
  *
- * @param step - Which synthesis step failed.
- * @param err - The caught error value.
- * @param code - Error classification code.
- * @returns A structured MetaError.
+ * @param ctx - Synthesis context.
+ * @param meta - Current meta.json (with _content already set by builder).
+ * @param config - Synthesis config.
+ * @returns The critic task prompt string.
  */
-function toMetaError(step, err, code = 'FAILED') {
-    return {
-        step,
-        code,
-        message: err instanceof Error ? err.message : String(err),
-    };
+function buildCriticTask(ctx, meta, config) {
+    const sections = [
+        `# jeeves-meta · CRITIC · ${ctx.path}`,
+        '',
+        getDefaultCriticPrompt(),
+        '',
+        '## SYNTHESIS TO EVALUATE',
+        meta._content ?? '(No content produced)',
+        '',
+        '## SCOPE',
+        `Path: ${ctx.path}`,
+        `Files in scope: ${ctx.scopeFiles.length.toString()}`,
+    ];
+    appendSharedSections(sections, ctx, {
+        includePreviousContent: false,
+        feedbackHeading: '## YOUR PREVIOUS FEEDBACK',
+        includeChildMetas: false,
+        includeCrossRefs: false,
+    });
+    sections.push('', '## OUTPUT FORMAT', 'Return your evaluation as Markdown text. Be specific and actionable.');
+    return compileTemplate(sections.join('\n'), buildTemplateContext(ctx, meta, config));
 }
 
 /**
@@ -2723,7 +2672,7 @@ async function runArchitect(node, currentMeta, phaseState, config, executor, wat
         ps = architectSuccess(ps);
         const architectUpdates = {
             _builder: builderBrief,
-            _architect: DEFAULT_ARCHITECT_PROMPT,
+            _architect: getDefaultArchitectPrompt(),
             _synthesisCount: 0,
             _architectTokens: architectTokens,
             _generatedAt: new Date().toISOString(),
@@ -2876,7 +2825,7 @@ async function runCritic(node, currentMeta, phaseState, config, executor, watche
         const cycleComplete = isFullyFresh(ps);
         const updates = {
             _feedback: feedback,
-            _critic: DEFAULT_CRITIC_PROMPT,
+            _critic: getDefaultCriticPrompt(),
             _criticTokens: criticTokens,
             _error: undefined,
         };
@@ -4170,6 +4119,100 @@ function registerConfigApplyRoute(app, configPath) {
     });
 }
 
+/**
+ * Archive reading helpers — watcher scan with filesystem fallback.
+ *
+ * Used by the GET /metas/:path route to retrieve archive history.
+ * Prefers watcher scan for performance; falls back to disk reads
+ * when the watcher is unavailable.
+ *
+ * @module archive/readArchive
+ */
+/** Build a Qdrant filter for archive points under a given meta path. */
+function buildArchiveScanFilter(metaPath, metaArchiveProperty) {
+    const must = [
+        {
+            key: 'file_path',
+            match: { text: normalizePath(join(metaPath, 'archive')) },
+        },
+    ];
+    for (const [key, value] of Object.entries(metaArchiveProperty)) {
+        must.push({ key, match: { value } });
+    }
+    return { must };
+}
+/** Extract file_path from a scan point payload. */
+function getArchiveFilePath(point) {
+    const value = point.payload?.file_path;
+    return typeof value === 'string' ? value : '';
+}
+/** Project archive metadata, stripping indexing-internal fields. */
+function projectArchivePayload(point, projectMeta) {
+    const payload = point.payload ?? {};
+    if (Object.keys(payload).length === 0)
+        return null;
+    const archiveMeta = { ...payload };
+    delete archiveMeta.file_path;
+    delete archiveMeta.chunk_text;
+    delete archiveMeta.chunk_index;
+    delete archiveMeta.total_chunks;
+    delete archiveMeta.content_hash;
+    delete archiveMeta.matched_rules;
+    return projectMeta(archiveMeta);
+}
+/**
+ * Read archive history via watcher scan.
+ *
+ * @param watcher - WatcherClient with scan support.
+ * @param metaPath - Absolute path to the .meta/ directory.
+ * @param metaArchiveProperty - Additional filter properties for archive points.
+ * @param limit - Max entries to return (newest first). Undefined = all.
+ * @param projectMeta - Field projection function.
+ * @returns Array of projected archive entries, newest first.
+ */
+async function readArchiveFromWatcher(watcher, metaPath, metaArchiveProperty, limit, projectMeta) {
+    if (limit === 0)
+        return [];
+    if (!watcher.scan) {
+        throw new Error('Watcher scan not available');
+    }
+    const points = [];
+    let cursor;
+    do {
+        const result = await watcher.scan({
+            filter: buildArchiveScanFilter(metaPath, metaArchiveProperty),
+            limit: 100,
+            cursor,
+        });
+        points.push(...result.points);
+        cursor = result.cursor ?? undefined;
+    } while (cursor);
+    const sorted = points.sort((a, b) => getArchiveFilePath(a).localeCompare(getArchiveFilePath(b)));
+    return sorted
+        .slice(limit ? -limit : 0)
+        .reverse()
+        .map((point) => projectArchivePayload(point, projectMeta))
+        .filter((value) => value !== null);
+}
+/**
+ * Read archive history from disk (fallback).
+ *
+ * @param metaPath - Absolute path to the .meta/ directory.
+ * @param limit - Max entries to return (newest first). Undefined = all.
+ * @param projectMeta - Field projection function.
+ * @returns Array of projected archive entries, newest first.
+ */
+async function readArchiveFromDisk(metaPath, limit, projectMeta) {
+    if (limit === 0)
+        return [];
+    const archiveFiles = listArchiveFiles(metaPath);
+    const selected = (limit ? archiveFiles.slice(-limit) : archiveFiles).reverse();
+    return Promise.all(selected.map(async (archiveFile) => {
+        const raw = await readFile(archiveFile, 'utf8');
+        return projectMeta(JSON.parse(raw));
+    }));
+}
+
 /**
  * GET /metas — list metas with optional filters.
  * GET /metas/:path — single meta detail.
@@ -5551,8 +5594,8 @@ function registerCustomCliCommands(program) {
 /**
  * Jeeves component descriptor for jeeves-meta.
  *
- * Single source of truth consumed by the service CLI, plugin writer, and
- * config-apply pipeline.
+ * Single source of truth consumed by the service CLI and the config-apply
+ * pipeline.
  *
  * @module descriptor
  */
@@ -5565,8 +5608,6 @@ const metaDescriptor = jeevesComponentDescriptorSchema.parse({
     servicePackage: META_COMPONENT.servicePackage,
     pluginPackage: META_COMPONENT.pluginPackage,
     defaultPort: META_COMPONENT.defaultPort,
-    // The runtime Zod custom validator only checks for a .parse() method.
-    // Use unknown cast to bridge the Zod v4 (service) → v3 (core SDK) type gap.
     configSchema: serviceConfigSchema,
     configFileName: 'config.json',
     initTemplate: () => serviceConfigSchema.parse({
@@ -5588,10 +5629,6 @@ const metaDescriptor = jeevesComponentDescriptorSchema.parse({
         '-c',
         configPath,
     ],
-    sectionId: 'Meta',
-    refreshIntervalSeconds: 73,
-    generateToolsContent: () => '',
-    dependencies: { hard: ['watcher'], soft: [] },
     customCliCommands: registerCustomCliCommands,
 });