@aiwg/cli 2026.10.4 → 2026.10.6

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

@@ -8,7 +8,7 @@ import { isDeepStrictEqual } from 'node:util';
 import path from 'node:path';
 import { glob } from 'glob';
 import { load as loadYaml } from 'js-yaml';
-import { compileModelPolicy, validateCanonicalModelPolicy, validateUserProjectModelConfig, loadProviderModelCapabilities, WorkerPolicyError, } from '../../models/provider-policy.js';
+import { compileModelPolicy, validateCanonicalModelPolicy, validateUserProjectModelConfig, loadProviderModelCapabilities, WorkerPolicyError, assertWorkerRoleEffort, } from '../../models/provider-policy.js';
 import { resolveGrokBuildRoleModel } from '../../models/grok-build-models.js';
 import { readAiwgConfig, emptyConfig } from '../../config/aiwg-config.js';
 import { ConfigLoader } from '../../models/config-loader.js';
@@ -39,8 +39,38 @@ export async function loadWorkerInputs(ctx) {
         return { snapshot: { config, models, modelDigests: loader.getInputDigests(), catalog,
                 registry, installations: {} }, drivers: {} };
     }
+    // Explain missing policy before a recorded approval's digest check can
+    // mask it. The host owner first preserves its missing-installation errors.
+    const parallelism = config.parallelism;
+    const precheckPolicy = () => {
+        if (!ctx.args.some(arg => arg === '--role' || arg.startsWith('--role=')))
+            return;
+        const request = parseWorkerCommandArgs(ctx.args.slice(1));
+        const members = Object.entries(parallelism.groups ?? {})
+            .filter(([id]) => !request.group || request.group === id)
+            .flatMap(([, group]) => group.members).filter(member => member.enabled !== false
+            && parallelism.clis?.[member.cli]?.enabled !== false && member.roles.includes(request.role));
+        const requiresExplicit = members.length > 0 && members.every(member => {
+            // Health metadata can identify the provider before an operator has
+            // qualified its dispatch adapter. It grants no dispatch authority.
+            const [namespace, id] = (parallelism.clis?.[member.cli]?.adapter ?? `providers:${member.cli}`).split(':');
+            const provider = namespace === 'providers' ? registry.providers[id] : undefined;
+            const adapter = namespace === 'workerAdapters' ? registry.workerAdapters?.[id]
+                : provider?.workerAdapter ?? provider?.workerHealthAdapter;
+            const observation = (catalog.discovery?.instances?.[member.cli]
+                ?? catalog.discovery?.providers?.[adapter?.provider ?? id])?.models.find(row => row.id === member.model)?.worker;
+            if (observation?.effortSupport === 'explicit')
+                return true;
+            if (observation?.effortSupport === 'not-applicable')
+                return false;
+            return adapter?.capabilities.effort === 'explicit';
+        });
+        // With no matching worker, do not invent policy needs.
+        if (members.length)
+            assertWorkerRoleEffort(models.defaults.workerSelection, request.role, requiresExplicit);
+    };
     const { registry: qualifiedRegistry, installations, drivers, observations } = await loadRecordedWorkerInstallations({
-        registry, cwd: ctx.cwd, policy: models.defaults.workerSelection, parallelism: config.parallelism,
+        registry, cwd: ctx.cwd, policy: models.defaults.workerSelection, parallelism: config.parallelism, precheckPolicy,
     });
     catalog.discovery ??= { source: 'static', fetchedAt: new Date().toISOString(), providers: {} };
     catalog.discovery.instances = { ...catalog.discovery.instances };

package/dist/src/cli/handlers/ralph-launcher.js

