@aiwg/cli 2026.10.4 → 2026.10.6

package/dist/src/artifacts/index-files.js

@@ -87,9 +87,14 @@ export async function collectGraphIndexFiles(cwd, graph, options = {}) {
         throw new Error(`Unknown graph: ${graph}`);
     }
     const artifactRoot = resolveProjectAiwgDir(cwd);
-    const excludedDirs = [path.join(cwd, DEFAULT_PROJECT_AIWG_DIR), artifactRoot]
-        .flatMap(root => INDEX_SCRATCH_DIRS.map(name => path.resolve(root, name)));
-    const excludedPaths = new Set(excludedDirs);
+    const artifactRoots = [path.join(cwd, DEFAULT_PROJECT_AIWG_DIR), artifactRoot];
+    // Aggregate owner state contains history, tombstones and transaction payloads.
+    // It is not an ordinary artifact: only each owner's public projection is a
+    // retrieval surface, never the backing store or maintenance receipts.
+    const privateDirs = ['context/compound-memory', 'memory/transactions', 'memory/maintenance'];
+    const privateFiles = ['memory/line-memory.meta.json', 'memory/line-memory.config.json', 'memory/line-memory.lock'];
+    const excludedDirs = artifactRoots.flatMap(root => [...INDEX_SCRATCH_DIRS, ...privateDirs].map(name => path.resolve(root, name)));
+    const excludedPaths = new Set([...excludedDirs, ...artifactRoots.flatMap(root => privateFiles.map(name => path.resolve(root, name)))]);
     // A directory's ancestors are shared by thousands of sibling artifacts.
     // Cache only within this scan so the next build still notices new symlinks.
     const safePaths = new Map();
@@ -109,7 +114,7 @@ export async function collectGraphIndexFiles(cwd, graph, options = {}) {
         }
         const inputPath = file;
         file = path.resolve(file);
