@aiwg/cli 2026.10.3 → 2026.10.4

package/dist/src/cli/handlers/runtime-info.js

@@ -202,8 +202,7 @@ async function handleRuntimeInfo(args, cwd = process.cwd()) {
     const { RuntimeDiscovery } = await import('../../smiths/toolsmith/runtime-discovery.mjs');
     const discovery = new RuntimeDiscovery();
     if (hasDiscover) {
-        // Full discovery
-        const catalog = await discovery.discover();
+        const catalog = await discovery.discover({ force: args.includes('--force') });
         if (hasJson) {
             console.log(JSON.stringify(catalog, null, 2));
         }

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

@@ -8,6 +8,7 @@
  * @source @src/cli/router.ts
  * @issue #33
  */
+import { signalChild } from '../../process/signal-child.mjs';
 import { spawn } from 'child_process';
 import path from 'path';
 /**
@@ -73,12 +74,12 @@ export class DefaultScriptRunner {
                     // does not exit within the deadline. Both kill() calls are wrapped
                     // because they can throw ESRCH on an already-exited child.
                     try {
-                        child.kill('SIGTERM');
+                        signalChild(child, 'SIGTERM');
                     }
                     catch { /* already exited */ }
                     killEscalationId = setTimeout(() => {
                         try {
-                            child.kill('SIGKILL');
+                            signalChild(child, 'SIGKILL');
                         }
                         catch { /* already exited */ }
                     }, killDeadlineMs);

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

@@ -32,10 +32,9 @@
  */
 import { spawnSync } from 'child_process';
 import { readFile } from 'node:fs/promises';
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { mkdtempSync, rmSync, writeFileSync, realpathSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { boundedSpawnSync } from '../../process/bounded-child-process.mjs';
+import { boundedSpawn, boundedSpawnSync } from '../../process/bounded-child-process.mjs';
 import { existsSync } from 'node:fs';
 import { ensureRuntimeHome, writeProfileConfig, launchWithProfile } from '../../mcp/adapters/codex-runtime.js';
 import { getFrameworkRoot } from '../../channel/manager.mjs';
@@ -314,8 +313,8 @@ function buildHeadlessLaunch(provider, binaryArgs, prompt) {
     }
     // File transport (opencode): the prompt never touches argv or stdin — it
     // is written to a private temp file only this process can read, passed
-    // by path. `mkdtemp()` under the system temp directory (never a custom
-    // location — #3062 second review, finding 10) already gives the
+    // by path. `mkdtemp()` under the independently verified system temp
+    // directory gives the
     // directory itself a private, unpredictable name owned by this process;
     // the file within it additionally gets an explicit `0600` mode via an
     // exclusive create (`flag: 'wx'` — fails rather than silently
@@ -328,7 +327,15 @@ function buildHeadlessLaunch(provider, binaryArgs, prompt) {
     // `launchProvider()`, keyed off `plan.tempDir`) handles the ordinary
     // "launch ran, now clean up" path; this one exists only for the write
     // itself failing before a `plan` is ever returned to that caller.
-    const tempDir = mkdtempSync(join(tmpdir(), 'aiwg-session-prompt-'));
+    // os.tmpdir() trusts TMPDIR/TEMP/TMP, which can point into the project.
+    // Select and validate the OS location independently of those overrides.
+    const systemTemp = realpathSync(process.platform === 'win32' ? join(process.env.SystemRoot ?? 'C:/Windows', 'Temp') : '/tmp');
+    const info = statSync(systemTemp);
+    if (!info.isDirectory() || (process.platform !== 'win32'
+        && (info.uid !== 0 && info.uid !== process.getuid?.() || (info.mode & 0o022) !== 0 && (info.mode & 0o1000) === 0))) {
+        throw new Error('Unsafe system temporary directory for session prompt');
+    }
+    const tempDir = mkdtempSync(join(systemTemp, 'aiwg-session-prompt-'));
     try {
         const promptPath = join(tempDir, 'prompt.txt');
         writeFileSync(promptPath, prompt, { encoding: 'utf-8', mode: 0o600, flag: 'wx' });
@@ -355,7 +362,7 @@ function buildHeadlessLaunch(provider, binaryArgs, prompt) {
  * and without a terminal, this refuses before spawning anything that would
  * hang.
  */
-function launchProvider(provider, mcpInjected, mcpConfigPath, profile, settingsPath, prompt, interactive) {
+async function launchProvider(provider, mcpInjected, mcpConfigPath, profile, settingsPath, prompt, interactive) {
     const cfg = getProviderConfig(provider);
     if (!isSpawnableProvider(provider)) {
         // Not spawnable — a prompt can never be delivered to a binary that does
@@ -424,11 +431,14 @@ ${cfg.guidanceMessage ?? `Open ${cfg.name} in your project directory to begin.`}
             // 8); stdin-transport providers get it via `input` (never inherited
             // from the parent), file-transport providers get it via a private
             // temp file path already baked into `plan.args`.
-            const result = boundedSpawnSync(cfg.binary, plan.args, 'long', {
+            const launchOptions = {
                 stdio: plan.input !== undefined ? ['pipe', 'inherit', 'inherit'] : ['ignore', 'inherit', 'inherit'],
                 env: process.env,
                 ...(plan.input !== undefined ? { input: plan.input } : {}),
-            });
+            };
+            const result = plan.tempDir
+                ? await boundedSpawn(cfg.binary, plan.args, 'long', { ...launchOptions, stdio: ['ignore', 'inherit', 'inherit'] }, () => rmSync(plan.tempDir, { recursive: true, force: true }))
+                : boundedSpawnSync(cfg.binary, plan.args, 'long', launchOptions);
             const { exitCode, message } = exitCodeForSpawnResult(result, cfg.binary);
             return message ? { exitCode, message } : { exitCode };
         }

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

@@ -3,7 +3,10 @@ import { randomUUID } from 'node:crypto';
 import { basename, dirname, isAbsolute, join, resolve, } from 'node:path';
 import { pathToFileURL } from 'node:url';
 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';
 import { classifyGrokbotBlobName } from '../../sessions/adapters/grokbot-locator.js';
+import { readAiwgConfig } from '../../config/aiwg-config.js';
 const JSON_CONTRACT_VERSION = '1.0.0';
 async function createLineMemoryPromotionDestination(projectRoot, manifestPath) {
     const modulePath = resolve(dirname(manifestPath), 'commands', 'line-memory.mjs');
@@ -48,7 +51,7 @@ Commands:
   promote <id> <version>          Preview promotion; use --confirm to write
   tag <session-id> <tag>          Add a catalog tag
   relocate <source-id> <file>     Update AIWG source-location metadata
-  reindex                         Rebuild catalog indexes
+  reindex --workspace <path-or-id> | --all-workspaces  Rebuild catalog indexes
   delete <session-id>             Preview deletion; use --confirm to tombstone
   restore <session-id>            Restore a reversible catalog tombstone
   purge <session-id>              Preview terminal AIWG-copy purge
@@ -60,6 +63,7 @@ Commands:
 Options:
   --json          Emit the versioned JSON contract
   --dry-run       Preview a mutation without changing state
+  --all-workspaces  Reindex every workspace in the selected catalog (reindex only)
   --db <path>     Select a catalog; relative paths resolve from cwd
   --workspace <path-or-id>  Select the workspace within that catalog for reads
                    (default: current project, matching cwd, or sole catalog workspace)
@@ -69,7 +73,7 @@ Options:
   --expected-providers <ids>  Comma-separated authorized scope, independent of runtime inventory
   --manifest <path>  Override the discovery manifest path
   --provider-home <path>  Override the provider home root (testing/portable homes)
-  --codex-root <path>  Explicitly authorize a shared Codex sessions/export root
+  --codex-root <path>  Authorize a shared Codex sessions/export root (repeatable)
   --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
@@ -78,6 +82,10 @@ Options:
                    (default: grok on PATH, then $GROK_HOME/bin/grok)
   --confirm, --yes  Confirm a persistent discovered batch import
   --lock-wait-ms <n>  Maximum import-lease wait (default 5000)
+  --exclude <id-or-glob>  Skip a session ID or absolute path glob (repeatable); adds to sessions.import.exclude and AIWG_SESSIONS_IMPORT_EXCLUDE
+  --max-record-bytes <n>  Import record limit (default 67108864); overrides AIWG_SESSIONS_IMPORT_MAX_RECORD_BYTES and sessions.import.max_record_bytes
+  --max-source-bytes <n>  Import source limit (default 1073741824, 1 GiB; 0 unlimited); overrides AIWG_SESSIONS_IMPORT_MAX_SOURCE_BYTES and sessions.import.max_source_bytes
+  Import limit precedence: CLI flag > env var > workspace config > default.
   --inactivity-threshold <duration>  Historical inactivity threshold (default 24h)
   --min-coverage <0..1>  Fail list/report commands below a coverage ratio
   --provider <id> Filter list or select an import adapter
@@ -110,9 +118,9 @@ Analytics / forensics:
   --group-by tool|session|provider, --limit <1..5000>
   --authorize-forensics  Required for each authorized forensic invocation
   --markdown      Render a sanitized forensic timeline table`;
-function printHelp(ctx, exitCode = EXIT.ok) {
+async function printHelp(ctx, exitCode = EXIT.ok) {
     if (ctx.args.includes('--json'))
-        emit(envelope('sessions.help', 'ok', { usage: HELP }, null));
+        await emit(envelope('sessions.help', 'ok', { usage: HELP }, null));
     else
         console.log(HELP);
     return { exitCode };
@@ -136,7 +144,7 @@ export const sessionsHandler = {
             const normalized = normalizeError(error);
             const output = envelope('sessions', 'error', null, normalized.error);
             if (json)
-                emit(output);
+                await emit(output);
             else
                 console.error(`${normalized.error.code}: ${normalized.error.message}`);
             return { exitCode: normalized.exitCode, message: normalized.error.message };
@@ -148,7 +156,7 @@ export const sessionsHandler = {
         try {
             const result = await executeCommand(ctx, parsed);
             if (json)
-                emit(result.envelope);
+                await emit(result.envelope);
             else
                 printHuman(result.envelope);
             return { exitCode: result.exitCode };
@@ -157,7 +165,7 @@ export const sessionsHandler = {
             const normalized = normalizeError(error);
             const output = envelope(`sessions.${parsed.command}`, 'error', null, normalized.error);
             if (json)
-                emit(output);
+                await emit(output);
             else
                 console.error(`${normalized.error.code}: ${normalized.error.message}`);
             return { exitCode: normalized.exitCode, message: normalized.error.message };
@@ -590,11 +598,22 @@ async function executeCommand(ctx, args) {
                 return ok(command, { sourceId, redactedLocator });
             }
             case 'reindex': {
-                const { workspaceId } = authorizationContext(ctx, args, command);
+                const allWorkspaces = args.flags.has('--all-workspaces');
+                if (allWorkspaces && args.values.has('--workspace')) {
+                    throw new CliError('INVALID_ARGUMENT', '--all-workspaces cannot be combined with --workspace', EXIT.usage);
+                }
+                const workspaceId = allWorkspaces
+                    ? undefined
+                    : authorizationContext(ctx, args, command).workspaceId;
+                const data = {
+                    operation: 'reindex',
+                    allWorkspaces,
+                    workspaceIds: allWorkspaces ? repository.listWorkspaceIds() : [workspaceId],
+                };
                 if (isDryRun(ctx, args))
-                    return preview(command, { operation: 'reindex' });
+                    return preview(command, data);
                 repository.reindex(workspaceId);
-                return ok(command, { operation: 'reindex' });
+                return ok(command, data);
             }
             case 'audit': {
                 const { workspaceId } = readAuthorizationContext(ctx, args, command, repository);
@@ -721,6 +740,7 @@ async function executeCommand(ctx, args) {
     }
 }
 async function importSource(ctx, args) {
+    const limits = await configuredImportLimits(ctx, args);
     const input = resolve(ctx.cwd, requiredPositional(args, 0, 'file'));
     const providerInput = args.values.get('--provider') ?? 'generic';
     const provider = assertSessionProviderId(providerInput);
@@ -753,37 +773,37 @@ async function importSource(ctx, args) {
     const isDsh = provider === 'deepseek-harness';
     const isWarp = provider === 'warp';
     const isDevinDesktop = provider === 'devin-desktop';
-    const adapter = isDsh ? new DeepSeekHarnessSessionAdapter() : isOmp ? new OmpSessionAdapter() : isClaude
-        ? new ClaudeSessionAdapter()
+    const adapter = isDsh ? new DeepSeekHarnessSessionAdapter(limits) : isOmp ? new OmpSessionAdapter(limits) : isClaude
+        ? new ClaudeSessionAdapter(limits)
         : isCodex
-            ? new CodexSessionAdapter()
+            ? new CodexSessionAdapter(limits)
             : isCopilot
-                ? new CopilotSessionAdapter()
+                ? new CopilotSessionAdapter(limits)
                 : isCursor
-                    ? new CursorSessionAdapter()
+                    ? new CursorSessionAdapter(limits)
                     : isFactory
-                        ? new FactorySessionAdapter()
+                        ? new FactorySessionAdapter(limits)
                         : isHermes
-                            ? new HermesSessionAdapter()
+                            ? new HermesSessionAdapter(limits)
                             : isOpenCode
-                                ? new OpenCodeSessionAdapter()
+                                ? new OpenCodeSessionAdapter(limits)
                                 : isOpenClaw
-                                    ? new OpenClawSessionAdapter()
+                                    ? new OpenClawSessionAdapter(limits)
                                     : isOpenHuman
-                                        ? new OpenHumanSessionAdapter()
+                                        ? new OpenHumanSessionAdapter(limits)
                                         : isGrokbot
-                                            ? new GrokbotSessionAdapter()
+                                            ? new GrokbotSessionAdapter(limits)
                                             : isGrokBuild
-                                                ? new GrokBuildSessionAdapter()
+                                                ? new GrokBuildSessionAdapter(limits)
                                                 : isMuse
-                                                    ? new MuseSessionAdapter()
+                                                    ? new MuseSessionAdapter(limits)
                                                     : isPi
-                                                        ? new PiSessionAdapter()
+                                                        ? new PiSessionAdapter(limits)
                                                         : isWarp
-                                                            ? new WarpSessionAdapter()
+                                                            ? new WarpSessionAdapter(limits)
                                                             : isDevinDesktop
-                                                                ? new DevinDesktopSessionAdapter()
-                                                                : new GenericSessionInterchangeAdapter();
+                                                                ? new DevinDesktopSessionAdapter(limits)
+                                                                : new GenericSessionInterchangeAdapter(limits);
     const locatorClass = isDsh ? 'deepseek-harness-session-v2-jsonl' : isOmp ? 'omp-session-v3-jsonl' : isClaude
         ? claudeLocatorClass(input)
         : isCodex
@@ -932,8 +952,9 @@ async function importSource(ctx, args) {
     try {
         const repository = openRepository(ctx, args);
         try {
+            const interruptedRuns = repository.interruptRunningBatchImports();
             const receipts = await new IncrementalSessionImporter(repository).import({
-                source, selectedSource, adapter, workspaceId, policyVersion: '1.0.0',
+                source, selectedSource, adapter, workspaceId, policyVersion: '1.0.0', limits,
                 inactivityThresholdMs: inactivityThreshold(args.values.get('--inactivity-threshold')),
             });
             for (const warning of workspaceReport.warnings)
@@ -942,6 +963,7 @@ async function importSource(ctx, args) {
                 sourceId,
                 ...workspaceReport,
                 receipts,
+                interruptedRuns,
                 totals: {
                     sessionsInserted: receipts.reduce((sum, item) => sum + item.sessionsInserted, 0),
                     eventsInserted: receipts.reduce((sum, item) => sum + item.eventsInserted, 0),
@@ -1234,8 +1256,15 @@ async function exportUnpack(ctx, args, command) {
 }
 async function discoverWorkspace(ctx, args) {
     const workspace = resolve(ctx.cwd, requiredValue(args, '--workspace'));
+    const config = await readAiwgConfig(workspace);
+    const canonicalWorkspace = realpathSync(workspace);
+    const manifestPath = resolve(ctx.cwd, args.values.get('--manifest') ?? defaultDiscoveryManifestPath(canonicalWorkspace));
+    const exclude = resolveImportExclusions(config?.sessions?.import, args.exclude);
+    const previous = exclude.length > 0 && existsSync(manifestPath) ? await readDiscoveryManifest(manifestPath) : undefined;
     const manifest = await discoverWorkspaceHistories({
         workspace,
+        knownSources: previous?.workspaceId === canonicalWorkspace ? previous.sources : undefined,
+        exclude,
         expectedProviders: requestedProviders(args),
         providerHome: args.values.has('--provider-home')
             ? resolve(ctx.cwd, args.values.get('--provider-home'))
@@ -1248,11 +1277,11 @@ async function discoverWorkspace(ctx, args) {
             ? resolve(ctx.cwd, args.values.get('--dsh-root')) : undefined,
         grokbotRoot: args.values.has('--grokbot-root')
             ? resolve(ctx.cwd, args.values.get('--grokbot-root')) : undefined,
-        codexRoot: args.values.has('--codex-root')
-            ? resolve(ctx.cwd, args.values.get('--codex-root'))
-            : undefined,
+        codexRoots: [
+            ...(config?.sessions?.codex_roots ?? []).map((root) => resolve(workspace, root)),
+            ...args.codexRoots.map((root) => resolve(ctx.cwd, root)),
+        ],
     });
-    const manifestPath = resolve(ctx.cwd, args.values.get('--manifest') ?? defaultDiscoveryManifestPath(manifest.workspacePath));
     const data = {
         manifest: publicDiscoveryManifest(manifest),
         manifestPath: redactSourceLocator(manifestPath),
@@ -1267,6 +1296,9 @@ async function discoverWorkspace(ctx, args) {
 async function importDiscovered(ctx, args) {
     const workspace = resolve(ctx.cwd, requiredValue(args, '--workspace'));
     const canonicalWorkspace = realpathSync(workspace);
+    const limits = await configuredImportLimits(ctx, args, canonicalWorkspace);
+    const config = await readAiwgConfig(canonicalWorkspace);
+    const exclude = resolveImportExclusions(config?.sessions?.import, args.exclude);
     const manifestPath = resolve(ctx.cwd, args.values.get('--manifest') ?? defaultDiscoveryManifestPath(canonicalWorkspace));
     const manifest = await readDiscoveryManifest(manifestPath);
     if (manifest.workspaceId !== canonicalWorkspace) {
@@ -1289,7 +1321,7 @@ async function importDiscovered(ctx, args) {
         }
         return preview('import-discovered', {
             manifest: publicDiscoveryManifest(manifest),
-            receipt: previewDiscoveryImport(manifest, existing),
+            receipt: previewDiscoveryImport(manifest, existing, new Date(), exclude),
             confirmationRequired: !isDryRun(ctx, args),
             wouldPersist: false,
         });
@@ -1300,12 +1332,16 @@ async function importDiscovered(ctx, args) {
     try {
         const repository = openRepository(ctx, args);
         try {
+            const interruptedRuns = repository.interruptRunningBatchImports();
             const receipt = await importDiscoveryManifest({
                 manifest,
                 repository,
+                limits,
+                exclude,
                 signal: ctx.signal,
                 inactivityThresholdMs: inactivityThreshold(args.values.get('--inactivity-threshold')),
             });
+            receipt.interruptedRuns = interruptedRuns;
             return ok('import-discovered', {
                 manifestId: manifest.manifestId,
                 receipt,
@@ -1648,9 +1684,25 @@ function catalogScope(ctx, args, repository, workspaceId) {
             : null,
     };
 }
+async function configuredImportLimits(ctx, args, workspace) {
+    const selectedWorkspace = workspace ?? (args.values.has('--workspace')
+        ? resolve(ctx.cwd, args.values.get('--workspace')) : ctx.cwd);
+    try {
+        const config = await readAiwgConfig(selectedWorkspace);
+        return resolveImportLimits(config?.sessions?.import, {
+            maxRecordBytes: args.values.get('--max-record-bytes'),
+            maxSourceBytes: args.values.get('--max-source-bytes'),
+        });
+    }
+    catch (error) {
+        throw new CliError('INVALID_ARGUMENT', error instanceof Error ? error.message : String(error), EXIT.usage);
+    }
+}
 function parseArgs(argv) {
     const flags = new Set();
     const values = new Map();
+    const codexRoots = [];
+    const exclude = [];
     const positionals = [];
     const valueFlags = new Set([
         '--db', '--provider', '--workspace', '--tag', '--limit', '--cursor', '--source-id',
@@ -1659,7 +1711,7 @@ function parseArgs(argv) {
         '--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',
-        '--inactivity-threshold', '--expected-providers',
+        '--inactivity-threshold', '--expected-providers', '--exclude', '--max-record-bytes', '--max-source-bytes',
         '--control-events',
         '--session', '--status', '--actor', '--group-by',
         '--out', '--plan', '--input', '--shard-name', '--max-attachment-bytes', '--format', '--grok-bin',
@@ -1673,6 +1725,10 @@ function parseArgs(argv) {
                 throw new CliError('MISSING_OPTION_VALUE', `missing value for ${arg}`, EXIT.usage);
             }
             values.set(arg, value);
+            if (arg === '--codex-root')
+                codexRoots.push(value);
+            if (arg === '--exclude')
+                exclude.push(value);
             index += 1;
         }
         else if (arg.startsWith('-')) {
@@ -1685,7 +1741,7 @@ function parseArgs(argv) {
             positionals.push(arg);
         }
     }
-    return { command, positionals, flags, values };
+    return { command, positionals, flags, values, codexRoots, exclude };
 }
 function requestedProviders(args) {
     const value = args.values.get('--expected-providers');
@@ -1961,8 +2017,13 @@ function preview(command, data) {
 function envelope(command, status, data, error) {
     return { contractVersion: JSON_CONTRACT_VERSION, command, status, data, error };
 }
-function emit(value) {
+async function emit(value) {
     console.log(JSON.stringify(value, null, 2));
+    // The launcher and router may force exit after the handler returns. A write
+    // callback waits for the JSON already queued on stdout, including on pipes.
+    await new Promise((resolve, reject) => {
+        process.stdout.write('', (error) => error ? reject(error) : resolve());
+    });
 }
 function printHuman(value) {
     if (value.status === 'preview')
@@ -2015,7 +2076,7 @@ function normalizeError(error) {
     }
     if (error instanceof SessionContractError) {
         const exitCode = error.code === 'UNSUPPORTED_OPERATION' ? EXIT.unsupported : EXIT.contract;
-        return { error: { code: error.code, message: error.message }, exitCode };
+        return { error: { code: error.code, message: error.message, ...(error.detail ? { details: error.detail } : {}) }, exitCode };
     }
     if (error instanceof ImportLeaseContentionError) {
         return {

package/dist/src/cli/handlers/setup-manifest.js

@@ -8,7 +8,7 @@ import { isInteractive } from '../env.js';
 import { boundedSpawnSync } from '../../process/bounded-child-process.mjs';
 import { sha256 } from '../../security/artifact-trust.js';
 import { artifactVerifyHandler } from './artifact-verify.js';
-import { requireFlagValue, MissingFlagValueError } from '../flag-parsing.js';
+import { requireFlagValue, MissingFlagValueError, collectFlagValues, hasPositionalOrSwitch, argsTerminatorIndex, valueTokenIndexes } from '../flag-parsing.js';
 import { exitCodeForSpawnResult } from '../child-process-result.js';
 import { askString, createPromptInterface } from '../prompt-utils.js';
 const SETUP_SCHEMA_REL = 'agentic/code/addons/agentic-installer/schemas/v1/setup-manifest.schema.json';
@@ -76,9 +76,8 @@ Safety:
 Headless input steps (#3062):
   A 'type: ask' step resolves its declared 'params' the same way a 'script'
   step's env vars do (--param/--params-file/env/default); if every declared
-  param is already resolved it runs headless, otherwise it is refused,
-  naming the missing param names — this CLI has no interactive-capture
-  mechanism for 'ask' steps, with or without a terminal. A step marked
+  param is already resolved it runs headless; otherwise a terminal prompts
+  for missing values. Without a terminal it refuses and names the missing params. A step marked
   'interactive: true' runs an arbitrary script whose questions cannot be
   enumerated; without a terminal it is refused outright. Every selected
   step (including nested 'platform-route' steps) is preflighted for both
@@ -96,40 +95,17 @@ Headless input steps (#3062):
 function flagValue(args, name) {
     return requireFlagValue(args, {}, name);
 }
+const VALUE_FLAGS = [
+    '--manifest', '--schema', '--platform', '--distro', '--params-file', '--param', '--set',
+    '--step', '--skip', '--type', '--output', '--name', '--attestation', '--policy', '--state',
+    '--asset-type', '--namespace', '--channel',
+];
 function hasFlag(args, ...names) {
-    return args.some((arg) => names.includes(arg));
+    return names.some(name => hasPositionalOrSwitch(args, name, VALUE_FLAGS));
 }
 function positionalManifest(args) {
-    const valueFlags = new Set([
-        '--manifest',
-        '--schema',
-        '--platform',
-        '--distro',
-        '--params-file',
-        '--param',
-        '--set',
-        '--step',
-        '--skip',
-        '--type',
-        '--output',
-        '--name',
-        '--attestation',
-        '--policy',
-        '--state',
-        '--asset-type',
-        '--namespace',
-        '--channel',
-    ]);
-    for (let i = 0; i < args.length; i += 1) {
-        const arg = args[i];
-        if (valueFlags.has(arg)) {
-            i += 1;
-            continue;
-        }
-        if (!arg.startsWith('-'))
-            return arg;
-    }
-    return undefined;
+    const consumed = valueTokenIndexes(args, VALUE_FLAGS);
+    return args.slice(0, argsTerminatorIndex(args)).find((arg, index) => !consumed.has(index) && !arg.startsWith('-'));
 }
 function resolveSchemaPath(frameworkRoot, cwd, override) {
     if (override)
@@ -472,15 +448,12 @@ function renderValidationText(result) {
 }
 function parseParamValues(args) {
     const values = {};
-    for (let i = 0; i < args.length; i += 1) {
-        if (args[i] !== '--param' && args[i] !== '--set')
-            continue;
-        const raw = args[i + 1] ?? '';
+    for (const raw of collectFlagValues(args, {}, '--param', '--set')) {
         const eq = raw.indexOf('=');
-        if (eq <= 0)
-            throw new Error(`${args[i]} requires KEY=VALUE`);
+        if (eq <= 0 || !raw.slice(0, eq).trim())
+            throw new MissingFlagValueError('--param KEY=VALUE');
+        // An empty parameter value is supported (e.g. explicitly clearing a default).
         values[raw.slice(0, eq)] = raw.slice(eq + 1);
-        i += 1;
     }
     return values;
 }
@@ -1068,10 +1041,21 @@ export async function runSetupManifest(options) {
         return { exitCode: 1, message: `setup-run: platform ${target.os}${target.distro ? `/${target.distro}` : ''}/${target.arch}/${target.shell} is not declared in the manifest` };
     }
     const params = resolveParams(manifest, options);
-    if (params.missing.length) {
+    const steps = selectedSteps(manifest, options);
+    const askSteps = [];
+    const collectAsks = (selected) => {
+        for (const step of selected) {
+            if (step.type === 'ask')
+                askSteps.push(step);
+            if (step.type === 'platform-route')
+                collectAsks(step.routes?.find(route => route.platform === target.os)?.steps ?? []);
+        }
+    };
+    collectAsks(steps);
+    const promptable = new Set(isInteractive() ? askSteps.flatMap(askStepParams) : []);
+    if (params.missing.some(name => !promptable.has(name))) {
         return { exitCode: 1, message: `setup-run: required params missing before execution: ${params.missing.join(', ')}` };
     }
-    const steps = selectedSteps(manifest, options);
     if (options.step && steps.length === 0)
         return { exitCode: 1, message: `setup-run: step '${options.step}' not found` };
     if (options.dryRun) {
@@ -1095,6 +1079,17 @@ export async function runSetupManifest(options) {
             message: `setup-run: refusing before executing any step:\n${blockers.map((b) => `  - ${b}`).join('\n')}`,
         };
     }
+    // Resolve required ask inputs before any scripts can consume them.
+    for (const step of askSteps) {
+        const missing = missingAskParams(step, params.values).filter(name => params.missing.includes(name));
+        if (!missing.length)
+            continue;
+        Object.assign(params.values, await promptForAskStep(step, missing));
+    }
+    const checked = resolveParams(manifest, { ...options, paramValues: { ...options.paramValues, ...params.values } });
+    if (checked.missing.length)
+        return { exitCode: 1, message: `setup-run: required params missing before execution: ${checked.missing.join(', ')}` };
+    Object.assign(params.values, checked.values);
     for (const step of steps) {
         const result = await runStep(step, manifest, validation.manifestDir, params.values, target.os, options.yes);
         if (!result.ok) {

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

@@ -476,6 +476,45 @@ export const setupHandler = {
     description: 'CLI helper for agent-led repository policy and tracker setup',
     category: 'project',
     aliases: [],
+    async help() {
+        return {
+            exitCode: 0,
+            rawOutput: true,
+            message: `Usage: aiwg setup project [options]
+
+Options:
+  --target <dir>                  Project directory
+  --yes                           Confirm writes without prompting
+  --dry-run                       Preview the setup plan
+  --non-interactive               Disable prompts
+  --json                          Emit the plan as JSON
+  --primary <remote>              Primary repository remote
+  --issue-tracker <remote>        Internal issue tracker remote
+  --customer-issue-tracker <remote>  Customer issue tracker remote
+  --ci <remote>                   CI remote
+  --issue-provider <provider>     Internal tracker provider
+  --customer-issue-provider <provider>  Customer tracker provider
+  --delivery-mode <mode>          Delivery policy
+  --default-branch <branch>        Default branch
+  --require-ci-green <boolean>    Require passing CI
+  --auto-close-issues <boolean>   Close delivered issues
+  --issue-comment-on-cycle <boolean>  Report issue cycles
+  --force-push-policy <policy>    Force-push policy
+  --require-signed-commits <boolean>  Require signed commits
+  --committer-name <name>         Committer identity
+  --committer-email <email>       Committer email
+  --signing-format <format>       Signing format
+  --signing-key <key>             Signing key
+  --signing-enforce <commits|tags|all>  Signing enforcement
+  --tracker-actor-login <login>   Internal tracker actor
+  --tracker-actor-via <via>       Internal tracker access method
+  --customer-tracker-actor-login <login>  Customer tracker actor
+  --customer-tracker-actor-via <via>  Customer tracker access method
+  --worker-dispatch <choice>      Worker dispatch policy
+  --providers <ids>               Comma-separated provider IDs
+`,
+        };
+    },
     async execute(ctx) {
         const [subcommand] = ctx.args;
         if (subcommand && subcommand !== 'project' && !subcommand.startsWith('--')) {
@@ -560,6 +599,8 @@ export const setupHandler = {
         }
         else {
             printPlan(plan);
+            if (options.workerDispatchChoice === 'enable')
+                ui.info('Next: aiwg doctor --probe-workers --qualify.');
             if (plan.workerDispatchOffer.shouldOffer) {
                 ui.info(workerDispatchOfferHintWithArg(plan.workerDispatchOffer.detected));
             }

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

@@ -204,6 +204,7 @@ async function handleSteward(args, ctx) {
   aiwg steward — Provider capability awareness and command routing
 
   Usage:
+    aiwg steward decision-offload [--json]         Offline advisory readiness and adoption report
     aiwg steward capabilities --provider <name>   Capabilities for a specific provider
     aiwg steward capabilities --feature <name>    Provider support matrix for a feature
     aiwg steward capabilities --all               Full matrix (all providers x features)
@@ -231,6 +232,16 @@ async function handleSteward(args, ctx) {
 `);
         return;
     }
+    if (subcommand === 'decision-offload') {
+        const unknown = args.slice(1).filter(arg => arg !== '--json');
+        if (unknown.length)
+            throw new AiwgError({ code: 'ERR_USAGE_UNKNOWN_ARGUMENT',
+                message: `Unknown decision-offload argument: ${unknown[0]}`, exitCode: EXIT_CODES.USAGE });
+        const { buildDecisionOffloadSnapshot } = await import('../../decision/offload.js');
+        const decisionOffload = await buildDecisionOffloadSnapshot({ projectRoot: ctx?.cwd ?? process.cwd(), frameworkRoot: ctx?.frameworkRoot });
+        console.log(JSON.stringify(args.includes('--json') ? { decisionOffload } : decisionOffload, null, 2));
+        return;
+    }
     if (subcommand === 'permissions') {
         const operation = args[1];
         // `<namespace> --help` must reach the same usage block bare invocation prints (#2533).