@@ -62,6 +62,13 @@ export function generateLoopId(objective) {
  * Build command-line arguments for the external Ralph process
  */
 export function buildArgs(options) {
+    if (options.managedWorker) {
+        if (!options.managedAdmission)
+            throw new Error('Managed worker execution requires admission');
+        return ['--launch-worker', '--invocation', options.managedWorker.invocationPath,
+            '--run-dir', options.managedWorker.runDir, '--managed-request', options.managedAdmission.requestId,
+            '--managed-generation', String(options.managedAdmission.generation)];
+    }
     const args = [options.objective];
     args.push('--completion', options.completionCriteria);
     if (options.maxIterations) {
@@ -175,7 +182,9 @@ export async function assertRalphParallelismCap(projectRoot) {
  * Launch the external Ralph process as a detached daemon
  */
 export async function launchExternalRalph(frameworkRoot, projectRoot, options) {
-    const orchestratorPath = getOrchestratorPath(frameworkRoot);
+    const orchestratorPath = options.managedWorker
+        ? join(frameworkRoot, 'tools', 'ralph-external', 'session-launcher.mjs')
+        : getOrchestratorPath(frameworkRoot);
     if (!existsSync(orchestratorPath)) {
         throw new AiwgError({
             code: 'ERR_RALPH_ORCHESTRATOR_MISSING',
@@ -191,6 +200,9 @@ export async function launchExternalRalph(frameworkRoot, projectRoot, options) {
     // surprising. Tell the operator what's running and how to lift the cap.
     await assertRalphParallelismCap(projectRoot);
     const loopId = options.loopId || generateLoopId(options.objective);
+    if (loadLauncherRegistry(projectRoot).loops[loopId]?.managedAdmission) {
+        throw new Error('Managed loop identity cannot be relaunched before admission reconciliation');
+    }
     const loopDir = join(registryDir, 'loops', loopId);
     mkdirSync(loopDir, { recursive: true });
     // Create output file for the detached process
@@ -200,6 +212,17 @@ export async function launchExternalRalph(frameworkRoot, projectRoot, options) {
     const promptFile = join(loopDir, 'prompts', '001-prompt.md');
     // Build arguments
     const args = buildArgs(options);
+    if (options.managedAdmission) {
+        const registry = loadLauncherRegistry(projectRoot);
+        registry.loops[loopId] = { loopId, pid: 0, objective: options.objective,
+            completionCriteria: options.completionCriteria, status: 'running',
+            startedAt: new Date().toISOString(), lastUpdate: new Date().toISOString(),
+            iteration: 0, maxIterations: options.managedWorker ? 1 : options.maxIterations || 5, outputFile,
+            sessionStdoutFile, sessionStderrFile, promptFile, provider: options.provider,
+            managedAdmission: { ...options.managedAdmission },
+            ...(options.managedWorker ? { managedWorker: { ...options.managedWorker } } : {}) };
+        saveLauncherRegistry(projectRoot, registry);
+    }
     // Create output file descriptors
     const { openSync, closeSync } = await import('fs');
     const outFd = openSync(outputFile, 'w');
@@ -232,6 +255,25 @@ export async function launchExternalRalph(frameworkRoot, projectRoot, options) {
             exitCode: EXIT_CODES.GENERAL,
         });
     }
+    let managedAdmission;
+    if (options.managedAdmission) {
+        const { sampleWorkerIdentity, createWorkerIdentityCapture } = await import(join(frameworkRoot, 'tools', 'ralph-external', 'process-monitor.mjs'));
+        const capture = createWorkerIdentityCapture({ timeoutMs: 250 });
+        const identityDeadline = process.hrtime.bigint() + 250000000n;
+        let identity;
+        while (!identity && process.hrtime.bigint() < identityDeadline) {
+            if ((child.exitCode !== null && child.exitCode !== undefined) || child.signalCode)
+                break;
+            identity = capture.observe(sampleWorkerIdentity(pid));
+            if (!identity)
+                await new Promise(resolve => setTimeout(resolve, 10));
+        }
+        if (!identity?.bootId || !identity.startTicks || !Number.isSafeInteger(identity.uid)) {
+            throw new Error('managed Ralph execution identity unavailable; reconcile uncertain launch');
+        }
+        managedAdmission = { ...options.managedAdmission,
+            execution: { pid, startedAt: `${identity.bootId}:${identity.startTicks}:${identity.uid}` }, processIdentity: identity };
+    }
     // Record the loop in our launcher registry (backup to the external-multi-loop-state-manager)
     const launcherRegistry = loadLauncherRegistry(projectRoot);
     launcherRegistry.loops[loopId] = {
@@ -243,12 +285,14 @@ export async function launchExternalRalph(frameworkRoot, projectRoot, options) {
         startedAt: new Date().toISOString(),
         lastUpdate: new Date().toISOString(),
         iteration: 0,
-        maxIterations: options.maxIterations || 5,
+        maxIterations: options.managedWorker ? 1 : options.maxIterations || 5,
         outputFile,
         sessionStdoutFile,
         sessionStderrFile,
         promptFile,
         provider: options.provider,
+        ...(managedAdmission ? { managedAdmission } : {}),
+        ...(options.managedWorker ? { managedWorker: { ...options.managedWorker } } : {}),
     };
     saveLauncherRegistry(projectRoot, launcherRegistry);
     return {
@@ -257,6 +301,7 @@ export async function launchExternalRalph(frameworkRoot, projectRoot, options) {
         pid,
         message: `agent loop started (${loopId}). Check status: aiwg ralph-status`,
         registryPath: getRegistryPath(projectRoot),
+        ...(managedAdmission ? { execution: managedAdmission.execution } : {}),
     };
 }
 /**
@@ -341,7 +386,7 @@ export function getLoopStatuses(projectRoot, options = {}) {
             entry.stale = true;
         }
         // Auto-clean completed entries if requested
-        if (options.autoCleanCompleted && (entry.status === 'completed')) {
+        if (options.autoCleanCompleted && !entry.managedAdmission && (entry.status === 'completed')) {
             cleanupCompletedLoop(projectRoot, loopId);
             registryDirty = true;
             continue; // Don't include in statuses
@@ -372,6 +417,8 @@ export function abortLoop(projectRoot, loopId) {
     if (!entry) {
         return { success: false, message: `Loop not found: ${loopId}` };
     }
+    if (entry.managedAdmission)
+        return { success: false, message: 'Managed loop cancellation requires its current admission generation' };
     if (!isProcessAlive(entry.pid)) {
         entry.status = 'aborted';
         saveLauncherRegistry(projectRoot, registry);
@@ -391,6 +438,26 @@ export function abortLoop(projectRoot, loopId) {
         };
     }
 }
+/** Signal only the birth identity bound to this current managed reservation.
+ * Native Ralph exit/status cannot prove descendant termination, so cancellation
+ * always leaves its admission reservation uncertain for explicit reconciliation.
+ */
+export async function cancelManagedRalph(frameworkRoot, projectRoot, loopId, binding) {
+    const entry = loadLauncherRegistry(projectRoot).loops[loopId];
+    const owned = entry?.managedAdmission;
+    if (!owned?.execution || !owned.processIdentity || owned.requestId !== binding.requestId || owned.generation !== binding.generation
+        || owned.execution.pid !== binding.execution.pid || owned.execution.startedAt !== binding.execution.startedAt) {
+        return { state: 'uncertain', signalled: false };
+    }
+    const { sampleWorkerIdentity } = await import(join(frameworkRoot, 'tools', 'ralph-external', 'process-monitor.mjs'));
+    const identity = sampleWorkerIdentity(owned.execution.pid);
+    const expected = owned.processIdentity;
+    if (!identity || ['pid', 'uid', 'bootId', 'startTicks', 'executable', 'pgid', 'sessionId']
+        .some(key => identity[key] !== expected[key]))
+        return { state: 'uncertain', signalled: false };
+    const { signalOwnedWorker } = await import(join(frameworkRoot, 'tools', 'ralph-external', 'session-launcher.mjs'));
+    return { state: 'uncertain', signalled: signalOwnedWorker(identity, 'SIGTERM') };
+}
 /**
  * Resume an interrupted agent loop
  */
@@ -438,6 +505,8 @@ export async function resumeLoop(frameworkRoot, projectRoot, loopId, overrides)
             exitCode: EXIT_CODES.USAGE,
         });
     }
+    if (entry.managedAdmission)
+        throw new Error('Managed loops require policy and admission reconciliation before resume');
     const loopDir = join(registryDir, 'loops', targetLoopId);
     const outputFile = join(loopDir, 'daemon-output.log');
     // Create output file descriptor
@@ -494,6 +563,9 @@ export function cleanupCompletedLoop(projectRoot, loopId, options = {}) {
     const registryDir = getRegistryDir(projectRoot);
     const loopDir = join(registryDir, 'loops', loopId);
     const preserved = [];
+    if (loadLauncherRegistry(projectRoot).loops[loopId]?.managedAdmission) {
+        return { success: false, message: 'Managed loop artifacts require admission reconciliation before cleanup', preserved };
+    }
     // Preserve completion reports before deleting the loop directory
     if (existsSync(loopDir)) {
         try {
@@ -616,7 +688,7 @@ export function cleanupRegistry(projectRoot, keepDays = 7) {
     const cutoff = Date.now() - keepDays * 24 * 60 * 60 * 1000;
     let cleaned = 0;
     for (const [loopId, entry] of Object.entries(registry.loops)) {
-        if (entry.status !== 'running') {
+        if (entry.status !== 'running' && !entry.managedAdmission) {
             const lastUpdate = new Date(entry.lastUpdate).getTime();
             if (lastUpdate < cutoff) {
                 delete registry.loops[loopId];

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

@@ -68,7 +68,7 @@ export const rulesHandler = {
                     throw new Error('Invalid inventory scope');
                 const activation = list('--activation');
                 const tier = list('--tier');
-                if (activation?.some(value => !['kernel', 'summary', 'bound', 'paths', 'on-demand'].includes(value)))
+                if (activation?.some(value => !['core', 'kernel', 'summary', 'bound', 'paths', 'on-demand'].includes(value)))
                     throw new Error('Invalid activation filter');
                 if (tier?.some(value => !['critical', 'high', 'medium', 'low'].includes(value)))
                     throw new Error('Invalid tier filter');

package/dist/src/cli/handlers/script-runner.js

@@ -11,10 +11,17 @@
 import { signalChild } from '../../process/signal-child.mjs';
 import { spawn } from 'child_process';
 import path from 'path';
+import { pathToFileURL } from 'node:url';
+import { Console } from 'node:console';
+import { Writable } from 'node:stream';
+import { writeSync } from 'node:fs';
+// Embedded deployers use process-wide console/environment APIs. Serialize the
+// complete invocation (including import), and restore them even after failure.
+let deploymentQueue = Promise.resolve();
 /**
  * Default script runner implementation
  *
- * Delegates command execution to existing Node.js scripts.
+ * Embeds repeatable agent deployment passes; runs other scripts in a child.
  */
 export class DefaultScriptRunner {
     frameworkRoot;
@@ -30,12 +37,26 @@ export class DefaultScriptRunner {
      */
     async run(scriptPath, args = [], options = {}) {
         const fullPath = path.join(this.frameworkRoot, scriptPath);
+        if (scriptPath === 'tools/agents/deploy-agents.mjs'
+            && process.env.AIWG_DEPLOY_SUBPROCESS !== '1'
+            && options.env?.AIWG_DEPLOY_SUBPROCESS !== '1'
+            && !options.timeout
+            && (!options.cwd || path.resolve(options.cwd) === process.cwd())
+            // Other environment overrides can affect module initialization. Keep
+            // those callers isolated; AIWG_ROOT is resolved afresh by each pass.
+            && Object.keys(options.env ?? {}).every(key => key === 'AIWG_ROOT')) {
+            const invocation = deploymentQueue.then(() => this.runDeployment(fullPath, args, options));
+            deploymentQueue = invocation.catch(() => { });
+            return invocation;
+        }
         return new Promise((resolve) => {
             // When capture mode is enabled, stdout/stderr are piped so that
             // quiet-mode callers can suppress output. When not
             // capturing, stdio: 'inherit' lets subprocess output flow directly to
             // the terminal (verbose mode).
-            const stdio = options.capture ? 'pipe' : 'inherit';
+            const stdio = options.capture
+                ? ['pipe', options.stdoutFd ?? 'pipe', 'pipe']
+                : 'inherit';
             const child = spawn('node', [fullPath, ...args], {
                 stdio,
                 cwd: options.cwd || process.cwd(),
@@ -122,6 +143,56 @@ export class DefaultScriptRunner {
             });
         });
     }
+    async runDeployment(fullPath, args, options) {
+        const previousConsole = globalThis.console;
+        const previousRoot = process.env.AIWG_ROOT;
+        const stderrLimit = 1024 * 1024;
+        const diagnostics = [];
+        let diagnosticBytes = 0;
+        try {
+            if (options.env?.AIWG_ROOT !== undefined)
+                process.env.AIWG_ROOT = options.env.AIWG_ROOT;
+            if (options.capture) {
+                const stdout = new Writable({ write(chunk, _encoding, done) {
+                        try {
+                            if (options.stdoutFd !== undefined)
+                                writeSync(options.stdoutFd, chunk);
+                            done();
+                        }
+                        catch (error) {
+                            done(error);
+                        }
+                    } });
+                const stderr = new Writable({ write(chunk, _encoding, done) {
+                        const retained = chunk.subarray(0, stderrLimit - diagnosticBytes);
+                        if (retained.length) {
+                            diagnostics.push(Buffer.from(retained));
+                            diagnosticBytes += retained.length;
+                        }
+                        done();
+                    } });
+                globalThis.console = new Console({ stdout, stderr });
+            }
+            // Runtime loading follows the provider preparation coordinator precedent;
+            // the runner still supports arbitrary scripts via its subprocess path.
+            const deployer = await import(pathToFileURL(fullPath).href);
+            const exitCode = (await deployer.main(args, { capture: options.capture === true })) ?? 0;
+            const message = Buffer.concat(diagnostics).toString().trim();
+            return exitCode && message ? { exitCode, message } : { exitCode };
+        }
+        catch (error) {
+            const message = Buffer.concat(diagnostics).toString().trim()
+                || (error instanceof Error ? error.message : String(error));
+            return { exitCode: 1, message };
+        }
+        finally {
+            globalThis.console = previousConsole;
+            if (previousRoot === undefined)
+                delete process.env.AIWG_ROOT;
+            else
+                process.env.AIWG_ROOT = previousRoot;
+        }
+    }
 }
 /**
  * Create a script runner for the given framework root

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

@@ -735,9 +735,11 @@ export async function startServer(opts) {
         if (!valid) {
             return c.json({ error: `Invalid register payload: ${errors}` }, 400);
         }
-        const result = executorRegistry.register(body);
-        if ('status' in result && result.status === 400) {
-            return c.json({ error: result.error }, 400);
+        const authHeader = c.req.header('authorization') ?? '';
+        const token = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : '';
+        const result = executorRegistry.register(body, token);
+        if ('status' in result) {
+            return c.json({ error: result.error }, result.status);
         }
         // Emit telemetry (reuse agent.spawn as closest match for executor registration)
         const resp = result;

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,10 +71,12 @@ 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)
+                   Adds to defaults separately authorized by --provider-home
   --omp-root <path>  Explicitly authorize an OMP profile sessions root
   --muse-root <path>  Explicitly authorize a Muse Code sessions root
   --dsh-root <path>  Explicitly authorize a DeepSeek Harness sessions root
@@ -725,12 +728,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 +1296,7 @@ async function discoverWorkspace(ctx, args) {
         ],
     });
     const data = {
+        warnings: manifest.preflight?.scopeWarnings ?? [],
         manifest: publicDiscoveryManifest(manifest),
         manifestPath: redactSourceLocator(manifestPath),
         exactManifestRequiredForImport: true,
@@ -1304,7 +1318,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 +1347,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 +1375,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 +1387,8 @@ async function importDiscovered(ctx, args) {
             });
         }
         finally {
-            repository.close();
+            repository?.close();
+            previous?.close();
         }
     }
     finally {
@@ -1710,7 +1744,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',