-        if (excludedDirs.some(dir => process.platform === 'win32'
+        if (excludedPaths.has(file) || excludedDirs.some(dir => process.platform === 'win32'
             ? pathContains(dir, file) : file === dir || file.startsWith(dir + path.sep)))
             return false;
         if (knownStat && !knownStat.isSymbolicLink() && safePaths.get(path.dirname(file)) === true) {
@@ -190,6 +195,10 @@ export async function collectGraphIndexFiles(cwd, graph, options = {}) {
         }
     }
     let sources = [...files];
+    const candidates = [...sources].sort();
+    if (options.selection?.files && JSON.stringify(candidates) === JSON.stringify(options.selection.candidates)) {
+        return [...options.selection.files];
+    }
     if (!options.includeIgnored) {
         // Many projects ignore the whole artifact root (`.aiwg/`). Honoring that
         // would empty the index, so ignore rules apply only beneath a scan root
@@ -225,6 +234,8 @@ export async function collectGraphIndexFiles(cwd, graph, options = {}) {
             if (!selected.has(file))
                 options.fileStats.delete(file);
     }
+    if (options.selection)
+        Object.assign(options.selection, { candidates, files: [...sources] });
     return sources;
 }
 //# sourceMappingURL=index-files.js.map

package/dist/src/artifacts/index-preparation.js

@@ -1,65 +1,130 @@
 /** Bounded artifact-local preparation; ordered graph reduction stays in index-builder. */
 import os from 'node:os';
-import { Worker } from 'node:worker_threads';
+import { fork } from 'node:child_process';
+import { signalChild } from '../process/signal-child.mjs';
+const MIB = 1024 ** 2;
+const WORKER_HEAP_MB = 256;
+// Leave room for V8's young generation, executable code, IPC and native allocations.
+const WORKER_BUDGET_BYTES = 512 * MIB;
+// Parsing and metadata extraction amplify input size; do large files only after the pool exits.
+const MAX_WORKER_ARTIFACT_BYTES = MIB;
+export function resolveIndexWorkers(requested, env = process.env) {
+    const value = requested ?? env.AIWG_INDEX_WORKERS;
+    if (requested === undefined && (value === undefined || value === ''))
+        return undefined;
+    if ((typeof value === 'string' && !/^\d+$/.test(value))
+        || !Number.isSafeInteger(Number(value)) || Number(value) < 0) {
+        throw new Error(`${requested === undefined ? 'AIWG_INDEX_WORKERS' : '--index-workers'} must be a nonnegative safe integer (0 = serial)`);
+    }
+    return Number(value);
+}
 export function indexPreparationWorkers(jobs, requested, cores = os.availableParallelism(), memory = Math.min(os.freemem(), process.availableMemory?.() ?? Infinity), totalBytes = 0) {
-    if (requested !== undefined && (!Number.isInteger(requested) || requested < 0))
-        throw new Error('Index workers must be a nonnegative integer');
+    requested = resolveIndexWorkers(requested);
     if (jobs < 64 || cores < 3 || requested === 0 || requested === 1)
         return 0;
-    // Thread startup costs dominate lightweight scans even at thousands of files.
-    // Explicit thread requests bypass only this conservative automatic workload gate.
-    if (requested === undefined && (jobs < 1000 || !Number.isFinite(totalBytes) || totalBytes < 16 * 1024 ** 2))
+    // Process startup costs dominate lightweight scans even at thousands of files.
+    // Explicit requests bypass only this conservative automatic workload gate.
+    if (requested === undefined && (jobs < 1000 || !Number.isFinite(totalBytes) || totalBytes < 16 * MIB))
         return 0;
-    const byMemory = Math.floor((memory - 512 * 1024 ** 2) / (256 * 1024 ** 2));
+    const byMemory = Math.floor((memory - 512 * MIB) / WORKER_BUDGET_BYTES);
     const bounded = Math.max(0, Math.min(requested ?? 4, 4, cores - 1, byMemory, jobs));
     return bounded >= 2 ? bounded : 0;
 }
-export async function runIndexPreparation(jobs, serial, moduleUrl, requested) {
-    const workerCount = indexPreparationWorkers(jobs.length, requested, undefined, undefined, jobs.reduce((total, job) => total + job.sizeBytes, 0));
+export async function runIndexPreparation(jobs, serial, moduleUrl, requested, onDiagnostic) {
+    const diagnostics = [];
+    const diagnose = (message) => { diagnostics.push(message); onDiagnostic?.(message); };
+    const eligible = jobs.map((job, index) => ({ job, index })).filter(({ job }) => Number.isFinite(job.sizeBytes) && job.sizeBytes >= 0 && job.sizeBytes <= MAX_WORKER_ARTIFACT_BYTES);
+    const workerCount = indexPreparationWorkers(eligible.length, requested, undefined, undefined, eligible.reduce((total, { job }) => total + job.sizeBytes, 0));
     if (!workerCount)
-        return { results: jobs.map(serial), workerCount: 0 };
+        return { results: jobs.map(serial), workerCount: 0, diagnostics };
     const results = new Array(jobs.length), workers = [];
+    const closed = [];
     let next = 0, completed = 0, stopped = false;
     try {
         await new Promise((resolve, reject) => {
-            const fail = (error) => { stopped = true; reject(error); };
+            // Stop dispatch on a process failure. Reap the entire pool before retrying
+            // unfinished work in the main isolate, avoiding overlapping memory peaks.
+            const recover = (message) => {
+                if (stopped)
+                    return;
+                stopped = true;
+                diagnose(`${message}; retrying unfinished preparation serially`);
+                resolve();
+            };
             const dispatch = (worker) => {
-                if (!stopped && next < jobs.length) {
-                    const index = next++;
-                    worker.postMessage({ index, job: jobs[index] });
+                if (stopped || next >= eligible.length)
+                    return;
+                const { index, job } = eligible[next++];
+                try {
+                    worker.send({ index, job }, error => { if (error)
+                        recover(`Index preparation IPC failed for ${job.relativePath}: ${error.message}`); });
+                }
+                catch (error) {
+                    recover(`Index preparation IPC failed for ${job.relativePath}: ${error instanceof Error ? error.message : String(error)}`);
                 }
             };
-            for (let index = 0; index < workerCount; index++) {
-                const worker = new Worker(new URL('./index-worker.mjs', import.meta.url), {
-                    workerData: { moduleUrl }, execArgv: [], resourceLimits: { maxOldGenerationSizeMb: 256 },
+            for (let index = 0; index < workerCount && !stopped; index++) {
+                // A worker_threads resourceLimit is not a process boundary: V8 can abort
+                // Node during allocation before its isolate-limit error is delivered.
+                // A child heap fatal/SIGABRT is instead an ordinary, recoverable exit.
+                const worker = fork(new URL('./index-worker.mjs', import.meta.url), [moduleUrl], {
+                    execArgv: [`--max-old-space-size=${WORKER_HEAP_MB}`, '--max-semi-space-size=16'],
+                    stdio: ['ignore', 'ignore', 'pipe', 'ipc'], serialization: 'advanced',
                 });
                 workers.push(worker);
-                worker.on('error', fail);
-                worker.on('exit', code => { if (!stopped && completed < jobs.length)
-                    fail(new Error(`Index preparation worker exited early (${code})`)); });
-                worker.on('message', message => {
+                closed.push(new Promise(done => worker.once('close', () => done())));
+                let stderr = '';
+                let activePath = '<startup>';
+                worker.stderr?.on('data', chunk => { stderr = (stderr + String(chunk)).slice(-8192); });
+                worker.on('error', error => recover(`Index preparation worker failed for ${activePath}: ${error.message}`));
+                worker.on('exit', (code, signal) => {
+                    const oom = /heap out of memory|ERR_WORKER_OUT_OF_MEMORY/i.test(stderr) ? ' (heap out of memory)' : '';
+                    recover(`Index preparation worker exited early for ${activePath} (${signal ?? code})${oom}`);
+                });
+                worker.on('message', (message) => {
                     if (stopped)
                         return;
                     if (message.error) {
-                        fail(new Error(message.error));
+                        stopped = true;
+                        reject(new Error(message.error));
                         return;
                     }
                     results[message.index] = message.result;
                     completed++;
-                    if (completed === jobs.length) {
+                    if (completed === eligible.length) {
                         stopped = true;
                         resolve();
                     }
-                    else
+                    else {
+                        activePath = eligible[next]?.job.relativePath ?? '<idle>';
                         dispatch(worker);
+                    }
                 });
+                activePath = eligible[next]?.job.relativePath ?? '<idle>';
                 dispatch(worker);
             }
         });
-        return { results, workerCount };
     }
     finally {
-        await Promise.all(workers.map(worker => worker.terminate()));
+        stopped = true;
+        for (const worker of workers)
+            if (worker.exitCode === null && worker.signalCode === null)
+                signalChild(worker, 'SIGKILL');
+        await Promise.all(closed);
+    }
+    const largeCount = jobs.length - eligible.length;
+    if (largeCount)
+        diagnose(`${largeCount} artifact(s) above the worker size threshold prepared serially`);
+    for (let index = 0; index < jobs.length; index++) {
+        if (!results[index]) {
+            try {
+                results[index] = serial(jobs[index]);
+            }
+            catch (error) {
+                throw new Error(`${jobs[index].relativePath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
     }
+    return { results, workerCount, diagnostics };
 }
 //# sourceMappingURL=index-preparation.js.map

package/dist/src/artifacts/index-reader.js

@@ -11,6 +11,7 @@
 import fs from 'fs';
 import path from 'path';
 import { getGraphIndexDir, getProjectIndexRoot } from './types.js';
+import { loadManifest, writeManifest } from './checksum-manifest.js';
 /**
  * Load a JSON file from the index directory
  *
@@ -109,4 +110,47 @@ export function loadGraphIndexFile(cwd, filename, graph) {
         return null;
     }
 }
+/** Publish a prepared snapshot with the existing atomic file writes under the owner lock. */
+export function publishIndexFiles(staging, directory) {
+    const files = fs.readdirSync(staging).filter(file => fs.statSync(path.join(staging, file)).isFile())
+        .sort((a, b) => Number(a === 'metadata.json') - Number(b === 'metadata.json'));
+    const backups = path.join(staging, '.previous');
+    fs.mkdirSync(backups);
+    for (const file of files) {
+        const target = path.join(directory, file);
+        if (fs.existsSync(target))
+            fs.copyFileSync(target, path.join(backups, file));
+    }
+    const published = [];
+    try {
+        for (const file of files) {
+            fs.renameSync(path.join(staging, file), path.join(directory, file));
+            published.push(file);
+        }
+        // Receipts bind to final inode signatures, after the atomic renames.
+        if (files.includes('checksum-manifest.json')) {
+            const manifest = loadManifest(directory);
+            const signature = (file) => {
+                const stat = fs.statSync(path.join(directory, file), { bigint: true });
+                return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(':');
+            };
+            if (manifest.receipt) {
+                manifest.receipt.metadataSignature = signature('metadata.json');
+                if (manifest.receipt.relations)
+                    manifest.receipt.relations.signature = signature('relations.json');
+                writeManifest(directory, manifest);
+            }
+        }
+    }
+    catch (error) {
+        for (const file of published.reverse()) {
+            const backup = path.join(backups, file);
+            if (fs.existsSync(backup))
+                fs.renameSync(backup, path.join(directory, file));
+            else
+                fs.rmSync(path.join(directory, file), { force: true });
+        }
+        throw error;
+    }
+}
 //# sourceMappingURL=index-reader.js.map

package/dist/src/artifacts/index-refresh.js

@@ -1,4 +1,4 @@
-import { createHash, randomUUID } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
 import * as fs from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
@@ -6,13 +6,15 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { findPackageRoot } from '../cli/find-package-root.js';
 import { projectAiwgPath, projectControlPath } from '../config/project-artifacts.js';
 import { getUserStateDir } from '../config/user-state.js';
-import { collectGraphIndexFiles } from './index-files.js';
+import { resolveIndexWorkers } from './index-preparation.js';
+import { resolveFrameworkIndexRoot } from './framework-index-paths.js';
 import { collectIndexStatus } from './index-status.js';
+import { graphIndexDigest, indexAdapterRegistry, selectIndexAdapters, indexFreshnessSnapshot, indexAdapterDigest, recordIndexVerification } from './index-adapters.js';
 import { getFortemiCoreSyncStatus, syncFortemiCoreIndex } from './fortemi-core-sync.js';
 import { acquireDirectoryLock, DirectoryLockContentionError } from './prebuilt-build-lock.js';
 import { resolveImportExclusions } from '../sessions/import-exclusions.js';
 import { resolveImportLimits } from '../sessions/import-limits.js';
-import { BUILTIN_GRAPH_CONFIGS, GRAPH_CONFIGS, INDEX_EXTRACTOR_VERSION, INDEX_VERSION, getGraphIndexDir, graphBuildOrder, loadGlobalGraphConfigs, loadUserGraphConfigs, resolveGraphBackendType, resolveGraphScanDir, } from './types.js';
+import { GRAPH_CONFIGS, getGraphIndexDir, graphBuildOrder, loadWorkspaceGraphs, resolveGraphScanDir, } from './types.js';
 function readJson(file, tolerateMalformed = true) {
     try {
         return JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -28,14 +30,6 @@ function writeJson(file, value) {
     fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
     fs.renameSync(temporary, file);
 }
-/** The registry is process-global; reload it per workspace to avoid cross-project leakage. */
-function loadWorkspaceGraphs(workspace) {
-    for (const name of Object.keys(GRAPH_CONFIGS))
-        delete GRAPH_CONFIGS[name];
-    Object.assign(GRAPH_CONFIGS, structuredClone(BUILTIN_GRAPH_CONFIGS));
-    loadUserGraphConfigs(workspace);
-    loadGlobalGraphConfigs();
-}
 function workspacePaths(options) {
     const cwd = options.cwd ?? process.cwd();
     const found = new Map();
@@ -123,33 +117,38 @@ function planWorkspaceRefresh(options, workspaces) {
             loadWorkspaceGraphs(workspace);
             const graphs = collectIndexStatus(workspace).graphs
                 .sort((a, b) => graphBuildOrder(a.name, GRAPH_CONFIGS[a.name]) - graphBuildOrder(b.name, GRAPH_CONFIGS[b.name]) || a.name.localeCompare(b.name));
-            if (!options.only || options.only === 'graphs') {
+            const adapters = indexAdapterRegistry(workspace);
+            const selected = selectIndexAdapters(adapters, options.only);
+            const includes = (name) => selected.some(adapter => adapter.name === name);
+            if (!options.only || options.only === 'all' || options.only === 'graphs' || selected.some(adapter => adapter.group === 'graphs')) {
                 for (const graph of graphs) {
-                    if (graph.built || graph.defaultBuild || graph.origin === 'registered') {
+                    if (selected.some(adapter => adapter.group === 'graphs' && adapter.graph === graph.name)
+                        && (graph.built || graph.defaultBuild || graph.origin === 'registered'
+                            || (options.only && options.only !== 'all' && options.only !== 'graphs'))) {
                         jobs.push({ kind: 'graph', workspace, graph: graph.name, status: 'planned', wallMs: 0 });
                     }
                 }
             }
-            if (!options.only || options.only === 'caches') {
+            if (!options.only || options.only === 'all' || options.only === 'caches' || options.only?.startsWith('caches:')) {
                 for (const graph of graphs) {
                     // Refresh only local, opted-in caches; never create a new cache from a packaged prebuilt.
-                    if (fs.existsSync(getFortemiCoreSyncStatus(workspace, graph.name).location)) {
+                    if (includes(`caches:${graph.name}`) && fs.existsSync(getFortemiCoreSyncStatus(workspace, graph.name).location)) {
                         jobs.push({ kind: 'cache', workspace, graph: graph.name, status: 'planned', wallMs: 0 });
                     }
                 }
             }
-            if ((!options.only || options.only === 'sessions') && fs.existsSync(path.join(workspace, '.aiwg/sessions/catalog.sqlite'))) {
+            if (includes('sessions') && fs.existsSync(path.join(workspace, '.aiwg/sessions/catalog.sqlite'))) {
                 jobs.push({ kind: 'sessions', workspace, status: 'planned', wallMs: 0, noManifest: 0 });
             }
             for (const kind of ['runtime', 'issues']) {
-                if (options.only && options.only !== kind)
+                if (!includes(kind))
                     continue;
                 if (kind === 'issues' && !fs.existsSync(projectAiwgPath(workspace, 'issues')))
                     continue;
                 jobs.push({ kind, workspace, status: 'planned', wallMs: 0 });
             }
         }
-        if (!options.only || options.only === 'models') {
+        if (!options.only || options.only === 'all' || options.only === 'models') {
             jobs.push({ kind: 'models', scope: 'host', status: 'planned', wallMs: 0 });
         }
         return jobs;
@@ -176,23 +175,6 @@ export async function refreshResourceGate(workspace, live) {
     const result = preflight.evaluateDispatchGate(live ?? preflight.readLiveHostResources({ paths: [workspace] }), thresholds);
     return { ok: result.ok, reason: result.failures.map((failure) => failure.reason).join('; ') || undefined };
 }
-async function graphFingerprint(workspace, graph) {
-    const files = await collectGraphIndexFiles(workspace, graph);
-    // Source import resolution also depends on the compiler/package configuration.
-    if (graph === 'source') {
-        for (const file of ['tsconfig.json', 'package.json']) {
-            if (fs.existsSync(path.join(workspace, file)))
-                files.push(path.join(workspace, file));
-        }
-    }
-    const stats = [...new Set(files)].sort().map(file => {
-        const stat = fs.statSync(file);
-        return [file, stat.mtimeMs, stat.ctimeMs, stat.size];
-    });
-    return createHash('sha256').update(JSON.stringify([
-        INDEX_VERSION, INDEX_EXTRACTOR_VERSION, GRAPH_CONFIGS[graph], resolveGraphBackendType(graph), stats,
-    ])).digest('hex');
-}
 async function refreshWorkspaceRuntime(workspace, full, runtime) {
     const directory = projectAiwgPath(workspace, 'smiths', 'toolsmith');
     const output = path.join(directory, 'runtime.json');
@@ -236,33 +218,54 @@ async function refreshWorkspaceRuntime(workspace, full, runtime) {
 async function executeJob(job, options, aliases, runtime) {
     const workspace = job.workspace ?? process.env.HOME ?? homedir();
     if (job.kind === 'graph') {
+        const graphStart = Date.now();
         const graph = job.graph;
         const config = GRAPH_CONFIGS[graph];
-        if (!config.scanDirs.some(dir => fs.existsSync(resolveGraphScanDir(workspace, dir)))) {
+        const sourceWorkspace = graph === 'framework' ? resolveFrameworkIndexRoot(workspace) : workspace;
+        if (!config.scanDirs.some(dir => fs.existsSync(resolveGraphScanDir(sourceWorkspace, dir)))) {
             job.status = 'skipped';
             job.reason = 'scan directories missing';
             return;
         }
         const directory = getGraphIndexDir(workspace, graph);
         const markerPath = path.join(directory, 'refresh-state.json');
+        const fingerprint = await graphIndexDigest(sourceWorkspace, graph);
         const marker = readJson(markerPath);
         const metadata = readJson(path.join(directory, 'metadata.json'));
-        const fingerprint = await graphFingerprint(workspace, graph);
-        const outputs = ['metadata.json', 'dependencies.json', 'tags.json', 'stats.json'];
-        if (resolveGraphBackendType(graph) === 'sqlite')
-            outputs.push('graph.db');
-        if (!options.full && marker?.fingerprint === fingerprint && metadata?.builtAt === marker.builtAt
-            && outputs.every(file => fs.existsSync(path.join(directory, file)))) {
-            job.status = 'skipped';
-            job.reason = 'unchanged';
-            return;
+        const adapter = indexAdapterRegistry(workspace).find(item => item.name === graph);
+        if (!options.full && marker?.fingerprint === fingerprint && marker.builtAt === metadata?.builtAt
+            && indexFreshnessSnapshot(adapter, workspace).pendingWork === 0) {
+            const release = await acquireDirectoryLock(`${directory}.build.lock`, {
+                timeoutMs: options.lockWaitMs ?? 0, reclaimDeadOwner: true,
+            });
+            try {
+                const current = await graphIndexDigest(sourceWorkspace, graph);
+                if (current === fingerprint && indexFreshnessSnapshot(adapter, workspace).pendingWork === 0) {
+                    recordIndexVerification(adapter, workspace, { before: fingerprint, after: current, wallMs: Date.now() - graphStart });
+                    job.status = 'skipped';
+                    job.reason = 'unchanged';
+                    return;
+                }
+            }
+            finally {
+                await release();
+            }
         }
+        const beforeOutput = outputStamp(path.join(directory, 'metadata.json'));
         const { buildIndex } = await import('./index-builder.js');
-        await buildIndex(workspace, { graph, force: Boolean(options.full), explicit: false, quiet: true });
+        await buildIndex(sourceWorkspace, { graph, force: Boolean(options.full), explicit: false, quiet: true, workers: options.workers, lockWaitMs: options.lockWaitMs ?? 0,
+            onDiagnostic: message => (job.diagnostics ??= []).push(message) });
         const built = readJson(path.join(directory, 'metadata.json'));
         if (!built)
             throw new Error(`graph did not produce metadata: ${graph}`);
-        writeJson(markerPath, { fingerprint, builtAt: built.builtAt });
+        const verification = readJson(path.join(directory, 'freshness.json'));
+        if (!options.full && beforeOutput && beforeOutput === outputStamp(path.join(directory, 'metadata.json'))) {
+            job.status = 'skipped';
+            job.reason = 'unchanged';
+        }
+        if (!verification?.pendingWork && verification?.lastVerifiedDigest === fingerprint) {
+            writeJson(markerPath, { fingerprint, builtAt: built.builtAt });
+        }
     }
     else if (job.kind === 'cache') {
         const status = getFortemiCoreSyncStatus(workspace, job.graph);
@@ -331,7 +334,8 @@ async function executeJob(job, options, aliases, runtime) {
             }
         }
     }
-    job.status = 'ok';
+    if (job.status !== 'skipped')
+        job.status = 'ok';
 }
 function outputStamp(file) {
     try {
@@ -351,6 +355,7 @@ function jobKey(job, aliases) {
         ...(job.kind === 'sessions' && aliases.length > 1 ? [aliases] : [])]);
 }
 export async function refreshIndexes(options = {}, dependencies = {}) {
+    options = { ...options, workers: resolveIndexWorkers(options.workers) };
     const start = Date.now();
     const workspaces = workspacePaths(options);
     const jobs = planWorkspaceRefresh(options, workspaces);
@@ -360,6 +365,13 @@ export async function refreshIndexes(options = {}, dependencies = {}) {
         totals: { jobs: jobs.length, ok: 0, skipped: 0, deferred: 0, errors: 0, noManifest: 0, excluded: 0, wallMs: 0 },
     };
     const finish = () => {
+        for (const job of jobs) {
+            for (const receipt of job.sessionImports ?? (job.sessionImport ? [job.sessionImport] : [])) {
+                for (const warning of receipt.run.preflight?.scopeWarnings ?? []) {
+                    report.messages.push(`WARNING ${job.workspace}: ${warning.message}`);
+                }
+            }
+        }
         for (const job of jobs.filter(job => job.noManifest)) {
             const command = `aiwg sessions discover --workspace '${job.workspace.replace(/'/g, "'\\''")}'`;
             report.messages.push(`Session refresh skipped for ${job.workspace}: no authorized discovery manifest. Run \`${command}\` or configure sessions.discovery_manifests in .aiwg/aiwg.config.`);
@@ -375,6 +387,17 @@ export async function refreshIndexes(options = {}, dependencies = {}) {
                 .reduce((total, receipt) => total + (receipt.totals.excluded ?? 0), 0), 0),
             wallMs: Date.now() - start,
         };
+        report.indices = [];
+        for (const workspace of workspaces.keys()) {
+            loadWorkspaceGraphs(workspace);
+            for (const adapter of selectIndexAdapters(indexAdapterRegistry(workspace), options.only)) {
+                report.indices.push({ ...indexFreshnessSnapshot(adapter, workspace), workspace });
+            }
+        }
+        if (!jobs.length && options.only && report.indices.length && report.indices.every(index => index.status === 'unsupported')) {
+            report.status = 'deferred';
+            report.reason = 'unsupported';
+        }
         return report;
     };
     if (options.dryRun)
@@ -425,6 +448,8 @@ export async function refreshIndexes(options = {}, dependencies = {}) {
                 continue;
             }
             const jobStart = Date.now();
+            let adapter;
+            let beforeDigest;
             try {
                 const gateWorkspace = job.workspace ?? workspaces.keys().next().value ?? options.cwd ?? process.cwd();
                 const gate = await (dependencies.gate ?? refreshResourceGate)(gateWorkspace);
@@ -437,6 +462,15 @@ export async function refreshIndexes(options = {}, dependencies = {}) {
                 }
                 if (job.workspace)
                     loadWorkspaceGraphs(job.workspace);
+                const workspace = job.workspace ?? options.cwd ?? process.cwd();
+                adapter = indexAdapterRegistry(workspace).find(item => item.name === (job.kind === 'graph' ? job.graph
+                    : job.kind === 'cache' ? `caches:${job.graph}` : job.kind));
+                if (adapter?.supported && job.kind !== 'graph') {
+                    try {
+                        beforeDigest = await indexAdapterDigest(adapter, workspace);
+                    }
+                    catch { /* Owner reports unavailable dependencies. */ }
+                }
                 if (job.kind === 'cache' && jobs.some(other => other.kind === 'graph'
                     && other.workspace === job.workspace && other.graph === job.graph && other.status === 'error')) {
                     job.status = 'skipped';
@@ -461,13 +495,52 @@ export async function refreshIndexes(options = {}, dependencies = {}) {
                     await executeJob(job, options, aliases, discoverRuntime);
             }
             catch (error) {
-                job.status = 'error';
-                job.error = error instanceof Error ? error.message : String(error);
+                if (error instanceof DirectoryLockContentionError) {
+                    job.status = 'deferred';
+                    job.reason = 'lock-held';
+                    report.status = 'deferred';
+                }
+                else {
+                    job.status = 'error';
+                    job.error = error instanceof Error ? error.message : String(error);
+                }
             }
             finally {
                 job.wallMs = Date.now() - jobStart;
+                if (adapter) {
+                    const workspace = job.workspace ?? options.cwd ?? process.cwd();
+                    if (adapter.supported && job.kind !== 'graph' && job.status !== 'deferred') {
+                        try {
+                            let after;
+                            let probeError;
+                            try {
+                                after = await indexAdapterDigest(adapter, workspace);
+                            }
+                            catch (error) {
+                                probeError = String(error);
+                            }
+                            if (job.kind === 'runtime' && job.status === 'ok')
+                                beforeDigest = after;
+                            const partial = job.reason && job.reason !== 'unchanged';
+                            job.freshness = recordIndexVerification(adapter, workspace, { before: beforeDigest, after,
+                                error: job.error ?? probeError, pendingWork: partial ? 1 : 0, wallMs: job.wallMs });
+                        }
+                        catch (error) {
+                            job.freshness = { ...indexFreshnessSnapshot(adapter, workspace), status: 'degraded',
+                                pendingWork: 1, lastError: String(error) };
+                        }
+                    }
+                    else
+                        job.freshness = indexFreshnessSnapshot(adapter, workspace);
+                    if (job.freshness.pendingWork && !job.error && job.status !== 'deferred' && job.kind === 'graph'
+                        && job.reason !== 'scan directories missing') {
+                        job.status = 'deferred';
+                        job.reason = 'inputs changed during build';
+                        report.status = 'deferred';
+                    }
+                }
             }
-            if (job.status !== 'error' && job.reason !== 'graph failed'
+            if (job.status !== 'error' && job.status !== 'deferred' && job.reason !== 'graph failed'
                 && job.reason !== 'no authorized discovery manifest')
                 checkpoint.completed.push(key);
             writeJson(checkpointPath, checkpoint);
@@ -507,7 +580,7 @@ export async function runIndexRefresh(args, cwd = process.cwd(), signal) {
                 options.dryRun = true;
             else if (flag === '--json')
                 json = true;
-            else if (['--workspace', '--root', '--only', '--lock-wait-ms', '--max-record-bytes', '--max-source-bytes', '--exclude'].includes(flag)) {
+            else if (['--workspace', '--root', '--only', '--lock-wait-ms', '--max-record-bytes', '--max-source-bytes', '--exclude', '--index-workers'].includes(flag)) {
                 const value = args[++i];
                 if (!value || value.startsWith('--'))
                     throw new Error(`${flag} requires a value`);
@@ -519,13 +592,11 @@ export async function runIndexRefresh(args, cwd = process.cwd(), signal) {
                     options.maxRecordBytes = value;
                 else if (flag === '--max-source-bytes')
                     options.maxSourceBytes = value;
+                else if (flag === '--index-workers')
+                    options.workers = resolveIndexWorkers(value);
                 else if (flag === '--exclude')
                     (options.exclude ??= []).push(value);
                 else if (flag === '--only') {
-                    if (value !== 'graphs' && value !== 'sessions' && value !== 'caches'
-                        && value !== 'runtime' && value !== 'models' && value !== 'issues') {
-                        throw new Error('--only must be graphs, sessions, caches, runtime, models, or issues');
-                    }
                     options.only = value;
                 }
                 else {
@@ -537,6 +608,7 @@ export async function runIndexRefresh(args, cwd = process.cwd(), signal) {
             else
                 throw new Error(`unknown refresh option: ${flag}`);
         }
+        options.workers = resolveIndexWorkers(options.workers);
         resolveImportLimits(undefined, { maxRecordBytes: options.maxRecordBytes, maxSourceBytes: options.maxSourceBytes });
         resolveImportExclusions(undefined, options.exclude);
         const report = await refreshIndexes(options);
@@ -547,6 +619,8 @@ export async function runIndexRefresh(args, cwd = process.cwd(), signal) {
             for (const job of report.jobs)
                 console.log(`  ${job.status}: ${job.kind} ${job.scope === 'host' ? '[host]' : job.workspace}${job.graph ? ` [${job.graph}]` : ''}${job.error || job.reason ? `: ${job.error ?? job.reason}` : ''}`);
             for (const job of report.jobs) {
+                for (const diagnostic of job.diagnostics ?? [])
+                    console.log(`    preparation: ${diagnostic}`);
                 for (const receipt of job.sessionImports ?? (job.sessionImport ? [job.sessionImport] : [])) {
                     for (const source of receipt.run.sources) {
                         if (source.status === 'excluded')