@aiwg/cli 2026.10.4 → 2026.10.5

package/dist/src/artifacts/cli.js

@@ -20,6 +20,7 @@ import path from 'node:path';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { GRAPH_CONFIGS, OPERATIONAL_DISCOVERY_TYPES, OPERATIONAL_SHOW_TYPES, isOperationalShowType, loadUserGraphConfigs, loadGlobalGraphConfigs, orderedGraphEntries, } from './types.js';
+import { resolveIndexWorkers } from './index-preparation.js';
 import { SUPPORTED_VIEWS } from './corpus-views/renderers.js';
 import { parseResourceSelector, readVerifiedRegularFile, } from '../resources/web-release.js';
 import { findPackageRoot } from '../cli/find-package-root.js';
@@ -332,6 +333,7 @@ export function printIndexUsage() {
     console.log('  Session import defaults: 67108864 bytes per record, 1073741824 bytes (1 GiB) per source; source 0 is unlimited.');
     console.log('  --exclude <id-or-glob> (repeatable): skip session IDs or absolute path globs; adds to sessions.import.exclude and AIWG_SESSIONS_IMPORT_EXCLUDE (comma-separated).');
     console.log('  Import limits: CLI flag > AIWG_SESSIONS_IMPORT_MAX_RECORD_BYTES / AIWG_SESSIONS_IMPORT_MAX_SOURCE_BYTES > workspace config > default.');
+    console.log('  build/refresh --index-workers <n>: preparation processes (0 = serial); flag > AIWG_INDEX_WORKERS > automatic CPU/memory limits.');
     console.log('  sync [--backend fortemi-core] [--graph <name> | --all] [--repo <name>]');
     console.log('       [--privacy private|sanitized|public] [--generated-at <iso>] [--json]');
     console.log('  --graph <name>  Target a specific graph (framework, project, codebase, source, user, or user-defined)');
@@ -503,6 +505,7 @@ async function handleBuild(args) {
         console.log('Usage: aiwg index build [options]');
         console.log('');
         console.log('Options:');
+        console.log('  --index-workers <n> Preparation processes (0 = serial); overrides AIWG_INDEX_WORKERS');
         console.log('  --force          Full rebuild (ignore checksums, re-index everything)');
         console.log('  --verbose        Show detailed progress during indexing');
         console.log('  --all            Build all known graphs (including user-defined)');
@@ -530,6 +533,15 @@ async function handleBuild(args) {
         console.log('  aiwg index sync --all');
         return;
     }
+    let workers;
+    try {
+        workers = resolveIndexWorkers(parseFlagValue(args, '--index-workers', 'Error: --index-workers requires a value'));
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+        return;
+    }
     // Dynamic import to keep the CLI router lightweight
     const { buildIndex } = await import('./index-builder.js');
     const cwd = process.cwd();
@@ -554,7 +566,7 @@ async function handleBuild(args) {
         // --graph X: build the JSON graph if X is one; otherwise X may be a
         // research-corpus markdown view, rendered below.
         if (graph in GRAPH_CONFIGS) {
-            await buildIndex(cwd, { force, verbose, scope, includeIgnored, graph, explicit: true });
+            await buildIndex(cwd, { force, verbose, scope, includeIgnored, workers, graph, explicit: true });
             jsonBuilt = true;
             builtGraphs.add(graph);
         }
@@ -562,7 +574,7 @@ async function handleBuild(args) {
     else if (all) {
         // Build all known graphs — user asked for everything, but don't hard-error on missing dirs
         for (const [name] of orderedGraphEntries(Object.entries(GRAPH_CONFIGS))) {
-            await buildIndex(cwd, { force, verbose, includeIgnored, graph: name, explicit: false });
+            await buildIndex(cwd, { force, verbose, includeIgnored, workers, graph: name, explicit: false });
             builtGraphs.add(name);
         }
         jsonBuilt = true;
@@ -571,7 +583,7 @@ async function handleBuild(args) {
         // Default: build graphs with defaultBuild=true; skip gracefully if their dirs don't exist
         for (const [name, config] of orderedGraphEntries(Object.entries(GRAPH_CONFIGS))) {
             if (config.defaultBuild) {
-                await buildIndex(cwd, { force, verbose, includeIgnored, scope: name === Object.keys(GRAPH_CONFIGS)[0] ? scope : undefined, graph: name, explicit: false });
+                await buildIndex(cwd, { force, verbose, includeIgnored, workers, scope: name === Object.keys(GRAPH_CONFIGS)[0] ? scope : undefined, graph: name, explicit: false });
                 builtGraphs.add(name);
             }
         }

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

@@ -24,7 +24,7 @@ import { FRAMEWORK_RELATIONS_REVISION } from './framework-source-digest.js';
 import { normalizeOperationalState } from './operational-state.js';
 import { DEFAULT_PROJECT_AIWG_DIR, resolveProjectAiwgDir, } from '../config/project-artifacts.js';
 import { normalizeStateTransferProjection } from './state-transfer.js';
-import { runIndexPreparation } from './index-preparation.js';
+import { resolveIndexWorkers, runIndexPreparation } from './index-preparation.js';
 import { collectGraphIndexFiles, findArtifactFiles, indexPathFor } from './index-files.js';
 function absoluteEntryPath(cwd, entryPath, graph) {
     if ((!graph || graph === 'project') && entryPath.startsWith(`${DEFAULT_PROJECT_AIWG_DIR}/`)) {
@@ -911,6 +911,7 @@ export function prepareIndexArtifact(job) {
 }
 export async function buildIndex(cwd, options = {}) {
     const { force = false, verbose = false, scope, includeIgnored = false, outputDir, graph, explicit = true } = options;
+    const workers = resolveIndexWorkers(options.workers);
     const startTime = Date.now();
     const log = options.quiet ? (..._args) => { } : console.log;
     // Ensure user-defined graphs are loaded
@@ -1119,7 +1120,7 @@ export async function buildIndex(cwd, options = {}) {
             jobs.push({ fullPath, relativePath, mtimeMs: stat.mtimeMs, birthtimeMs: stat.birthtimeMs, sizeBytes: stat.size,
                 ...(!force && existingEntries[relativePath] ? { existingChecksum: existingEntries[relativePath].checksum } : {}) });
         }
-    const preparation = await runIndexPreparation(jobs, prepareIndexArtifact, import.meta.url, options.workers);
+    const preparation = await runIndexPreparation(jobs, prepareIndexArtifact, import.meta.url, workers, options.onDiagnostic ?? (message => console.warn(`Index preparation: ${message}`)));
     const preparedArtifacts = new Map(jobs.map((job, index) => [job.fullPath, preparation.results[index]]));
     for (const fullPath of files) {
         const relativePath = indexPathFor(cwd, fullPath, graph);

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-refresh.js

@@ -6,6 +6,7 @@ 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 { resolveIndexWorkers } from './index-preparation.js';
 import { collectGraphIndexFiles } from './index-files.js';
 import { collectIndexStatus } from './index-status.js';
 import { getFortemiCoreSyncStatus, syncFortemiCoreIndex } from './fortemi-core-sync.js';
@@ -258,7 +259,8 @@ async function executeJob(job, options, aliases, runtime) {
             return;
         }
         const { buildIndex } = await import('./index-builder.js');
-        await buildIndex(workspace, { graph, force: Boolean(options.full), explicit: false, quiet: true });
+        await buildIndex(workspace, { graph, force: Boolean(options.full), explicit: false, quiet: true, workers: options.workers,
+            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}`);
@@ -351,6 +353,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 +363,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.`);
@@ -507,7 +517,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,6 +529,8 @@ 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') {
@@ -537,6 +549,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 +560,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')

package/dist/src/artifacts/index-worker.mjs

@@ -1,9 +1,11 @@
 /** Artifact worker uses the exact caller module: source never silently loads stale dist. */
-import { parentPort, workerData } from 'node:worker_threads';
-const module = workerData.moduleUrl.endsWith('.ts')
-  ? await (await import('tsx/esm/api')).tsImport(workerData.moduleUrl, import.meta.url)
-  : await import(workerData.moduleUrl);
-parentPort.on('message', ({ index, job }) => {
-  try { parentPort.postMessage({ index, result: module.prepareIndexArtifact(job) }); }
-  catch (error) { parentPort.postMessage({ index, error: `${job.relativePath}: ${error.message}` }); }
+const moduleUrl = process.argv[2];
+const module = moduleUrl.endsWith('.ts')
+  ? await (await import('tsx/esm/api')).tsImport(moduleUrl, import.meta.url)
+  : await import(moduleUrl);
+process.on('message', ({ index, job }) => {
+  try { process.send({ index, result: module.prepareIndexArtifact(job) }); }
+  catch (error) { process.send({ index, error: `${job.relativePath}: ${error.message}` }); }
 });
+// The parent may itself be interrupted; do not leave orphaned preparation processes.
+process.on('disconnect', () => process.exit(0));

package/dist/src/cli/handlers/sessions.js

@@ -2,6 +2,7 @@ import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, renameSync
 import { randomUUID } from 'node:crypto';
 import { basename, dirname, isAbsolute, join, resolve, } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { providerScopeWarnings } from '../../sessions/coverage-preflight.js';
 import { CLAUDE_ADAPTER_VERSION, ClaudeSessionAdapter, CODEX_ADAPTER_VERSION, CodexSessionAdapter, COPILOT_ADAPTER_VERSION, CopilotSessionAdapter, CURSOR_ADAPTER_VERSION, CursorSessionAdapter, FACTORY_ADAPTER_VERSION, FactorySessionAdapter, HERMES_ADAPTER_VERSION, HermesSessionAdapter, OPENCODE_ADAPTER_VERSION, OpenCodeSessionAdapter, OPENCLAW_ADAPTER_VERSION, OpenClawSessionAdapter, OPENHUMAN_ADAPTER_VERSION, OpenHumanSessionAdapter, GROKBOT_ADAPTER_VERSION, GROKBOT_NATIVE_REPLICA_LOCATOR_CLASS, GrokbotSessionAdapter, GROK_BUILD_ADAPTER_VERSION, GROK_BUILD_CLI_EXPORT_LOCATOR_CLASS, GrokBuildSessionAdapter, grokBuildList, grokBuildSearch, grokBuildExport, grokHeadlessSessionIdFromFile, MUSE_ADAPTER_VERSION, MuseSessionAdapter, PI_ADAPTER_VERSION, PiSessionAdapter, DEEPSEEK_HARNESS_ADAPTER_VERSION, DeepSeekHarnessSessionAdapter, OmpSessionAdapter, OMP_ADAPTER_VERSION, WARP_ADAPTER_VERSION, WarpSessionAdapter, DEVIN_DESKTOP_ADAPTER_VERSION, DevinDesktopSessionAdapter, CandidateExtractionService, GENERIC_ADAPTER_VERSION, GenericSessionInterchangeAdapter, IncrementalSessionImporter, ImportLeaseContentionError, FilesystemMemoryDestination, FilesystemPromotionDispositionCoordinator, MemoryPromotionGateway, SESSION_CONTRACT_VERSION, SessionContractError, SessionRepository, SessionSourceSchema, StructuralCandidateExtractor, resolveMemoryConsumerManifest, assertSessionProviderId, acquireImportLease, defaultDiscoveryManifestPath, discoverWorkspaceHistories, createSessionAdapterRegistry, coveragePreflight, expectedSessionProviders, deriveSessionTimeline, importDiscoveryManifest, previewDiscoveryImport, publicDiscoveryManifest, readDiscoveryManifest, redactSourceLocator, sha256, parseTimelineGap, writeDiscoveryManifest, buildSessionExportPlan, reverifySessionExportPlan, buildSessionAiwgFortemiIndexExport, recoverAiwgFortemiIndexFromFullV1Shard, embedAttachmentsInFullV1Shard, recoverEmbeddedAttachments, SESSION_EXPORT_PLAN_SCHEMA_VERSION, } from '../../sessions/index.js';
 import { resolveImportExclusions } from '../../sessions/import-exclusions.js';
 import { resolveImportLimits } from '../../sessions/import-limits.js';
@@ -58,7 +59,7 @@ Commands:
   audit --workspace <id>          Read content-free mutation events
   analytics <view> --workspace <id>  Summary, tool-calls, escalations, or HITL
   forensics <view> --workspace <id>  Authorized timeline, indicators, or evidence
-  doctor                          Check catalog availability and integrity
+  doctor                          Check catalog integrity and configured provider scope
 
 Options:
   --json          Emit the versioned JSON contract
@@ -70,7 +71,8 @@ Options:
                    Catalog defaults to <project-or-cwd>/.aiwg/sessions/catalog.sqlite
                    Imports for other workspaces stay in the selected catalog;
                    use --db to read that catalog from another directory
-  --expected-providers <ids>  Comma-separated authorized scope, independent of runtime inventory
+  --expected-providers <ids>  Explicit scope for this invocation; refresh re-reads workspace config
+  --carry-forward <catalog>  Rebuild from sources plus re-redacted stored history (import-discovered)
   --manifest <path>  Override the discovery manifest path
   --provider-home <path>  Override the provider home root (testing/portable homes)
   --codex-root <path>  Authorize a shared Codex sessions/export root (repeatable)
@@ -725,12 +727,22 @@ async function executeCommand(ctx, args) {
                     providerLogsModified: false,
                 });
             }
-            case 'doctor':
+            case 'doctor': {
+                const workspacePath = resolve(ctx.cwd, args.values.get('--workspace') ?? ctx.cwd);
+                const workspace = existsSync(workspacePath) ? realpathSync(workspacePath) : workspacePath;
+                const config = await readAiwgConfig(workspace);
+                const manifestPath = resolve(ctx.cwd, args.values.get('--manifest') ?? defaultDiscoveryManifestPath(workspace));
+                const preflight = existsSync(manifestPath)
+                    ? (await readDiscoveryManifest(manifestPath)).preflight
+                    : repository.getCoverage(workspace).preflight;
+                const warnings = providerScopeWarnings(config?.providers ?? [], preflight?.expectedProviders ?? [], preflight?.scopeWarnings);
                 return ok(command, {
                     database: redactSourceLocator(databasePath(ctx, args)),
                     health: repository.doctor(),
+                    warnings,
                     jsonContractVersion: JSON_CONTRACT_VERSION,
                 });
+            }
             default:
                 throw new CliError('UNKNOWN_COMMAND', `unknown sessions command: ${command}`, EXIT.usage);
         }
@@ -1283,6 +1295,7 @@ async function discoverWorkspace(ctx, args) {
         ],
     });
     const data = {
+        warnings: manifest.preflight?.scopeWarnings ?? [],
         manifest: publicDiscoveryManifest(manifest),
         manifestPath: redactSourceLocator(manifestPath),
         exactManifestRequiredForImport: true,
@@ -1304,7 +1317,20 @@ async function importDiscovered(ctx, args) {
     if (manifest.workspaceId !== canonicalWorkspace) {
         throw new CliError('MANIFEST_WORKSPACE_MISMATCH', 'discovery manifest does not belong to the explicitly authorized workspace', EXIT.contract);
     }
+    const carryPath = args.values.has('--carry-forward')
+        ? resolve(ctx.cwd, args.values.get('--carry-forward')) : undefined;
+    if (carryPath) {
+        const sourceStat = statSync(carryPath);
+        const target = databasePath(ctx, args);
+        if (existsSync(target)) {
+            const targetStat = statSync(target);
+            if (sourceStat.dev === targetStat.dev && sourceStat.ino === targetStat.ino) {
+                throw new CliError('INVALID_ARGUMENT', 'carry-forward requires a separate destination catalog', EXIT.usage);
+            }
+        }
+    }
     const expected = requestedProviders(args);
+    const warnings = providerScopeWarnings(config?.providers ?? [], manifest.preflight?.expectedProviders ?? [], manifest.preflight?.scopeWarnings);
     if (expected && JSON.stringify(expected) !== JSON.stringify(manifest.preflight?.expectedProviders)) {
         throw new SessionContractError('INVALID_ARGUMENT', 'expected provider scope differs from the saved manifest; rediscover with --expected-providers');
     }
@@ -1320,22 +1346,27 @@ async function importDiscovered(ctx, args) {
             // A preview can still describe the exact manifest before a catalog exists.
         }
         return preview('import-discovered', {
+            warnings,
             manifest: publicDiscoveryManifest(manifest),
             receipt: previewDiscoveryImport(manifest, existing, new Date(), exclude),
             confirmationRequired: !isDryRun(ctx, args),
             wouldPersist: false,
+            ...(carryPath ? { carryForward: redactSourceLocator(carryPath) } : {}),
         });
     }
     const lease = await acquireImportLease(databasePath(ctx, args), sha256(['discovered-import', manifest.manifestId, manifest.workspaceId].join('\0')), {
         waitMs: boundedInteger(args.values.get('--lock-wait-ms'), 5_000, 0, 300_000, '--lock-wait-ms'),
     });
     try {
-        const repository = openRepository(ctx, args);
+        const previous = carryPath ? new SessionRepository(carryPath, { readonly: true }) : undefined;
+        let repository;
         try {
+            repository = openRepository(ctx, args);
             const interruptedRuns = repository.interruptRunningBatchImports();
             const receipt = await importDiscoveryManifest({
                 manifest,
                 repository,
+                carryForward: previous,
                 limits,
                 exclude,
                 signal: ctx.signal,
@@ -1343,6 +1374,7 @@ async function importDiscovered(ctx, args) {
             });
             receipt.interruptedRuns = interruptedRuns;
             return ok('import-discovered', {
+                warnings,
                 manifestId: manifest.manifestId,
                 receipt,
                 resumable: receipt.run.status !== 'complete',
@@ -1354,7 +1386,8 @@ async function importDiscovered(ctx, args) {
             });
         }
         finally {
-            repository.close();
+            repository?.close();
+            previous?.close();
         }
     }
     finally {
@@ -1710,7 +1743,7 @@ function parseArgs(argv) {
         '--entity', '--sensitivity', '--extraction-state', '--page-size', '--max-documents',
         '--state', '--reviewer', '--reason', '--policy-version', '--min-confidence',
         '--consumer', '--actor-class', '--reason-code', '--dependent-action', '--basis',
-        '--manifest', '--provider-home', '--codex-root', '--omp-root', '--muse-root', '--dsh-root', '--grokbot-root', '--lock-wait-ms', '--min-coverage', '--gap',
+        '--carry-forward', '--manifest', '--provider-home', '--codex-root', '--omp-root', '--muse-root', '--dsh-root', '--grokbot-root', '--lock-wait-ms', '--min-coverage', '--gap',
         '--inactivity-threshold', '--expected-providers', '--exclude', '--max-record-bytes', '--max-source-bytes',
         '--control-events',
         '--session', '--status', '--actor', '--group-by',

package/dist/src/sessions/adapters/codex.js

@@ -202,16 +202,7 @@ function normalizeRolloutRecord(state, envelope, line, sourceArtifactSessionId)
             firstMetadata = true;
             state.metadataId = declaredId;
             state.nativeSessionId = declaredId;
-            const spawn = asObject(asObject(asObject(payload.source).subagent).thread_spawn);
-            const lineage = Object.fromEntries(Object.entries({
-                forkedFromId: stringValue(payload.forked_from_id),
-                parentThreadId: stringValue(spawn.parent_thread_id),
-                depth: nonnegativeInteger(spawn.depth ?? payload.depth),
-                agentPath: stringValue(payload.agent_path ?? spawn.agent_path),
-                agentNickname: stringValue(payload.agent_nickname ?? spawn.agent_nickname),
-                subagentHistoryStartOrdinal: nonnegativeInteger(payload.subagent_history_start_ordinal),
-                threadSource: stringValue(payload.thread_source),
-            }).filter(([, value]) => value !== undefined));
+            const lineage = rolloutLineage(payload);
             if (Object.keys(lineage).length > 0)
                 state.lineage = lineage;
         }
@@ -243,6 +234,28 @@ function normalizeRolloutRecord(state, envelope, line, sourceArtifactSessionId)
     }
     return record;
 }
+/** Apply the rollout identity rule to legacy catalog rows, including split parent replay. */
+export function recoverCodexRolloutIdentity(events) {
+    const metadata = [...events].sort((a, b) => a.sequence - b.sequence || a.eventId.localeCompare(b.eventId))
+        .find(event => asObject(event.extensions['native.codex']).rolloutType === 'session_meta');
+    if (!metadata?.nativeId)
+        return undefined; // App Server sources can contain multiple independent threads.
+    const native = asObject(metadata.extensions['native.codex']);
+    return { nativeSessionId: metadata.nativeId,
+        lineage: { ...rolloutLineage(asObject(native.unknownFields)), ...asObject(native.lineage) } };
+}
+function rolloutLineage(payload) {
+    const spawn = asObject(asObject(asObject(payload.source).subagent).thread_spawn);
+    return Object.fromEntries(Object.entries({
+        forkedFromId: stringValue(payload.forked_from_id),
+        parentThreadId: stringValue(spawn.parent_thread_id),
+        depth: nonnegativeInteger(spawn.depth ?? payload.depth),
+        agentPath: stringValue(payload.agent_path ?? spawn.agent_path),
+        agentNickname: stringValue(payload.agent_nickname ?? spawn.agent_nickname),
+        subagentHistoryStartOrdinal: nonnegativeInteger(payload.subagent_history_start_ordinal),
+        threadSource: stringValue(payload.thread_source),
+    }).filter(([, value]) => value !== undefined));
+}
 function nonnegativeInteger(value) {
     return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
         ? value : undefined;

package/dist/src/sessions/batch-contracts.js

@@ -24,7 +24,7 @@ export function coverageFromBatchRun(run, now = new Date(), staleAfterMs = 24 *
     const unresolvedProviders = preflight?.unresolvedProviders
         ?? [...new Set([...unavailable, ...exportRequired, ...notChecked])].sort();
     const acquisitionIncomplete = rejected > 0 || pending > 0 || skipped > 0
-        || (preflight?.expectedProviderBasis === 'explicit' && unresolvedProviders.length > 0);
+        || (preflight && ['explicit', 'workspace-config'].includes(preflight.expectedProviderBasis) && unresolvedProviders.length > 0);
     const incomplete = acquisitionIncomplete || !preflight || preflight.status !== 'complete'
         || unavailable.length > 0 || accepted + duplicated + previouslyCommitted + excluded === 0
         || exportRequired.length > 0 || notChecked.length > 0;

package/dist/src/sessions/batch-import.js

@@ -1,13 +1,21 @@
-import { stat } from 'node:fs/promises';
+import { mkdtemp, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { createSessionAdapterRegistry } from './adapter-registry.js';
 import { coveragePreflight, sessionRuntimeIdentity } from './coverage-preflight.js';
-import { SESSION_CONTRACT_VERSION, SessionContractError, schemaIssueDetail, SessionSourceSchema, sha256, } from './contracts.js';
+import { SESSION_CONTRACT_VERSION, SessionContractError, schemaIssueDetail, SessionSourceSchema, sha256, stableSessionId, stableEventId, } from './contracts.js';
 import { BATCH_IMPORT_VERSION, coverageFromBatchRun, } from './batch-contracts.js';
 import { IncrementalSessionImporter, SessionImportFailure } from './importer.js';
 import { matchImportExclusion, resolveImportExclusions } from './import-exclusions.js';
 import { resolveImportLimits } from './import-limits.js';
 import { fingerprintSourceFile } from './readers.js';
+import { SessionRepository } from './repository.js';
+import { redactSessionValue, sanitizeSessionEvent } from './policy.js';
+import { deriveSessionIntent } from './origin.js';
+import { recoverCodexRolloutIdentity } from './adapters/codex.js';
 export async function importDiscoveryManifest(options) {
+    if (options.carryForward)
+        return rebuildFromCatalog(options);
     const exclusions = resolveImportExclusions(undefined, options.exclude);
     const limits = { ...resolveImportLimits(undefined, {
             maxRecordBytes: options.limits?.maxRecordBytes, maxSourceBytes: options.limits?.maxTotalBytes,
@@ -25,6 +33,8 @@ export async function importDiscoveryManifest(options) {
     }
     run.schemaVersion = BATCH_IMPORT_VERSION;
     run.preflight = coveragePreflight({
+        configuredProviders: options.manifest.preflight?.configuredProviders,
+        scopeWarnings: options.manifest.preflight?.scopeWarnings,
         expectedProviders: options.manifest.preflight?.expectedProviders,
         expectedProviderBasis: options.manifest.preflight?.expectedProviderBasis ?? 'legacy',
         runtime: options.runtime ?? sessionRuntimeIdentity(),
@@ -160,6 +170,8 @@ export function previewDiscoveryImport(manifest, existing, now = new Date(), exc
             return disposition;
         }),
         preflight: coveragePreflight({
+            configuredProviders: manifest.preflight?.configuredProviders,
+            scopeWarnings: manifest.preflight?.scopeWarnings,
             expectedProviders: manifest.preflight?.expectedProviders,
             expectedProviderBasis: manifest.preflight?.expectedProviderBasis ?? 'legacy',
             reports: manifest.providers,
@@ -202,6 +214,7 @@ function receiptFor(run, now) {
         run,
         coverage,
         interruptedRuns: [],
+        ...(run.carryForward ? { carryForward: run.carryForward } : {}),
         totals: {
             discovered: coverage.sources.discovered,
             accepted: coverage.sources.accepted,
@@ -304,4 +317,191 @@ function isAccepted(status) {
         || status === 'duplicate'
         || status === 'previously-committed';
 }
+/** Reuse source import and normalized repository gates, without copying FTS/analytics. */
+async function rebuildFromCatalog(options) {
+    const previous = options.carryForward;
+    if (previous === options.repository) {
+        throw new SessionContractError('INVALID_ARGUMENT', 'carry-forward requires a separate destination catalog');
+    }
+    const workspaceId = options.manifest.workspaceId;
+    const exclusions = resolveImportExclusions(undefined, options.exclude);
+    const byProvider = {};
+    const counts = (provider) => byProvider[provider] ??= {
+        reimported: 0, carried: 0, droppedAsDuplicate: 0, excluded: 0,
+    };
+    const oldSessions = catalogSessions(previous, workspaceId);
+    const available = [];
+    const present = new Set();
+    const excludedSources = new Set();
+    for (const source of options.manifest.sources) {
+        if (matchImportExclusion(source, exclusions) ?? source.exclusion) {
+            excludedSources.add(source.sourceId);
+            continue;
+        }
+        let details;
+        try {
+            details = await stat(source.locator);
+        }
+        catch (error) {
+            if (['ENOENT', 'ENOTDIR'].includes(error.code ?? ''))
+                continue;
+            throw error;
+        }
+        // Refresh the snapshot, but retain the explicitly saved authorization and source identity.
+        const fingerprint = await fingerprintSourceFile({ selectedPath: source.locator,
+            allowedRoots: [source.authorizedRoot] });
+        available.push({ ...source, sizeBytes: details.size, modifiedAt: details.mtime.toISOString(),
+            digest: fingerprint.digest });
+        present.add(source.sourceId);
+    }
+    const manifest = { ...options.manifest, sources: available,
+        manifestId: sha256(JSON.stringify(['carry-forward-v1', options.manifest.manifestId, available])) };
+    const stagingDirectory = await mkdtemp(join(tmpdir(), 'aiwg-session-rebuild-'));
+    let staged;
+    try {
+        staged = new SessionRepository(join(stagingDirectory, 'staging.sqlite'));
+        const receipt = await importDiscoveryManifest({ ...options, manifest, repository: staged,
+            carryForward: undefined, fault: undefined });
+        const identities = new Set();
+        const destinationCodex = new Map(catalogSessions(options.repository, workspaceId)
+            .filter(session => session.provider === 'codex').map(session => [session.nativeSessionId, session.sourceId]));
+        const transfer = (repository, sessions, category) => {
+            // A legacy Codex rollout may have split replayed parent events into phantom rows.
+            // Recover the first session_meta ID for the whole source before grouping events.
+            const sourceGroups = new Map();
+            for (const session of sessions) {
+                const group = sourceGroups.get(session.sourceId) ?? [];
+                group.push(session);
+                sourceGroups.set(session.sourceId, group);
+            }
+            for (const [sourceId, group] of sourceGroups) {
+                if (options.signal?.aborted)
+                    throw new SessionContractError('IMPORT_INTERRUPTED', 'catalog rebuild interrupted');
+                const source = repository.getSource(sourceId, workspaceId);
+                if (!source)
+                    throw new SessionContractError('IMPORT_CONFLICT', 'catalog session has no authorized source');
+                const allEvents = group.flatMap(session => repository.listEvents(session.sessionId, workspaceId))
+                    .sort((a, b) => a.sequence - b.sequence || a.eventId.localeCompare(b.eventId));
+                const rollout = source.provider === 'codex' ? recoverCodexRolloutIdentity(allEvents) : undefined;
+                const childId = rollout?.nativeSessionId;
+                // Prefer the child's aggregate when the legacy source also has phantom parent aggregates.
+                group.sort((a, b) => Number(b.nativeSessionId === childId) - Number(a.nativeSessionId === childId));
+                const canonical = new Map();
+                for (const session of group) {
+                    const nativeId = childId ?? session.nativeSessionId;
+                    const locator = options.manifest.sources.find(item => item.sourceId === sourceId)?.locator
+                        ?? source.redactedLocator;
+                    if (excludedSources.has(sourceId) || matchImportExclusion({ provider: session.provider,
+                        locator, locatorClass: source.locatorClass, nativeSessionId: nativeId }, exclusions)) {
+                        counts(session.provider).excluded++;
+                        continue;
+                    }
+                    const key = session.provider === 'codex' ? `${session.provider}\0${nativeId}` : session.sessionId;
+                    if (identities.has(key)) {
+                        counts(session.provider).droppedAsDuplicate++;
+                        continue;
+                    }
+                    const existing = canonical.get(key);
+                    if (existing) {
+                        counts(session.provider).droppedAsDuplicate++;
+                        existing.events.push(...repository.listEvents(session.sessionId, workspaceId));
+                    }
+                    else
+                        canonical.set(key, { session: { ...session, nativeSessionId: nativeId },
+                            events: repository.listEvents(session.sessionId, workspaceId) });
+                }
+                for (const [key, entry] of canonical) {
+                    if (source.provider === 'codex' && destinationCodex.has(entry.session.nativeSessionId)
+                        && destinationCodex.get(entry.session.nativeSessionId) !== sourceId) {
+                        throw new SessionContractError('IMPORT_CONFLICT', 'destination has a different source for this Codex identity; select a fresh catalog');
+                    }
+                    const session = redactSessionValue({ ...entry.session,
+                        sessionId: stableSessionId(source.provider, sourceId, entry.session.nativeSessionId),
+                    }).value;
+                    // Hash only sanitized content; receipts and IDs must never retain old plaintext.
+                    const sanitized = entry.events.map(sanitizeSessionEvent);
+                    const runId = sha256(JSON.stringify(['catalog-carry-v1', session.sessionId, sanitized]));
+                    const events = sanitized.map(event => {
+                        const digest = event.digest;
+                        return { ...event, sessionId: session.sessionId, importRunId: runId, digest,
+                            eventId: stableEventId(source.provider, sourceId, {
+                                nativeSessionId: session.nativeSessionId, nativeEventId: event.nativeId ?? event.eventId,
+                                sequence: event.sequence, kind: event.kind, text: event.searchableText,
+                                rawReference: event.rawReference,
+                            }, digest) };
+                    });
+                    if (rollout && Object.keys(rollout.lineage).length > 0) {
+                        session.extensions['native.codex'] = { lineage: rollout.lineage };
+                    }
+                    session.intent = deriveSessionIntent(events);
+                    const checkpoint = repository.getCheckpoint(sourceId, source.adapterVersion)
+                        ?? { cursor: '', recordsRead: events.length, bytesRead: Buffer.byteLength(JSON.stringify(events)) };
+                    options.repository.applyImport({ source, sessions: [session], events,
+                        run: { contractVersion: SESSION_CONTRACT_VERSION, importRunId: runId, sourceId,
+                            parserVersion: source.adapterVersion, policyVersion: '1.0.0',
+                            sourceSchemaVersion: source.sourceSchemaVersion, consistency: source.consistency,
+                            status: 'running', checkpoint, startedAt: (options.now?.() ?? new Date()).toISOString(),
+                            completedAt: null, errorCode: null } }, checkpoint);
+                    for (const old of group.filter(item => (childId ?? item.nativeSessionId) === entry.session.nativeSessionId)) {
+                        for (const tag of repository.listTags(old.sessionId, workspaceId)) {
+                            options.repository.tagSession(session.sessionId, tag, workspaceId);
+                        }
+                    }
+                    identities.add(key);
+                    counts(source.provider)[category]++;
+                }
+            }
+        };
+        const reimported = catalogSessions(staged, workspaceId);
+        transfer(staged, reimported, 'reimported');
+        for (const sourceId of present) {
+            const old = oldSessions.filter(session => session.sourceId === sourceId && session.provider === 'codex');
+            const imported = reimported.filter(session => session.sourceId === sourceId);
+            // Account for phantom rows eliminated by current source parsing, separately from copied duplicates.
+            if (imported.length > 0 && old.length > imported.length) {
+                counts('codex').droppedAsDuplicate += old.length - imported.length;
+            }
+        }
+        transfer(previous, oldSessions.filter(session => !present.has(session.sourceId)), 'carried');
+        options.repository.reindex(workspaceId);
+        const finalSessions = catalogSessions(options.repository, workspaceId);
+        const sourceIds = new Set([...receipt.run.sources.map(item => item.sourceId),
+            ...oldSessions.map(session => session.sourceId)]);
+        for (const sourceId of sourceIds) {
+            const accepted = finalSessions.filter(session => session.sourceId === sourceId);
+            let disposition = receipt.run.sources.find(item => item.sourceId === sourceId);
+            if (!disposition) {
+                const old = oldSessions.find(session => session.sourceId === sourceId);
+                const excluded = excludedSources.has(sourceId) || matchImportExclusion({
+                    provider: old.provider, nativeSessionId: old.nativeSessionId,
+                    locator: previous.getSource(sourceId, workspaceId)?.redactedLocator ?? '', locatorClass: 'catalog',
+                }, exclusions);
+                disposition = { sourceId, provider: old.provider,
+                    status: excluded ? 'excluded' : accepted.length > 0 ? 'committed' : 'duplicate',
+                    attempts: 1, sessionsAccepted: 0, eventsAccepted: 0,
+                    errorCode: null, diagnostic: null, updatedAt: receipt.run.updatedAt };
+                receipt.run.sources.push(disposition);
+            }
+            disposition.sessionsAccepted = accepted.length;
+            disposition.eventsAccepted = accepted.reduce((sum, session) => sum + options.repository.listEvents(session.sessionId, workspaceId).length, 0);
+        }
+        receipt.run.carryForward = { byProvider };
+        options.repository.saveBatchImportRun(receipt.run);
+        return redactSessionValue(receiptFor(receipt.run, options.now?.() ?? new Date())).value;
+    }
+    finally {
+        staged?.close();
+        await rm(stagingDirectory, { recursive: true, force: true });
+    }
+}
+function catalogSessions(repository, workspaceId) {
+    const sessions = [];
+    let cursor;
+    do {
+        const page = repository.listSessions({ workspaceId, limit: 500, cursor });
+        sessions.push(...page.items);
+        cursor = page.nextCursor ?? undefined;
+    } while (cursor);
+    return sessions;
+}
 //# sourceMappingURL=batch-import.js.map

package/dist/src/sessions/contracts.js

@@ -20,9 +20,18 @@ export const SessionRuntimeIdentitySchema = z.object({
     canonicalRoot: z.string().nullable(),
     diagnostics: z.array(z.string()),
 });
+export const SessionProviderScopeWarningSchema = z.object({
+    code: z.literal('CONFIGURED_PROVIDERS_OUTSIDE_SCOPE'),
+    configuredProviders: z.array(ExpectedSessionProviderSchema),
+    expectedProviders: z.array(ExpectedSessionProviderSchema),
+    missingProviders: z.array(ExpectedSessionProviderSchema),
+    message: z.string(),
+});
 export const SessionCoveragePreflightSchema = z.object({
     expectedProviders: z.array(ExpectedSessionProviderSchema).min(1),
-    expectedProviderBasis: z.enum(['explicit', 'declared-default', 'legacy']),
+    expectedProviderBasis: z.enum(['explicit', 'workspace-config', 'declared-default', 'legacy']),
+    configuredProviders: z.array(ExpectedSessionProviderSchema).optional(),
+    scopeWarnings: z.array(SessionProviderScopeWarningSchema).optional(),
     supportedProviders: z.array(ExpectedSessionProviderSchema),
     runtime: SessionRuntimeIdentitySchema,
     status: z.enum(['partial', 'complete']),

package/dist/src/sessions/coverage-preflight.js

@@ -19,6 +19,29 @@ export function expectedSessionProviders(values) {
     }
     return [...new Set(providers)].sort();
 }
+export function providerScopeWarnings(configured, expected, recorded = []) {
+    const configuredProviders = configured.length ? expectedSessionProviders(configured) : [];
+    const expectedProviders = expected.length ? expectedSessionProviders(expected) : [];
+    const missingProviders = configuredProviders.filter(provider => !expectedProviders.includes(provider));
+    const current = missingProviders.length ? [{
+            code: 'CONFIGURED_PROVIDERS_OUTSIDE_SCOPE', configuredProviders, expectedProviders, missingProviders,
+            message: `Configured providers outside discovery scope: ${missingProviders.join(', ')}. Rediscover or refresh with current workspace config; verify authorized roots before rebuilding.`,
+        }] : [];
+    return [...recorded, ...current].filter((warning, index, all) => all.findIndex(item => JSON.stringify(item) === JSON.stringify(warning)) === index);
+}
+/** Explicit scope applies once; maintenance combines current config with saved root grants. */
+export function resolveSessionProviderScope(configured, explicit, authorized) {
+    const configuredProviders = configured.length ? expectedSessionProviders(configured) : [];
+    const values = [...configuredProviders, ...(authorized ?? [])];
+    const expectedProviders = expectedSessionProviders(explicit ?? (values.length ? values : SESSION_PROVIDER_IDS));
+    return {
+        expectedProviders,
+        expectedProviderBasis: explicit ? 'explicit' : configuredProviders.length ? 'workspace-config'
+            : authorized?.length ? 'explicit' : 'declared-default',
+        configuredProviders,
+        scopeWarnings: providerScopeWarnings(configuredProviders, expectedProviders),
+    };
+}
 /** Resolve the code actually loaded, independently of cwd, AIWG_ROOT and corpus redirects. */
 export function sessionRuntimeIdentity() {
     const packageRoot = findPackageRoot(dirname(fileURLToPath(import.meta.url)));
@@ -103,6 +126,8 @@ export function coveragePreflight(options = {}) {
     return SessionCoveragePreflightSchema.parse({
         expectedProviders,
         expectedProviderBasis: options.expectedProviderBasis ?? (options.expectedProviders ? 'explicit' : 'declared-default'),
+        ...(options.configuredProviders ? { configuredProviders: options.configuredProviders } : {}),
+        ...(options.scopeWarnings ? { scopeWarnings: options.scopeWarnings } : {}),
         supportedProviders: adapters.map((adapter) => adapter.provider), runtime,
         status: 'partial', unresolvedProviders: expectedProviders, ledger,
     });
@@ -127,7 +152,7 @@ export function reconcileCoveragePreflight(preflight, sources) {
     const runtimeGap = ['mismatch', 'stale', 'unknown'].includes(preflight.runtime.installationState);
     return {
         ...preflight, ledger, unresolvedProviders,
-        status: unresolvedProviders.length > 0 || runtimeGap || preflight.expectedProviderBasis !== 'explicit'
+        status: unresolvedProviders.length > 0 || runtimeGap || !['explicit', 'workspace-config'].includes(preflight.expectedProviderBasis)
             ? 'partial' : 'complete',
     };
 }

package/dist/src/sessions/policy.js

@@ -56,20 +56,31 @@ async function safeRealpath(path, root = false) {
         throw new SessionContractError('SOURCE_NOT_AUTHORIZED', root ? 'an authorized source root is inaccessible' : 'selected session source is inaccessible');
     }
 }
+// Newline gaps are bounded and each repetition consumes a line break, keeping
+// indentation scans disjoint even on large malformed records (#3273, #3404).
+const VALUE_GAP = /[ \t]*(?:\r?\n[ \t]*){0,2}/.source;
+const NEXT_LINE_GAP = /[ \t]*(?:\r?\n[ \t]*){1,2}/.source;
+const QUOTED_VALUE = /"(?:\\[^\r\n]|[^"\\\r\n])+"|'(?:\\[^\r\n]|[^'\\\r\n])+'|`(?!`)(?:\\[^\r\n]|[^`\\\r\n])+`(?!`)/.source;
+const GENERATED_VALUE = /(?=[A-Za-z0-9._~+/=-]*[0-9])(?=[A-Za-z0-9._~+/=-]*[A-Za-z])[A-Za-z0-9._~+/=-]{20,}/.source;
+function assignmentPattern(key, separator, sameLineValue) {
+    // Only the next-line branch needs stronger evidence: quoted text or a long
+    // generated value. In particular, YAML lists and Markdown fences are prose.
+    return new RegExp(`\\b${key}[ \\t]*${separator}(?:${NEXT_LINE_GAP}(?:${QUOTED_VALUE}|${GENERATED_VALUE})|[ \\t]*(?:${QUOTED_VALUE}|${sameLineValue}))`, 'gi');
+}
 // Ambiguous token components are bounded; whitespace and key blocks use disjoint scans.
 const SECRET_PATTERNS = [
-    ['bearer-token', /\bBearer[ \t]+[A-Za-z0-9._~+/=-]{12,}/gi],
-    ['authorization', /\bAuthorization[ \t]*:[ \t]*[^\r\n]+/gi],
-    ['cookie', /\b(?:Cookie|Set-Cookie)[ \t]*:[ \t]*[^\r\n]+/gi],
-    ['environment-assignment', /\b(?:AWS_SECRET_ACCESS_KEY|[A-Z][A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|PASSWD|API_KEY))[ \t]*=[ \t]*(?:"[^"\r\n]+"|'[^'\r\n]+'|[^\s]+)/gi],
-    ['credential', /\b(?:api[_-]?key|token|password|secret)[ \t]*[:=][ \t]*["']?[^\s"',;]{6,}/gi],
+    ['bearer-token', new RegExp(`\\bBearer(?:[ \\t]+|${NEXT_LINE_GAP})(?:${QUOTED_VALUE}|\\\\"[A-Za-z0-9._~+/=-]{12,}\\\\"|[A-Za-z0-9._~+/=-]{12,})`, 'gi')],
+    ['authorization', new RegExp(`\\bAuthorization[ \\t]*:${VALUE_GAP}[^\\s][^\\r\\n]*`, 'gi')],
+    ['cookie', new RegExp(`\\b(?:Cookie|Set-Cookie)[ \\t]*:${VALUE_GAP}[^\\s][^\\r\\n]*`, 'gi')],
+    ['environment-assignment', assignmentPattern('(?:AWS_SECRET_ACCESS_KEY|[A-Z][A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|PASSWD|API_KEY))', '=', /[^\s]+/.source)],
+    ['credential', assignmentPattern('(?:api[_-]?key|token|password|secret)', '[:=]', /["'`]?[^\s"'`,;]{6,}/.source)],
     ['credential', /^[ \t]*password[ \t]+[^\s]+[ \t]*$/gim],
     // Space-separated values only when they look generated (20+ chars, letters and digits), so prose stays.
-    ['credential', /\b(?:api[_-]?key|token|secret)[ \t]+(?=[A-Za-z0-9._~+/=-]*[0-9])(?=[A-Za-z0-9._~+/=-]*[A-Za-z])[A-Za-z0-9._~+/=-]{20,}/gi],
+    ['credential', new RegExp(`\\b(?:api[_-]?key|token|secret)[ \\t]+${GENERATED_VALUE}`, 'gi')],
     ['provider-token', /\b(?:sk-(?:ant-|proj-)?|[sr]k_(?:live|test)_|gh[pousr]_|github_pat_|glpat-|xai-|npm_|hf_|xox[baprs]-|AKIA|AIza)[A-Za-z0-9._~+/=-]{8,}/g],
     ['provider-token', /https:\/\/hooks\.slack\.com\/services\/[A-Za-z0-9_-]+\/[A-Za-z0-9_-]+\/[A-Za-z0-9_-]+/g],
     ['connection-string', /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis):\/\/[^\s]+/gi],
-    ['credential-url', /\bhttps?:\/\/[^/\s:@]+:[^/\s@]+@[^\s]+/gi],
+    ['credential-url', new RegExp(`\\bhttps?://${VALUE_GAP}[^/\\s:@]+:${VALUE_GAP}(?:${QUOTED_VALUE}|[^/\\s@]+)@${VALUE_GAP}[^\\s"'\x60<>\\\\]+`, 'gi')],
     ['fixture-credential', /\bredaction-canary-[A-Za-z0-9_-]+\b/gi],
     ['email', /\b[A-Z0-9._%+-]{1,64}@[A-Z0-9.-]{1,253}\.[A-Z]{2,63}\b/gi],
 ];

package/dist/src/sessions/refresh.js

@@ -20,7 +20,7 @@ export function sessionRefreshAvailable() {
         return false;
     }
 }
-/** Refresh an existing catalog without inferring or granting provider access. */
+/** Refresh current configured scope within saved provider root grants. */
 export async function refreshSessionCatalog(workspace, full, waitMs, signal, workspaceAliases = [], flags = {}) {
     const canonicalWorkspace = realpathSync(workspace);
     const config = await readAiwgConfig(canonicalWorkspace);
@@ -56,8 +56,7 @@ export async function refreshSessionCatalog(workspace, full, waitMs, signal, wor
             const manifest = await discoverWorkspaceHistories({
                 workspace: canonicalWorkspace,
                 workspaceAliases: [workspace, ...workspaceAliases],
-                expectedProviders: providers,
-                authorizedRoots,
+                refreshFrom: { ...previous, authorizedRoots },
                 registry: createSessionAdapterRegistry(limits),
                 exclude,
                 knownSources: previous.sources,

package/dist/src/sessions/repository.js

@@ -13,7 +13,7 @@ const VISIBLE_SESSION_PREDICATE = `s.lifecycle != 'tombstoned' AND EXISTS (
 )`;
 export class SessionRepository {
     db;
-    constructor(path = ':memory:') {
+    constructor(path = ':memory:', options = {}) {
         let Database;
         try {
             Database = requireFeaturePackage('better-sqlite3');
@@ -23,7 +23,9 @@ export class SessionRepository {
                 'run `aiwg features install sqlite`, then retry. If the native build fails, install ' +
                 'Python 3, make, and a C/C++ compiler supported by node-gyp.', { cause });
         }
-        this.db = new Database(path);
+        this.db = new Database(path, options.readonly ? { readonly: true, fileMustExist: true } : undefined);
+        if (options.readonly)
+            return;
         this.db.pragma('foreign_keys = ON');
         this.db.pragma('journal_mode = WAL');
         this.db.pragma('busy_timeout = 5000');

package/dist/src/sessions/workspace-discovery.js

@@ -5,10 +5,11 @@ import { inspectMuseNativeWorkspace } from './adapters/muse.js';
 import { readOmpSessionHeader } from './adapters/omp.js';
 import { grokbotConversationIdFromLocator } from './adapters/grokbot-locator.js';
 import { resolveOmpPaths } from '../providers/omp-paths.mjs';
-import { SESSION_PROVIDER_IDS, SessionCoveragePreflightSchema, SessionContractError, sha256, } from './contracts.js';
+import { readAiwgConfig } from '../config/aiwg-config.js';
+import { SessionCoveragePreflightSchema, SessionContractError, sha256, } from './contracts.js';
 import { redactSourceLocator } from './discovery.js';
 import { createSessionAdapterRegistry } from './adapter-registry.js';
-import { coveragePreflight, expectedSessionProviders } from './coverage-preflight.js';
+import { coveragePreflight, providerScopeWarnings, resolveSessionProviderScope } from './coverage-preflight.js';
 import { fingerprintSourceFile, streamJsonLines } from './readers.js';
 import { matchSessionWorkspace } from './workspace-matching.js';
 import { matchImportExclusion, nativeSessionIdFromLocator, resolveImportExclusions } from './import-exclusions.js';
@@ -20,9 +21,26 @@ const MANUAL_EXPORT_PROVIDERS = new Set([
 export async function discoverWorkspaceHistories(options) {
     const registry = options.registry ?? createSessionAdapterRegistry();
     const exclusions = resolveImportExclusions(undefined, options.exclude);
-    const expectedProviders = expectedSessionProviders(options.expectedProviders ?? SESSION_PROVIDER_IDS);
     const supportedProviders = new Set(registry.list().map((adapter) => adapter.provider));
     const workspacePath = await canonicalPath(options.workspace);
+    const config = await readAiwgConfig(workspacePath);
+    const configuredProviders = config?.providers ?? [];
+    const explicitlyRootedProviders = [
+        ...(options.codexRoot || options.codexRoots?.length || config?.sessions?.codex_roots?.length ? ['codex'] : []),
+        ...(options.ompRoot ? ['omp'] : []),
+        ...(options.museRoot ? ['muse'] : []),
+        ...(options.dshRoot ? ['deepseek-harness'] : []),
+        ...(options.grokbotRoot ? ['grokbot'] : []),
+    ];
+    const savedRoots = options.authorizedRoots ?? options.refreshFrom?.authorizedRoots;
+    const authorizedProviders = options.refreshFrom
+        ? Object.keys(savedRoots ?? {}).filter(provider => savedRoots?.[provider]?.length)
+        : configuredProviders.length ? explicitlyRootedProviders : undefined;
+    const providerScope = resolveSessionProviderScope(configuredProviders, options.expectedProviders, authorizedProviders);
+    if (options.refreshFrom) {
+        providerScope.scopeWarnings = providerScopeWarnings(configuredProviders, options.refreshFrom.preflight?.expectedProviders ?? []);
+    }
+    const { expectedProviders } = providerScope;
     const workspaceId = workspacePath;
     const workspacePaths = [...new Set([workspacePath, resolve(options.workspace),
             ...(options.workspaceAliases ?? []).map((alias) => resolve(alias))])];
@@ -52,12 +70,19 @@ export async function discoverWorkspaceHistories(options) {
                 ? [resolve(options.grokbotRoot)] : [] },
         {
             provider: 'claude',
-            roots: providerHomes.flatMap((providerHome) => workspacePaths.map((workspace) => join(providerHome, '.claude', 'projects', claudeProjectKey(workspace)))),
+            // Same scope rule as codex: configured providers keep their root grant
+            // even when a narrow discovery does not scan them (#3402).
+            roots: savedRoots || (!expectedProviders.includes('claude') && !providerScope.configuredProviders?.includes('claude'))
+                ? [] : await claudeDiscoveryRoots(providerHomes, workspacePaths, workspacePath, registry, exclusions),
         },
         {
             provider: 'codex',
-            roots: options.authorizedRoots || !expectedProviders.includes('codex')
-                ? [] : await codexDiscoveryRoots(options),
+            roots: savedRoots || (!expectedProviders.includes('codex') && !providerScope.configuredProviders?.includes('codex')
+                && !explicitlyRootedProviders.includes('codex'))
+                ? [] : await codexDiscoveryRoots({ ...options, codexRoots: [
+                    ...(config?.sessions?.codex_roots ?? []).map(root => resolve(workspacePath, root)),
+                    ...(options.codexRoots ?? []),
+                ] }),
         },
         {
             provider: 'cursor',
@@ -85,11 +110,22 @@ export async function discoverWorkspaceHistories(options) {
                 : providerHomes.map((providerHome) => join(providerHome, '.pi', 'agent', 'sessions'))).flatMap((sessionsRoot) => workspacePaths.map((workspace) => join(sessionsRoot, `--${workspaceKey(workspace, false)}--`))),
         },
     ];
-    const authorizedRoots = { ...options.authorizedRoots };
+    const authorizedRoots = { ...savedRoots };
     const reports = new Map();
     const candidates = [];
     const seen = new Set();
     for (const entry of discoverable) {
+        // A hand-run narrow scope must not discard explicit root grants, including
+        // configured providers under an authorized home. Do not scan their histories.
+        if (!savedRoots && !expectedProviders.includes(entry.provider)
+            && (explicitlyRootedProviders.includes(entry.provider)
+                || (providerScope.configuredProviders?.includes(entry.provider) && options.providerHome))) {
+            const roots = [];
+            for (const root of entry.roots)
+                if (await pathExists(root))
+                    roots.push(await canonicalPath(root));
+            authorizedRoots[entry.provider] = [...new Set(roots)];
+        }
         if (!expectedProviders.includes(entry.provider) || !supportedProviders.has(entry.provider))
             continue;
         const adapter = registry.get(entry.provider);
@@ -97,10 +133,10 @@ export async function discoverWorkspaceHistories(options) {
             continue;
         const availableRoots = [];
         const rootCounts = new Map();
-        for (const root of options.authorizedRoots ? options.authorizedRoots[entry.provider] ?? [] : entry.roots) {
+        for (const root of savedRoots ? savedRoots[entry.provider] ?? [] : entry.roots) {
             if (await pathExists(root)) {
                 const canonical = await canonicalPath(root);
-                if (options.authorizedRoots && canonical !== root) {
+                if (savedRoots && canonical !== root) {
                     throw new SessionContractError('INVALID_ARGUMENT', 'previously authorized provider root changed; rediscover with explicit authorization');
                 }
                 if (!availableRoots.includes(canonical)) {
@@ -198,9 +234,12 @@ export async function discoverWorkspaceHistories(options) {
             const authorizedRoot = scope.allowedRoots.find((root) => locator === root || locator.startsWith(`${root}/`));
             if (!authorizedRoot)
                 continue;
-            if (entry.provider === 'claude'
-                && !await claudeSourceMatchesWorkspace(locator, workspacePath))
-                continue;
+            if (entry.provider === 'claude') {
+                const exactProject = workspacePaths.some(path => basename(authorizedRoot) === claudeProjectKey(path));
+                workspaceMatch = await claudeSourceWorkspaceMatch(locator, workspacePath, exactProject);
+                if (!workspaceMatch)
+                    continue;
+            }
             const fingerprint = await fingerprintSourceFile({
                 selectedPath: locator,
                 allowedRoots: [authorizedRoot],
@@ -274,7 +313,7 @@ export async function discoverWorkspaceHistories(options) {
     const sources = candidates.sort(compareSources);
     const providers = [...reports.values()].sort((a, b) => a.provider.localeCompare(b.provider));
     const preflight = coveragePreflight({
-        expectedProviders, expectedProviderBasis: options.expectedProviders ? 'explicit' : 'declared-default',
+        ...providerScope,
         registry, runtime: options.runtime, reports: providers,
     });
     const identity = {
@@ -512,7 +551,40 @@ function asObject(value) {
 async function canonicalPath(path) {
     return realpath(resolve(path));
 }
-async function claudeSourceMatchesWorkspace(locator, workspacePath) {
+/** Claude keys are lossy: use transcript cwd, never decode hyphens into paths. */
+async function claudeDiscoveryRoots(homes, paths, workspace, registry, exclusions) {
+    const roots = homes.flatMap(home => paths.map(path => join(home, '.claude', 'projects', claudeProjectKey(path))));
+    const adapter = registry.get('claude');
+    for (const home of homes) {
+        const projects = join(home, '.claude', 'projects');
+        let entries;
+        try {
+            entries = await readdir(projects, { withFileTypes: true });
+        }
+        catch (error) {
+            if (['ENOENT', 'ENOTDIR'].includes(error.code ?? ''))
+                continue;
+            throw error;
+        }
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!entry.isDirectory())
+                continue;
+            const root = join(projects, entry.name);
+            if (roots.includes(root))
+                continue;
+            for await (const descriptor of adapter.discover({ workspaceId: workspace, allowedRoots: [root] })) {
+                if (matchImportExclusion(descriptor, exclusions))
+                    continue;
+                if (await claudeSourceWorkspaceMatch(descriptor.locator, workspace, false)) {
+                    roots.push(root);
+                    break;
+                }
+            }
+        }
+    }
+    return [...new Set(roots)];
+}
+async function claudeSourceWorkspaceMatch(locator, workspacePath, exactProject) {
     let count = 0;
     for await (const { line } of streamJsonLines(locator, { end: 1024 * 1024 - 1 })) {
         if (++count > 50)
@@ -527,15 +599,10 @@ async function claudeSourceMatchesWorkspace(locator, workspacePath) {
         const cwd = asObject(value).cwd;
         if (typeof cwd !== 'string' || cwd.length === 0)
             continue;
-        try {
-            return await canonicalPath(cwd) === workspacePath;
-        }
-        catch {
-            return resolve(cwd) === workspacePath;
-        }
+        return matchSessionWorkspace(cwd, workspacePath);
     }
-    // Older transcripts without cwd still use the selected project folder.
-    return true;
+    // Only exact project keys can establish ownership without cwd.
+    return exactProject ? 'exact' : null;
 }
 export function claudeProjectKey(path) {
     // Claude Code 2.1.302 replaces each character, then caps keys at 200

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.10.4",
+  "version": "2026.10.5",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",