@aiwg/cli 2026.9.12 → 2026.9.16

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

@@ -1,7 +1,8 @@
-import { existsSync, mkdirSync, realpathSync, statSync, } from 'node:fs';
-import { dirname, isAbsolute, resolve, } from 'node:path';
+import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+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, 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, } 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, GrokbotSessionAdapter, 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';
 const JSON_CONTRACT_VERSION = '1.0.0';
 async function createLineMemoryPromotionDestination(projectRoot, manifestPath) {
     const modulePath = resolve(dirname(manifestPath), 'commands', 'line-memory.mjs');
@@ -33,6 +34,10 @@ Commands:
   show <session-id>               Show a session with events and tags
   search <query> --workspace <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
+  export verify --input <shard>   Validate a shard and its receipt
+  export unpack --input <shard> --out <dir>  Recover a shard's records to disk
   candidates [--state <state>]    List the candidate review queue
   review <id> <version> <state>   Record an explicit review transition
   promote <id> <version>          Preview promotion; use --confirm to write
@@ -65,6 +70,9 @@ Options:
   --workspace <id>, --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
+  --max-attachment-bytes <n>  Maximum bytes per embedded output (default 67108864)
+  --force         Permit replacing an existing export or recovery output
 
 Search filters:
   --date-from <rfc3339>, --date-to <rfc3339>
@@ -409,6 +417,7 @@ async function executeCommand(ctx, args) {
                     ? preview(command, { items, count: items.length, durableMemoryWrites: 0, scan })
                     : ok(command, { items, count: items.length, durableMemoryWrites: 0, scan });
             }
+            case 'export': return exportCommand(ctx, args, repository);
             case 'candidates': {
                 const { workspaceId } = readAuthorizationContext(ctx, args, command, repository);
                 const state = candidateState(args.values.get('--state'));
@@ -647,7 +656,7 @@ async function importSource(ctx, args) {
     if (provider !== 'generic' && provider !== 'claude' && provider !== 'codex'
         && provider !== 'copilot' && provider !== 'cursor' && provider !== 'factory'
         && provider !== 'hermes' && provider !== 'opencode' && provider !== 'openclaw'
-        && provider !== 'openhuman' && provider !== 'pi' && provider !== 'omp' && provider !== 'deepseek-harness' && provider !== 'warp' && provider !== 'devin-desktop') {
+        && provider !== 'openhuman' && provider !== 'grokbot' && provider !== 'pi' && provider !== 'omp' && provider !== 'deepseek-harness' && provider !== 'warp' && provider !== 'devin-desktop') {
         throw new CliError('UNSUPPORTED_OPERATION', `session import is not implemented for ${provider}`, EXIT.unsupported);
     }
     const sourceId = requiredValue(args, '--source-id');
@@ -663,6 +672,7 @@ async function importSource(ctx, args) {
     const isOpenCode = provider === 'opencode';
     const isOpenClaw = provider === 'openclaw';
     const isOpenHuman = provider === 'openhuman';
+    const isGrokbot = provider === 'grokbot';
     const isPi = provider === 'pi';
     const isOmp = provider === 'omp';
     const isDsh = provider === 'deepseek-harness';
@@ -686,15 +696,17 @@ async function importSource(ctx, args) {
                                     ? new OpenClawSessionAdapter()
                                     : isOpenHuman
                                         ? new OpenHumanSessionAdapter()
-                                        : isPi
-                                            ? new PiSessionAdapter()
-                                            : isWarp
-                                                ? new WarpSessionAdapter()
-                                                : isDevinDesktop
-                                                    ? new DevinDesktopSessionAdapter()
-                                                    : new GenericSessionInterchangeAdapter();
+                                        : isGrokbot
+                                            ? new GrokbotSessionAdapter()
+                                            : isPi
+                                                ? new PiSessionAdapter()
+                                                : isWarp
+                                                    ? new WarpSessionAdapter()
+                                                    : isDevinDesktop
+                                                        ? new DevinDesktopSessionAdapter()
+                                                        : new GenericSessionInterchangeAdapter();
     const locatorClass = isDsh ? 'deepseek-harness-session-v2-jsonl' : isOmp ? 'omp-session-v3-jsonl' : isClaude
-        ? (input.endsWith('.hooks.jsonl') ? 'claude-hook-jsonl' : 'claude-transcript-jsonl')
+        ? claudeLocatorClass(input)
         : isCodex
             ? (input.endsWith('.app-server.jsonl') ? 'codex-app-server-jsonl' : 'codex-rollout-jsonl')
             : isCopilot
@@ -711,13 +723,15 @@ async function importSource(ctx, args) {
                                     ? 'openclaw-consistent-snapshot-jsonl'
                                     : isOpenHuman
                                         ? 'openhuman-enriched-jsonl'
-                                        : isPi
-                                            ? 'pi-session-v3-jsonl'
-                                            : isWarp
-                                                ? 'warp-markdown-export'
-                                                : isDevinDesktop
-                                                    ? 'devin-desktop-cascade-hook-jsonl'
-                                                    : 'manual-export';
+                                        : isGrokbot
+                                            ? 'manual-export'
+                                            : isPi
+                                                ? 'pi-session-v3-jsonl'
+                                                : isWarp
+                                                    ? 'warp-markdown-export'
+                                                    : isDevinDesktop
+                                                        ? 'devin-desktop-cascade-hook-jsonl'
+                                                        : 'manual-export';
     const selectedSource = {
         provider, locator: input, locatorClass, sourceId,
         authorizedScope: { workspaceId, allowedRoots: [dirname(input)] },
@@ -726,7 +740,7 @@ async function importSource(ctx, args) {
     const source = SessionSourceSchema.parse({
         contractVersion: SESSION_CONTRACT_VERSION, sourceId, provider,
         providerProfile: isDsh ? 'native-session-v2-jsonl' : isOmp ? 'native-title-slot-v3' : isClaude
-            ? 'documented-local-jsonl'
+            ? claudeProviderProfile(locatorClass)
             : isCodex
                 ? 'app-server-v2-rollout-fallback'
                 : isCopilot
@@ -743,11 +757,13 @@ async function importSource(ctx, args) {
                                         ? 'schema-16-event-v3-consistent-snapshot'
                                         : isOpenHuman
                                             ? 'schema-1-session-raw-enriched'
-                                            : isWarp
-                                                ? 'manual-lossy-markdown-export'
-                                                : isDevinDesktop
-                                                    ? 'opt-in-cascade-transcript-hook'
-                                                    : 'manual-interchange',
+                                            : isGrokbot
+                                                ? 'manual-interchange'
+                                                : isWarp
+                                                    ? 'manual-lossy-markdown-export'
+                                                    : isDevinDesktop
+                                                        ? 'opt-in-cascade-transcript-hook'
+                                                        : 'manual-interchange',
         locatorClass, redactedLocator: redactSourceLocator(input),
         adapterVersion: isDsh ? DEEPSEEK_HARNESS_ADAPTER_VERSION : isOmp ? OMP_ADAPTER_VERSION : isClaude
             ? CLAUDE_ADAPTER_VERSION
@@ -767,13 +783,15 @@ async function importSource(ctx, args) {
                                         ? OPENCLAW_ADAPTER_VERSION
                                         : isOpenHuman
                                             ? OPENHUMAN_ADAPTER_VERSION
-                                            : isWarp
-                                                ? WARP_ADAPTER_VERSION
-                                                : isDevinDesktop
-                                                    ? DEVIN_DESKTOP_ADAPTER_VERSION
-                                                    : GENERIC_ADAPTER_VERSION,
+                                            : isGrokbot
+                                                ? GROKBOT_ADAPTER_VERSION
+                                                : isWarp
+                                                    ? WARP_ADAPTER_VERSION
+                                                    : isDevinDesktop
+                                                        ? DEVIN_DESKTOP_ADAPTER_VERSION
+                                                        : GENERIC_ADAPTER_VERSION,
         sourceSchemaVersion: probe.sourceSchemaVersion,
-        disposition: isWarp
+        disposition: isWarp || isGrokbot
             ? 'manual-only'
             : isClaude || isCodex || isCopilot || isCursor || isFactory || isHermes
                 || isOpenCode || isOpenClaw || isOpenHuman || isDevinDesktop || isOmp || isDsh || isPi
@@ -798,14 +816,16 @@ async function importSource(ctx, args) {
                                         ? { 'native.openclaw': {} }
                                         : isOpenHuman
                                             ? { 'native.openhuman': {} }
-                                            : isWarp
-                                                ? { 'native.warp': {} }
-                                                : isDevinDesktop
-                                                    ? { 'native.devin-desktop': {
-                                                            product: 'Devin Desktop',
-                                                            compatibilityProviderId: 'windsurf',
-                                                        } }
-                                                    : { 'native.generic': {} },
+                                            : isGrokbot
+                                                ? { 'native.grokbot': {} }
+                                                : isWarp
+                                                    ? { 'native.warp': {} }
+                                                    : isDevinDesktop
+                                                        ? { 'native.devin-desktop': {
+                                                                product: 'Devin Desktop',
+                                                                compatibilityProviderId: 'windsurf',
+                                                            } }
+                                                        : { 'native.generic': {} },
     });
     if (isDryRun(ctx, args)) {
         return preview('import', { source, wouldInspect: true, wouldPersist: false });
@@ -837,6 +857,264 @@ async function importSource(ctx, args) {
         await lease.release();
     }
 }
+/**
+ * `aiwg sessions export {plan,build,verify,unpack}` (#2564). Sub-verb after
+ * `export`, matching the issue's proposed shape:
+ *   export plan --workspace ID --out selection.json SESSION_ID...
+ *   export build --plan selection.json --out DIRECTORY
+ *   export verify --input evidence.shard
+ *   export unpack --input evidence.shard --out DIRECTORY
+ */
+async function exportCommand(ctx, args, repository) {
+    const subVerb = requiredPositional(args, 0, 'export sub-command (plan|build|verify|unpack)');
+    const command = `export.${subVerb}`;
+    if (subVerb === 'plan')
+        return exportPlan(ctx, args, repository, command);
+    if (subVerb === 'build')
+        return exportBuild(ctx, args, repository, command);
+    if (subVerb === 'verify')
+        return exportVerify(ctx, args, command);
+    if (subVerb === 'unpack')
+        return exportUnpack(ctx, args, command);
+    throw new CliError('UNKNOWN_COMMAND', `unknown export sub-command: ${subVerb}`, EXIT.usage);
+}
+function exportPlan(ctx, args, repository, command) {
+    const workspaceId = normalizeWorkspaceId(ctx.cwd, requiredValue(args, '--workspace'));
+    const out = resolve(ctx.cwd, requiredValue(args, '--out'));
+    const flagSelection = args.values.get('--session')?.split(',').map((value) => value.trim()).filter(Boolean) ?? [];
+    const sessionIds = [...new Set([...flagSelection, ...args.positionals.slice(1)])];
+    const { plan } = buildSessionExportPlan(repository, { workspaceId, sessionIds, projectRoot: ctx.cwd });
+    mkdirSync(dirname(out), { recursive: true, mode: 0o700 });
+    writeFileSync(out, `${JSON.stringify(plan, null, 2)}\n`, { mode: 0o600 });
+    return ok(command, {
+        plan: out,
+        totals: plan.totals,
+        sessions: plan.sessions.map((entry) => entry.sessionId),
+        outputs: plan.outputs.length,
+    });
+}
+async function exportBuild(ctx, args, repository, command) {
+    const planPath = resolve(ctx.cwd, requiredValue(args, '--plan'));
+    const outDirectory = resolve(ctx.cwd, requiredValue(args, '--out'));
+    const shardName = args.values.get('--shard-name') ?? 'evidence.shard';
+    if (basename(shardName) !== shardName) {
+        throw new CliError('INVALID_ARGUMENT', '--shard-name must be a filename, not a path', EXIT.usage);
+    }
+    const finalPath = join(outDirectory, shardName);
+    const receiptPath = `${finalPath}.receipt.json`;
+    if (!args.flags.has('--force') && (existsSync(finalPath) || existsSync(receiptPath))) {
+        throw new CliError('OUTPUT_EXISTS', `refusing to overwrite an existing shard or receipt: ${finalPath} (use --force to replace)`, EXIT.usage);
+    }
+    let plan;
+    try {
+        plan = JSON.parse(readFileSync(planPath, 'utf8'));
+    }
+    catch {
+        throw new CliError('MALFORMED_SOURCE', `plan file is not readable JSON: ${planPath}`, EXIT.usage);
+    }
+    if (plan.schemaVersion !== SESSION_EXPORT_PLAN_SCHEMA_VERSION) {
+        throw new CliError('UNKNOWN_SCHEMA_MAJOR', `plan schemaVersion ${plan.schemaVersion} is not supported by this build (expected ${SESSION_EXPORT_PLAN_SCHEMA_VERSION})`, EXIT.contract);
+    }
+    // Recheck source changes before writing (#2564 acceptance criteria):
+    // re-select from the live repository and reject on any digest drift.
+    const { sessions, eventsBySessionId, catalogTagsBySessionId, outputBytesByRegistrationId, attachmentBytesByEventId, } = reverifySessionExportPlan(repository, plan, { projectRoot: ctx.cwd });
+    const includeBytes = args.flags.has('--include-bytes');
+    const outputs = plan.outputs.map((output) => ({
+        ...output,
+        bytesEmbedded: includeBytes && outputBytesByRegistrationId.has(output.registrationId),
+    }));
+    const index = buildSessionAiwgFortemiIndexExport(plan.workspaceId, sessions, eventsBySessionId, outputs, catalogTagsBySessionId);
+    // aiwgFortemiIndexToKnowledgeShardWithReport targets the declared
+    // full-v1/2.0.0 archive contract and validates losslessness -- unlike the
+    // plain aiwgFortemiIndexToKnowledgeShard (core-v1), which silently embeds
+    // the whole input record as opaque note metadata regardless of whether it
+    // maps to any native component. The mapping in fortemi-export-mapping.ts
+    // was built specifically so every AIWG-specific field lands in a real
+    // full-v1 component (tags, provenance_events) rather than being smuggled
+    // through as an unmapped blob.
+    const { aiwgFortemiIndexToKnowledgeShardWithReport } = await import('@fortemi/core');
+    const result = await aiwgFortemiIndexToKnowledgeShardWithReport(index);
+    if (!result.success || !result.archive) {
+        throw new CliError('MALFORMED_SOURCE', `full-v1 shard conversion failed: ${JSON.stringify(result.losses)}`, EXIT.contract);
+    }
+    let bytes = result.archive;
+    let embeddedAttachmentCount = 0;
+    let embeddedAttachmentBytes = 0;
+    if (includeBytes) {
+        const maximum = Number(args.values.get('--max-attachment-bytes') ?? 64 * 1024 * 1024);
+        if (!Number.isSafeInteger(maximum) || maximum <= 0) {
+            throw new CliError('INVALID_ARGUMENT', '--max-attachment-bytes must be a positive integer', EXIT.usage);
+        }
+        const attachments = plan.outputs.map((output) => {
+            const content = outputBytesByRegistrationId.get(output.registrationId);
+            if (content.length > maximum) {
+                throw new CliError('SOURCE_TOO_LARGE', `registered output exceeds --max-attachment-bytes: ${output.outputLocator}`, EXIT.contract);
+            }
+            return {
+                recordId: `output_${output.registrationId}`,
+                attachmentId: randomUUID(),
+                filename: basename(output.outputLocator),
+                mimeType: output.mediaType,
+                bytes: content,
+            };
+        });
+        for (const attachment of plan.attachments ?? []) {
+            const content = attachmentBytesByEventId.get(attachment.eventId);
+            if (content.length > maximum) {
+                throw new CliError('SOURCE_TOO_LARGE', `session attachment exceeds --max-attachment-bytes: ${attachment.filename}`, EXIT.contract);
+            }
+            attachments.push({
+                recordId: attachment.eventId,
+                attachmentId: randomUUID(),
+                filename: basename(attachment.filename),
+                mimeType: attachment.mediaType,
+                bytes: content,
+            });
+        }
+        embeddedAttachmentCount = attachments.length;
+        embeddedAttachmentBytes = attachments.reduce((sum, attachment) => sum + attachment.bytes.length, 0);
+        bytes = await embedAttachmentsInFullV1Shard(bytes, attachments);
+    }
+    mkdirSync(outDirectory, { recursive: true, mode: 0o700 });
+    // Interrupted writes must never be mistaken for a completed export: write
+    // to a sibling temp file, then rename (atomic on the same filesystem), and
+    // only then write the receipt -- the receipt's existence is the completion
+    // signal, not the shard file's.
+    const tempPath = join(outDirectory, `.${shardName}.${randomUUID()}.tmp`);
+    writeFileSync(tempPath, bytes, { mode: 0o600 });
+    if (args.flags.has('--force'))
+        renameSync(tempPath, finalPath);
+    else {
+        try {
+            linkSync(tempPath, finalPath);
+            unlinkSync(tempPath);
+        }
+        catch (error) {
+            if (existsSync(tempPath))
+                unlinkSync(tempPath);
+            throw new CliError('OUTPUT_EXISTS', `refusing to overwrite an existing shard: ${finalPath}`, EXIT.usage, error);
+        }
+    }
+    const readBack = readFileSync(finalPath);
+    const shardDigest = sha256(readBack);
+    if (readBack.length !== bytes.length) {
+        throw new CliError('IMPORT_INTERRUPTED', 'shard readback size did not match the written archive', EXIT.storage);
+    }
+    const receipt = {
+        schemaVersion: '1.0.0',
+        generatedAt: new Date().toISOString(),
+        workspaceId: plan.workspaceId,
+        planGeneratedAt: plan.generatedAt,
+        sessionIds: plan.sessions.map((entry) => entry.sessionId),
+        totals: plan.totals,
+        indexSchemaVersion: index.schema_version,
+        archiveProfile: result.profile,
+        archiveSchemaVersion: result.schema_version,
+        lossless: result.lossless,
+        losses: result.losses,
+        fortemiReceipt: result.receipt,
+        shardFile: shardName,
+        shardDigest,
+        shardBytes: readBack.length,
+        embeddedAttachmentCount,
+        embeddedAttachmentBytes,
+    };
+    writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`, {
+        mode: 0o600,
+        flag: args.flags.has('--force') ? 'w' : 'wx',
+    });
+    return ok(command, { shard: finalPath, receipt: receiptPath, ...receipt });
+}
+async function exportVerify(ctx, args, command) {
+    const input = resolve(ctx.cwd, requiredValue(args, '--input'));
+    let bytes;
+    try {
+        bytes = readFileSync(input);
+    }
+    catch {
+        throw new CliError('SOURCE_NOT_AUTHORIZED', `shard file is not readable: ${input}`, EXIT.usage);
+    }
+    let recovered;
+    let embeddedAttachments;
+    try {
+        recovered = recoverAiwgFortemiIndexFromFullV1Shard(bytes);
+        embeddedAttachments = recoverEmbeddedAttachments(bytes);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CliError('MALFORMED_SOURCE', `shard failed validation: ${message}`, EXIT.contract);
+    }
+    const shardDigest = sha256(bytes);
+    const receiptPath = `${input}.receipt.json`;
+    let receiptMatches = null;
+    if (existsSync(receiptPath)) {
+        try {
+            const receipt = JSON.parse(readFileSync(receiptPath, 'utf8'));
+            receiptMatches = receipt.shardDigest === shardDigest && receipt.shardBytes === bytes.length;
+        }
+        catch {
+            receiptMatches = false;
+        }
+    }
+    return ok(command, {
+        valid: true,
+        schemaVersion: recovered.schema_version,
+        itemCount: recovered.items.length,
+        shardDigest,
+        shardBytes: bytes.length,
+        receiptChecked: existsSync(receiptPath),
+        receiptMatches,
+        embeddedAttachmentCount: embeddedAttachments.length,
+    });
+}
+async function exportUnpack(ctx, args, command) {
+    const input = resolve(ctx.cwd, requiredValue(args, '--input'));
+    const outDirectory = resolve(ctx.cwd, requiredValue(args, '--out'));
+    let bytes;
+    try {
+        bytes = readFileSync(input);
+    }
+    catch {
+        throw new CliError('SOURCE_NOT_AUTHORIZED', `shard file is not readable: ${input}`, EXIT.usage);
+    }
+    let recovered;
+    try {
+        recovered = recoverAiwgFortemiIndexFromFullV1Shard(bytes);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CliError('MALFORMED_SOURCE', `shard failed validation: ${message}`, EXIT.contract);
+    }
+    const attachments = recoverEmbeddedAttachments(bytes);
+    mkdirSync(outDirectory, { recursive: true, mode: 0o700 });
+    const finalPath = join(outDirectory, 'index.json');
+    if (!args.flags.has('--force') && existsSync(finalPath)) {
+        throw new CliError('OUTPUT_EXISTS', `refusing to overwrite recovered output: ${finalPath}`, EXIT.usage);
+    }
+    const attachmentPaths = attachments.map((attachment) => join(outDirectory, 'attachments', attachment.recordId, basename(attachment.filename)));
+    if (!args.flags.has('--force')) {
+        const conflict = attachmentPaths.find((attachmentPath) => existsSync(attachmentPath));
+        if (conflict)
+            throw new CliError('OUTPUT_EXISTS', `refusing to overwrite recovered attachment: ${conflict}`, EXIT.usage);
+    }
+    const tempPath = join(outDirectory, `.index.json.${randomUUID()}.tmp`);
+    writeFileSync(tempPath, `${JSON.stringify(recovered, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tempPath, finalPath);
+    for (const [index, attachment] of attachments.entries()) {
+        const attachmentDirectory = join(outDirectory, 'attachments', attachment.recordId);
+        mkdirSync(attachmentDirectory, { recursive: true, mode: 0o700 });
+        writeFileSync(attachmentPaths[index], attachment.bytes, { mode: 0o600 });
+    }
+    return ok(command, {
+        index: finalPath,
+        schemaVersion: recovered.schema_version,
+        itemCount: recovered.items.length,
+        sessionRecordCount: recovered.items.filter((item) => item.type === 'aiwg.session').length,
+        eventRecordCount: recovered.items.filter((item) => item.type === 'aiwg.session-event').length,
+        recoveredAttachmentCount: attachments.length,
+        recoveredAttachmentBytes: attachments.reduce((sum, attachment) => sum + attachment.bytes.length, 0),
+    });
+}
 async function discoverWorkspace(ctx, args) {
     const workspace = resolve(ctx.cwd, requiredValue(args, '--workspace'));
     const manifest = await discoverWorkspaceHistories({
@@ -935,12 +1213,13 @@ function providerDisposition(provider) {
         return {
             provider, disposition: 'implemented', operationalState: 'available',
             supportedOperations: ['discover', 'inspect', 'stream'],
-            acquisitionModes: ['jsonl', 'hook'],
+            acquisitionModes: ['jsonl', 'hook', 'manual-export'],
             reasonCode: null,
-            remediation: 'Authorize a Claude projects or hook root, then import an explicit JSONL file.',
+            remediation: 'Authorize a Claude projects or hook root and import a JSONL file, '
+                + 'or import an explicitly selected Claude web/account conversations.json export.',
             evidence: {
                 adapterVersion: CLAUDE_ADAPTER_VERSION,
-                verifiedAt: '2026-07-27',
+                verifiedAt: '2026-09-15',
                 documentation: 'https://code.claude.com/docs/en/sessions',
             },
         };
@@ -1082,6 +1361,20 @@ 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.',
+            evidence: {
+                adapterVersion: GROKBOT_ADAPTER_VERSION,
+                verifiedAt: '2026-09-15',
+                documentation: 'docs/providers/grokbot-sessions.md',
+            },
+        };
+    }
     if (provider === 'warp') {
         return {
             provider, disposition: 'manual-only', operationalState: 'available',
@@ -1131,6 +1424,18 @@ function providerDisposition(provider) {
         evidence: { adapterVersion: null, verifiedAt: '2026-07-26' },
     };
 }
+function claudeLocatorClass(input) {
+    if (input.endsWith('.hooks.jsonl') || input.endsWith('.hook.jsonl'))
+        return 'claude-hook-jsonl';
+    if (input.endsWith('.json'))
+        return 'claude-web-export-json';
+    return 'claude-transcript-jsonl';
+}
+function claudeProviderProfile(locatorClass) {
+    if (locatorClass === 'claude-web-export-json')
+        return 'web-account-export-conversations-json';
+    return 'documented-local-jsonl';
+}
 function cursorLocatorClass(input) {
     if (input.endsWith('.md') || input.endsWith('.markdown'))
         return 'cursor-editor-markdown';
@@ -1182,6 +1487,7 @@ function parseArgs(argv) {
         '--inactivity-threshold',
         '--control-events',
         '--session', '--status', '--actor', '--group-by',
+        '--out', '--plan', '--input', '--shard-name', '--max-attachment-bytes',
     ]);
     let command;
     for (let index = 0; index < argv.length; index += 1) {

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

@@ -3102,6 +3102,7 @@ export class UseHandler {
                         version: manifest.version ?? (await getVersionInfo()).version,
                         source: 'bundled',
                         manifestHash: await hashManifest(manifestPath),
+                        asPrimary: Boolean(explicitAddonProvider),
                     });
                     await writeAiwgConfig(projectDir, updated);
                     config = updated;
@@ -3224,6 +3225,10 @@ export class UseHandler {
         }
         if (scope === 'user' && verbose) {
             ui.dim(`  --scope user: deploy targets mirror to home-rooted paths per ADR-4 §2`);
+            if (process.env.AIWG_USER_REGISTRY_PATH?.trim()) {
+                ui.warn('AIWG_USER_REGISTRY_PATH is set (test override active); user registry is not writing to default ~/.aiwg/installed.json'
+                    + ` (active: ${process.env.AIWG_USER_REGISTRY_PATH})`);
+            }
         }
         const filteredArgs = deployArgs.filter(a => a !== '--no-utils' && a !== '--no-project-local' && a !== '--ci-hooks-enabled' && a !== '--force' && a !== '--skip-conflicts' && a !== '--no-harness-agents');
         const deployFilteredArgs = removeFlagWithOptionalValue(filteredArgs, '--harness-agents');
@@ -3324,6 +3329,15 @@ export class UseHandler {
                     message: `--scope user not supported for provider '${provider}' — see docs/customization/user-scope-deployment.md for the supported list`,
                 };
             }
+            if (provider === 'grokbot') {
+                const { isGrokbotUserScopeConfigured, grokbotMissingRootRemediation } = await import('../../providers/grokbot-paths.js');
+                if (!isGrokbotUserScopeConfigured()) {
+                    return {
+                        exitCode: 1,
+                        message: grokbotMissingRootRemediation(),
+                    };
+                }
+            }
         }
         // Pre-deployment collision check (skip in dry-run — nothing is written)
         if (!dryRun) {
@@ -3853,7 +3867,12 @@ export class UseHandler {
                     commands: counts.commands,
                     skills: counts.skills,
                     rules: counts.rules,
-                }, { version: versionInfo.version, source: 'bundled', manifestHash: mHash });
+                }, {
+                    version: versionInfo.version,
+                    source: 'bundled',
+                    manifestHash: mHash,
+                    asPrimary: Boolean(explicitProvider),
+                });
                 await writeAiwgConfig(projectDir, updatedConfig);
             }
             catch {

package/dist/src/cli/scope-resolver.js

@@ -13,6 +13,7 @@ import { resolveOmpPaths } from '../providers/omp-paths.mjs';
 import { homedir } from 'node:os';
 import * as path from 'node:path';
 import { resolveHermesHome, resolveHermesHomePath } from '../providers/hermes-home.js';
+import { resolveGrokbotSkillsDir } from '../providers/grokbot-paths.js';
 export const hermesHome = resolveHermesHome;
 function piAgentDir() {
     const configured = process.env.PI_CODING_AGENT_DIR;
@@ -216,6 +217,18 @@ export const USER_SCOPE_PATHS = {
         rules: path.join(homedir(), '.openhuman', '.aiwg', 'rules'),
         behaviors: '',
     },
+    get grokbot() {
+        // Fail-closed: skills path is empty until AIWG_GROKBOT_SKILLS_DIR is set.
+        // Never invent ~/.grokbot. See adr-grokbot-provider-target / #205/#207.
+        const skills = resolveGrokbotSkillsDir() || '';
+        return {
+            agents: '',
+            skills,
+            commands: '',
+            rules: '',
+            behaviors: '',
+        };
+    },
     factory: {
         // #1164 — Verified against Factory docs (docs.factory.ai/cli/configuration/skills).
         // Skills primary user-scope path is ~/.factory/skills/, NOT the

package/dist/src/cli/services/deployment-verification.js

@@ -6,6 +6,7 @@ import { readUserRegistry } from '../../config/user-registry.js';
 import { inspectInstallation } from '../../installation/manager.mjs';
 import { getPackageRoot } from '../../channel/manager.mjs';
 import { getProviderDefinition, normalizeProviderDefinitionId, resolveProviderPathValue, } from '../../providers/provider-definitions.js';
+import { resolveGrokbotSkillsDir } from '../../providers/grokbot-paths.js';
 import { diagnoseIntegratedProviderTransformationReceipt } from '../../providers/transformation-receipt-integration.js';
 import { diagnoseWorkspaceContext, providerContextContract, } from '../../smiths/context-pipeline/workspace-context.js';
 import { USER_SCOPE_PATHS } from '../scope-resolver.js';
@@ -31,6 +32,11 @@ const RESTART_NOTICES = {
         action: 'Reload the Cursor workspace so it reloads agents and rules.',
         reason: 'Cursor reads workspace agents and rules when the workspace opens.',
     },
+    grokbot: {
+        policy: 'restart-required',
+        action: 'Start a new Grok Bot agent chat (or re-read skills) so deployed AIWG context and skills are visible.',
+        reason: 'Grok Bot skill/context reload behavior is not yet verified; AIWG does not claim live refresh.',
+    },
     factory: {
         policy: 'restart-required',
         action: 'Restart the Factory droid runtime so it reloads deployed droids.',
@@ -362,7 +368,16 @@ export async function verifyProviderDeployment(options) {
         const deploymentRoot = options.outputRoot ?? options.projectRoot;
         const artifactPaths = options.scope === 'user'
             ? USER_SCOPE_PATHS[normalized] ?? definition.paths.artifacts
-            : definition.paths.artifacts;
+            : { ...definition.paths.artifacts };
+        // Grok Bot: project-scope definition keeps skills null (fail-closed sentinel).
+        // When the operator configured AIWG_GROKBOT_SKILLS_DIR, count that absolute
+        // root so verification matches the deployer (#210 PUW).
+        if (normalized === 'grokbot') {
+            const configuredSkills = resolveGrokbotSkillsDir();
+            if (configuredSkills) {
+                artifactPaths.skills = configuredSkills;
+            }
+        }
         const writtenSince = options.invocationStartedAt
             ? Date.parse(options.invocationStartedAt)
             : Number.NaN;
@@ -402,7 +417,23 @@ export async function verifyProviderDeployment(options) {
             counts.skills += kernelCount;
         const artifactTotal = Object.values(counts).reduce((sum, value) => sum + value, 0);
         if (artifactTotal === 0) {
-            findings.push(finding(normalized, 'provider-artifacts-missing', 'blocking', `No deployed provider or kernel artifacts were found for ${normalized}.`, `Re-run aiwg use ${options.requestedBundles[0] ?? 'all'} --provider ${normalized}.`, { kernelPath, kernelCount, counts }));
+            // Bridge-only providers (e.g. grokbot project scope without skills env)
+            // intentionally have null native artifact dirs and land AGENTS.md instead.
+            const bridgeName = definition.paths.configFile || definition.paths.contextFiles?.contextFile;
+            const bridgePath = bridgeName ? path.join(options.projectRoot, bridgeName) : '';
+            const bridgePresent = bridgePath ? await exists(bridgePath) : false;
+            const expectsNoNativeArtifacts = (!definition.paths.artifacts.agents
+                && !definition.paths.artifacts.commands
+                && !definition.paths.artifacts.skills
+                && !definition.paths.artifacts.rules
+                && !definition.paths.artifacts.behaviors
+                && !definition.paths.kernelSkills);
+            if (expectsNoNativeArtifacts && bridgePresent) {
+                findings.push(finding(normalized, 'provider-bridge-only', 'info', `No native artifact directories for ${normalized}; discover-first bridge ${bridgeName} is present.`, 'Set AIWG_GROKBOT_SKILLS_DIR (absolute) before --scope user / --global when native skill copies are required.', { bridgePath, counts }));
+            }
+            else {
+                findings.push(finding(normalized, 'provider-artifacts-missing', 'blocking', `No deployed provider or kernel artifacts were found for ${normalized}.`, `Re-run aiwg use ${options.requestedBundles[0] ?? 'all'} --provider ${normalized}.`, { kernelPath, kernelCount, counts }));
+            }
         }
     }
     findings.push(...await collectRegistryFindings(options, normalized, counts));