@aiwg/cli 2026.10.1 → 2026.10.4

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

@@ -2,7 +2,11 @@ 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 { 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, 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, SESSION_PROVIDER_IDS, SessionContractError, SessionRepository, SessionSourceSchema, StructuralCandidateExtractor, resolveMemoryConsumerManifest, assertSessionProviderId, acquireImportLease, defaultDiscoveryManifestPath, discoverWorkspaceHistories, 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 { 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');
@@ -33,10 +37,10 @@ Commands:
   grok-export <id> --workspace <path> --out <dir>  Export one CLI transcript
   grok-id <file> --format json|streaming-json  Read a headless session ID
   import <file> --source-id <id>  Import a supported provider JSONL source
-  list [--limit N] [--cursor N]   List normalized sessions
-  timeline [--gap 30m]            Report chronological activity segments
-  show <session-id>               Show a session with events and tags
-  search <query> --workspace <id> Search authorized normalized content
+  list [--workspace <path-or-id>] [--limit N] [--cursor N]  List normalized sessions
+  timeline [--workspace <path-or-id>] [--gap 30m]  Report chronological activity segments
+  show <session-id> [--workspace <path-or-id>]  Show a session with events and tags
+  search <query> [--workspace <path-or-id>]  Search authorized normalized content
   extract [session-id] --workspace <id> Extract structural candidates
   export plan --workspace <id> --out <file> <session-id...>  Select sessions into a reviewable plan
   export build --plan <file> --out <dir>  Build a Fortemi Knowledge Shard from a plan
@@ -47,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
@@ -59,20 +63,34 @@ Commands:
 Options:
   --json          Emit the versioned JSON contract
   --dry-run       Preview a mutation without changing state
-  --db <path>     Override .aiwg/sessions/catalog.sqlite
+  --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)
+                   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
   --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
+  --grokbot-root <path>  Explicitly authorize a Grok Bot sand-client-persistence root
+  --grok-bin <path>  Absolute Grok Build CLI path for grok-list/grok-search/grok-export
+                   (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
   --consumer <id> Select a named memory consumer for promotion
-  --workspace <id>, --tag <tag>, --limit <n>, --cursor <n>
+  --tag <tag>, --limit <n>, --cursor <n>
   --page-size <n>  Extraction scan page size (default 250, maximum 500)
   --max-documents <n>  Explicit extraction safety limit; returns a partial receipt
   --include-bytes  Embed registered-output bytes in session export shards
@@ -87,6 +105,12 @@ Search filters:
   Query syntax: FTS5 terms, quoted phrases, prefixes, AND/OR/NOT
   Follow the opaque nextCursor with the same query and filters
 
+Show identifiers:
+  Internal session_ IDs, exact provider-native IDs, or unique prefixes
+  Native IDs search the selected catalog unless --workspace is explicit
+  Internal session_ IDs retain the default workspace scope
+  Ambiguous IDs list candidates; select --workspace or an internal ID from list
+
 Analytics / forensics:
   --session <id>, --date-from <rfc3339>, --date-to <rfc3339>
   --actor <id>, --participant <id>, --tool <name>, --status <status>
@@ -94,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 };
@@ -120,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 };
@@ -132,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 };
@@ -141,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 };
@@ -151,8 +175,10 @@ export const sessionsHandler = {
 async function executeCommand(ctx, args) {
     const command = args.command;
     if (command === 'sources') {
-        const reports = [...SESSION_PROVIDER_IDS].sort().map(providerDisposition);
-        return ok(command, { providers: reports, count: reports.length });
+        const registry = createSessionAdapterRegistry();
+        const reports = registry.list().map((adapter) => providerDisposition(adapter.provider));
+        const preflight = coveragePreflight({ expectedProviders: requestedProviders(args), registry });
+        return ok(command, { providers: reports, count: reports.length, preflight });
     }
     if (command === 'import')
         return importSource(ctx, args);
@@ -198,7 +224,10 @@ async function executeCommand(ctx, args) {
                     limit,
                     cursor,
                 });
-                const coverage = repository.getCoverage(workspaceId);
+                const coverage = {
+                    ...repository.getCoverage(workspaceId),
+                    catalogScope: catalogScope(ctx, args, repository, workspaceId),
+                };
                 const response = {
                     items: result.items,
                     page: {
@@ -230,7 +259,10 @@ async function executeCommand(ctx, args) {
                 const { workspaceId } = readAuthorizationContext(ctx, args, command, repository);
                 const gapMs = timelineGap(args.values.get('--gap'));
                 const items = deriveSessionTimeline(repository.listTimelineInputs(workspaceId), gapMs);
-                const coverage = repository.getCoverage(workspaceId);
+                const coverage = {
+                    ...repository.getCoverage(workspaceId),
+                    catalogScope: catalogScope(ctx, args, repository, workspaceId),
+                };
                 const response = {
                     schemaVersion: '1.0.0',
                     workspaceId,
@@ -257,14 +289,33 @@ async function executeCommand(ctx, args) {
             }
             case 'show': {
                 const id = requiredPositional(args, 0, 'session-id');
-                const { workspaceId } = readAuthorizationContext(ctx, args, command, repository);
-                const session = repository.getSession(id, workspaceId);
+                const explicit = args.values.has('--workspace');
+                const catalogMatches = explicit ? undefined : repository.findSessionsByReference(id);
+                // Provider-native IDs and their prefixes may themselves start with
+                // session_. Exact internal IDs still take precedence.
+                const scoped = explicit || catalogMatches?.some((session) => session.sessionId === id)
+                    || (id.startsWith('session_')
+                        && !catalogMatches?.some((session) => session.nativeSessionId.startsWith(id)));
+                const workspaceId = scoped
+                    ? readAuthorizationContext(ctx, args, command, repository).workspaceId
+                    : projectRootCandidate(ctx.cwd) ?? normalizeWorkspaceId(ctx.cwd, '.');
+                const scope = catalogScope(ctx, args, repository, workspaceId);
+                // Native IDs identify provider transcripts across this local catalog.
+                // Explicit workspace selection and internal IDs retain workspace scope.
+                const matches = scoped ? repository.findSessionsByReference(id, workspaceId) : catalogMatches;
+                if (matches.length > 1) {
+                    throw new CliError('SESSION_AMBIGUOUS', `session reference is ambiguous: ${id}; candidates: ${matches.map((session) => `${session.sessionId} (provider=${session.provider}, workspace=${JSON.stringify(session.workspaceId)})`).join(', ')}; select --workspace or use an internal session ID from sessions list`, EXIT.usage, { catalogScope: scope, candidates: matches.map((session) => ({
+                            sessionId: session.sessionId, provider: session.provider, workspaceId: session.workspaceId,
+                        })) });
+                }
+                const session = matches[0];
                 if (!session)
-                    throw new CliError('SESSION_NOT_FOUND', `session not found: ${id}`, EXIT.unavailable);
+                    throw new CliError('SESSION_NOT_FOUND', `session not found: ${id}${scope.hint ? `; ${scope.hint}` : ''}`, EXIT.unavailable, { catalogScope: scope });
                 return ok(command, {
                     session,
-                    tags: repository.listTags(id, workspaceId),
-                    events: repository.listEvents(id, workspaceId),
+                    tags: repository.listTags(session.sessionId, session.workspaceId),
+                    events: repository.listEvents(session.sessionId, session.workspaceId),
+                    catalogScope: catalogScope(ctx, args, repository, session.workspaceId),
                 });
             }
             case 'search': {
@@ -292,6 +343,7 @@ async function executeCommand(ctx, args) {
                 });
                 return ok(command, {
                     items: result.items,
+                    catalogScope: catalogScope(ctx, args, repository, workspaceId),
                     page: { limit: boundedInteger(args.values.get('--limit'), 50, 1, 500, '--limit'),
                         nextCursor: result.nextCursor },
                 });
@@ -546,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);
@@ -677,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);
@@ -700,6 +764,8 @@ async function importSource(ctx, args) {
     const isOpenClaw = provider === 'openclaw';
     const isOpenHuman = provider === 'openhuman';
     const isGrokbot = provider === 'grokbot';
+    const isGrokbotNative = isGrokbot
+        && classifyGrokbotBlobName(basename(input))?.kind === 'transcript-replica';
     const isGrokBuild = provider === 'grok-build';
     const isMuse = provider === 'muse';
     const isPi = provider === 'pi';
@@ -707,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
@@ -757,7 +823,7 @@ async function importSource(ctx, args) {
                                     : isOpenHuman
                                         ? 'openhuman-enriched-jsonl'
                                         : isGrokbot
-                                            ? 'manual-export'
+                                            ? (isGrokbotNative ? GROKBOT_NATIVE_REPLICA_LOCATOR_CLASS : 'manual-export')
                                             : isGrokBuild
                                                 ? GROK_BUILD_CLI_EXPORT_LOCATOR_CLASS
                                                 : isMuse
@@ -774,6 +840,7 @@ async function importSource(ctx, args) {
         authorizedScope: { workspaceId, allowedRoots: [dirname(input)] },
     };
     const probe = await adapter.inspect(selectedSource);
+    const workspaceReport = importWorkspaceReport(workspaceId, args.values.has('--workspace'), probe);
     const source = SessionSourceSchema.parse({
         contractVersion: SESSION_CONTRACT_VERSION, sourceId, provider,
         providerProfile: isDsh ? 'native-session-v2-jsonl' : isOmp ? 'native-title-slot-v3' : isClaude
@@ -795,7 +862,7 @@ async function importSource(ctx, args) {
                                         : isOpenHuman
                                             ? 'schema-1-session-raw-enriched'
                                             : isGrokbot
-                                                ? 'manual-interchange'
+                                                ? (isGrokbotNative ? 'grokbot-native-transcript-replica-v1' : 'manual-interchange')
                                                 : isGrokBuild
                                                     ? 'documented-cli-markdown-export'
                                                     : isMuse
@@ -836,10 +903,10 @@ async function importSource(ctx, args) {
                                                                 ? DEVIN_DESKTOP_ADAPTER_VERSION
                                                                 : GENERIC_ADAPTER_VERSION,
         sourceSchemaVersion: probe.sourceSchemaVersion,
-        disposition: isWarp || isGrokbot || isMuse
+        disposition: isWarp || (isGrokbot && !isGrokbotNative) || isMuse
             ? 'manual-only'
             : isClaude || isCodex || isCopilot || isCursor || isFactory || isHermes
-                || isOpenCode || isOpenClaw || isOpenHuman || isGrokBuild || isDevinDesktop || isOmp || isDsh || isPi
+                || isOpenCode || isOpenClaw || isOpenHuman || isGrokbotNative || isGrokBuild || isDevinDesktop || isOmp || isDsh || isPi
                 ? 'implemented' : 'manual-only',
         operationalState: probe.operationalState,
         consistency: probe.consistency, authorizedAt: new Date().toISOString(),
@@ -877,7 +944,7 @@ async function importSource(ctx, args) {
                                                                 : { 'native.generic': {} },
     });
     if (isDryRun(ctx, args)) {
-        return preview('import', { source, wouldInspect: true, wouldPersist: false });
+        return preview('import', { source, ...workspaceReport, wouldInspect: true, wouldPersist: false });
     }
     const lease = await acquireImportLease(databasePath(ctx, args), sha256(['single-source-import', sourceId, workspaceId].join('\0')), {
         waitMs: boundedInteger(args.values.get('--lock-wait-ms'), 5_000, 0, 300_000, '--lock-wait-ms'),
@@ -885,13 +952,18 @@ 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)
+                console.error(`WARNING ${warning}`);
             return ok('import', {
                 sourceId,
+                ...workspaceReport,
                 receipts,
+                interruptedRuns,
                 totals: {
                     sessionsInserted: receipts.reduce((sum, item) => sum + item.sessionsInserted, 0),
                     eventsInserted: receipts.reduce((sum, item) => sum + item.eventsInserted, 0),
@@ -906,6 +978,24 @@ async function importSource(ctx, args) {
         await lease.release();
     }
 }
+/**
+ * Report which catalog workspace an import uses (#2967). A source-declared
+ * workspace is provenance only; it never selects the authorization scope.
+ */
+function importWorkspaceReport(workspaceId, fromArgument, probe) {
+    const warnings = [];
+    const declared = probe.declaredWorkspaceId;
+    if (declared !== undefined && declared !== workspaceId) {
+        warnings.push(`source declares workspace "${declared}" but sessions are imported into "${workspaceId}"`
+            + `${fromArgument ? '' : ' (no --workspace given)'}; pass --workspace to choose the catalog workspace`);
+    }
+    return {
+        workspaceId,
+        workspaceSource: fromArgument ? 'argument' : 'default',
+        ...(declared === undefined ? {} : { declaredWorkspaceId: declared }),
+        warnings,
+    };
+}
 /**
  * `aiwg sessions export {plan,build,verify,unpack}` (#2564). Sub-verb after
  * `export`, matching the issue's proposed shape:
@@ -1166,8 +1256,16 @@ 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'))
             : undefined,
@@ -1177,11 +1275,13 @@ async function discoverWorkspace(ctx, args) {
             ? resolve(ctx.cwd, args.values.get('--muse-root')) : undefined,
         dshRoot: args.values.has('--dsh-root')
             ? resolve(ctx.cwd, args.values.get('--dsh-root')) : undefined,
-        codexRoot: args.values.has('--codex-root')
-            ? resolve(ctx.cwd, args.values.get('--codex-root'))
-            : undefined,
+        grokbotRoot: args.values.has('--grokbot-root')
+            ? resolve(ctx.cwd, args.values.get('--grokbot-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),
@@ -1196,11 +1296,18 @@ 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) {
         throw new CliError('MANIFEST_WORKSPACE_MISMATCH', 'discovery manifest does not belong to the explicitly authorized workspace', EXIT.contract);
     }
+    const expected = requestedProviders(args);
+    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');
+    }
     const confirmed = args.flags.has('--confirm') || args.flags.has('--yes');
     if (isDryRun(ctx, args) || !confirmed) {
         let existing = null;
@@ -1214,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,
         });
@@ -1225,16 +1332,25 @@ 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,
                 resumable: receipt.run.status !== 'complete',
+                catalog: {
+                    database: databasePath(ctx, args),
+                    workspaceId: manifest.workspaceId,
+                    hint: `Read these sessions from either directory with aiwg sessions list --workspace ${JSON.stringify(manifest.workspaceId)} --db ${JSON.stringify(databasePath(ctx, args))}`,
+                },
             });
         }
         finally {
@@ -1414,14 +1530,16 @@ function providerDisposition(provider) {
     }
     if (provider === 'grokbot') {
         return {
-            provider, disposition: 'manual-only', operationalState: 'available',
-            supportedOperations: ['inspect', 'stream'],
-            acquisitionModes: ['manual-export'],
-            reasonCode: 'MANUAL_SOURCE_SELECTION_REQUIRED',
-            remediation: 'Select an authorized AIWG session interchange export; Grok Bot auto-discover is unsupported until a native locator exists.',
+            provider, disposition: 'implemented', operationalState: 'available',
+            supportedOperations: ['discover', 'inspect', 'stream'],
+            acquisitionModes: ['manual-export', 'jsonl'],
+            reasonCode: null,
+            remediation: 'Import an explicit AIWG session interchange export, or pass --grokbot-root with an '
+                + 'explicitly authorized $XDG_CONFIG_HOME/Grok Bot/sand-client-persistence root (Linux only) for '
+                + 'evidence-gated native discovery.',
             evidence: {
                 adapterVersion: GROKBOT_ADAPTER_VERSION,
-                verifiedAt: '2026-09-15',
+                verifiedAt: '2026-10-09',
                 documentation: 'docs/providers/grokbot-sessions.md',
             },
         };
@@ -1432,7 +1550,7 @@ function providerDisposition(provider) {
             supportedOperations: ['inspect', 'stream'],
             acquisitionModes: ['manual-export'],
             reasonCode: 'CLI_EXPORT_REQUIRED',
-            remediation: 'Run `grok sessions list`, then `grok export <session-id> <session-id>.md` and import the explicitly authorized Markdown file.',
+            remediation: 'Run `grok sessions list`, then `grok export <session-id> <session-id>.md` and import the explicitly authorized Markdown file. `aiwg sessions grok-list` finds `grok` on PATH or in $GROK_HOME/bin; pass --grok-bin <absolute path> otherwise.',
             evidence: {
                 adapterVersion: GROK_BUILD_ADAPTER_VERSION,
                 verifiedAt: '2026-09-21',
@@ -1550,11 +1668,41 @@ function openRepository(ctx, args) {
 function databasePath(ctx, args) {
     if (args.values.has('--db'))
         return resolve(ctx.cwd, args.values.get('--db'));
-    return resolve(projectRootCandidate(ctx.cwd) ?? ctx.cwd, '.aiwg/sessions/catalog.sqlite');
+    return resolve(projectRootCandidate(ctx.cwd) ?? normalizeWorkspaceId(ctx.cwd, '.'), '.aiwg/sessions/catalog.sqlite');
+}
+function catalogScope(ctx, args, repository, workspaceId) {
+    const workspaces = repository.listWorkspaceSessionCounts();
+    const otherWorkspaces = workspaces.filter((workspace) => workspace.workspaceId !== workspaceId);
+    const database = databasePath(ctx, args);
+    return {
+        database,
+        workspaceId,
+        total: workspaces.reduce((total, workspace) => total + workspace.count, 0),
+        otherWorkspaces,
+        hint: otherWorkspaces.length
+            ? `Other workspaces in this catalog: ${otherWorkspaces.map((workspace) => `${JSON.stringify(workspace.workspaceId)} (${workspace.count} sessions)`).join(', ')}. Select one with --workspace <path-or-id>; from another directory also pass --db ${JSON.stringify(database)}.`
+            : 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',
@@ -1562,8 +1710,8 @@ 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', '--lock-wait-ms', '--min-coverage', '--gap',
-        '--inactivity-threshold',
+        '--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',
         '--out', '--plan', '--input', '--shard-name', '--max-attachment-bytes', '--format', '--grok-bin',
@@ -1577,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('-')) {
@@ -1589,7 +1741,11 @@ 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');
+    return value === undefined ? undefined : expectedSessionProviders(value.split(','));
 }
 function requiredPositional(args, index, name) {
     const value = args.positionals[index];
@@ -1634,6 +1790,16 @@ function readAuthorizationContext(ctx, args, operation, repository) {
         };
     }
     const candidates = repository.listWorkspaceIds();
+    const current = normalizeWorkspaceId(ctx.cwd, '.');
+    if (candidates.includes(current) || candidates.length === 0) {
+        return {
+            actorId: 'local-catalog-owner',
+            workspaceId: current,
+            operation,
+            catalogScope: 'workspace',
+            mode: 'local-owner',
+        };
+    }
     if (candidates.length === 1) {
         return {
             actorId: 'local-catalog-owner',
@@ -1643,15 +1809,9 @@ function readAuthorizationContext(ctx, args, operation, repository) {
             mode: 'local-owner',
         };
     }
-    if (candidates.length > 1) {
-        throw new CliError('WORKSPACE_AMBIGUOUS', 'current workspace cannot be inferred safely; pass --workspace explicitly', EXIT.usage, {
-            candidates,
-            example: `aiwg sessions ${operation} --workspace ${JSON.stringify(candidates[0])}`,
-        });
-    }
-    throw new CliError('WORKSPACE_REQUIRED', 'current workspace cannot be inferred; pass --workspace explicitly', EXIT.usage, {
-        candidates: [],
-        example: `aiwg sessions ${operation} --workspace <path-or-id>`,
+    throw new CliError('WORKSPACE_AMBIGUOUS', 'current workspace cannot be inferred safely; pass --workspace explicitly', EXIT.usage, {
+        candidates,
+        example: `aiwg sessions ${operation} --workspace ${JSON.stringify(candidates[0])}`,
     });
 }
 function projectRootCandidate(start) {
@@ -1857,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')
@@ -1885,6 +2050,8 @@ function printHuman(value) {
             ].join(' '));
         }
         console.log(`Coverage: ${data.coverage?.status ?? 'unknown'}`);
+        if (data.coverage?.catalogScope?.hint)
+            console.log(data.coverage.catalogScope.hint);
         return;
     }
     console.log(JSON.stringify(value.data, null, 2));
@@ -1909,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 {