@aiwg/cli 2026.9.15 → 2026.9.16

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

@@ -1,8 +1,8 @@
-import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync, } from 'node:fs';
+import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { randomUUID } from 'node:crypto';
-import { dirname, isAbsolute, join, resolve, } from 'node:path';
+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, buildSessionExportPlan, reverifySessionExportPlan, buildSessionAiwgFortemiIndexExport, recoverAiwgFortemiIndexFromFullV1Shard, 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, 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');
@@ -70,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>
@@ -653,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');
@@ -669,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';
@@ -692,13 +696,15 @@ 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
         ? claudeLocatorClass(input)
         : isCodex
@@ -717,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)] },
@@ -749,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
@@ -773,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
@@ -804,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 });
@@ -883,6 +897,14 @@ 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'));
@@ -895,8 +917,13 @@ async function exportBuild(ctx, args, repository, command) {
     }
     // Recheck source changes before writing (#2564 acceptance criteria):
     // re-select from the live repository and reject on any digest drift.
-    const { sessions, eventsBySessionId } = reverifySessionExportPlan(repository, plan);
-    const index = buildSessionAiwgFortemiIndexExport(plan.workspaceId, sessions, eventsBySessionId, plan.outputs);
+    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
@@ -910,16 +937,64 @@ async function exportBuild(ctx, args, repository, command) {
     if (!result.success || !result.archive) {
         throw new CliError('MALFORMED_SOURCE', `full-v1 shard conversion failed: ${JSON.stringify(result.losses)}`, EXIT.contract);
     }
-    const bytes = result.archive;
+    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 });
-    const finalPath = join(outDirectory, shardName);
     // 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 });
-    renameSync(tempPath, finalPath);
+    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) {
@@ -941,9 +1016,14 @@ async function exportBuild(ctx, args, repository, command) {
         shardFile: shardName,
         shardDigest,
         shardBytes: readBack.length,
+        embeddedAttachmentCount,
+        embeddedAttachmentBytes,
     };
-    writeFileSync(`${finalPath}.receipt.json`, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
-    return ok(command, { shard: finalPath, receipt: `${finalPath}.receipt.json`, ...receipt });
+    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'));
@@ -955,8 +1035,10 @@ async function exportVerify(ctx, args, command) {
         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);
@@ -982,6 +1064,7 @@ async function exportVerify(ctx, args, command) {
         shardBytes: bytes.length,
         receiptChecked: existsSync(receiptPath),
         receiptMatches,
+        embeddedAttachmentCount: embeddedAttachments.length,
     });
 }
 async function exportUnpack(ctx, args, command) {
@@ -1002,17 +1085,34 @@ async function exportUnpack(ctx, args, command) {
         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) {
@@ -1261,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',
@@ -1373,7 +1487,7 @@ function parseArgs(argv) {
         '--inactivity-threshold',
         '--control-events',
         '--session', '--status', '--actor', '--group-by',
-        '--out', '--plan', '--input', '--shard-name',
+        '--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));

package/dist/src/config/aiwg-config.js

@@ -172,6 +172,7 @@ export function resolveDelivery(delivery) {
  *     less aggressive at small fan-outs (10 is a safe middle ground)
  *   - hermes: MCP sidecar; rate-limit depends on upstream provider, operator
  *     should tune. Conservative 10 default.
+ *   - grokbot: desktop multi-agent; conservative 4 until native evidence.
  *   - unknown: conservative 4 default.
  */
 export const PROVIDER_PARALLELISM_DEFAULTS = {
@@ -186,6 +187,13 @@ export const PROVIDER_PARALLELISM_DEFAULTS = {
     windsurf: { max_parallel_subagents: 10, max_parallel_ralph_loops: 3, max_parallel_mc_missions: 6 },
     openclaw: { max_parallel_subagents: 10, max_parallel_ralph_loops: 3, max_parallel_mc_missions: 6 },
     hermes: { max_parallel_subagents: 10, max_parallel_ralph_loops: 3, max_parallel_mc_missions: 6 },
+    // Desktop multi-agent; conservative until native concurrency evidence exists.
+    grokbot: { max_parallel_subagents: 4, max_parallel_ralph_loops: 2, max_parallel_mc_missions: 4 },
+    // Conservative defaults for remaining stable/experimental harnesses (#249).
+    openhuman: { max_parallel_subagents: 4, max_parallel_ralph_loops: 2, max_parallel_mc_missions: 4 },
+    omp: { max_parallel_subagents: 4, max_parallel_ralph_loops: 2, max_parallel_mc_missions: 4 },
+    pi: { max_parallel_subagents: 4, max_parallel_ralph_loops: 2, max_parallel_mc_missions: 4 },
+    'deepseek-harness': { max_parallel_subagents: 4, max_parallel_ralph_loops: 2, max_parallel_mc_missions: 4 },
 };
 const UNKNOWN_PROVIDER_PARALLELISM = {
     max_parallel_subagents: 4,
@@ -928,6 +936,35 @@ export async function writeAiwgConfig(projectDir, config) {
         }
     }
 }
+/**
+ * Ensure `provider` appears in `config.providers` without wiping others (#247).
+ * First entry is the primary provider for parallelism/doctor labels.
+ * When `asPrimary` is true (explicit `--provider` deploy), move the provider to the front.
+ */
+export function ensureProviderListed(config, provider, opts = {}) {
+    const normalized = provider.trim();
+    if (!normalized)
+        return config;
+    const providers = Array.isArray(config.providers) ? [...config.providers] : [];
+    const idx = providers.indexOf(normalized);
+    if (opts.asPrimary) {
+        if (idx === 0) {
+            config.providers = providers;
+            return config;
+        }
+        if (idx > 0)
+            providers.splice(idx, 1);
+        providers.unshift(normalized);
+    }
+    else if (idx < 0) {
+        providers.push(normalized);
+    }
+    else {
+        return config;
+    }
+    config.providers = providers;
+    return config;
+}
 /**
  * Update the `installed` record for a framework after a successful deployment.
  * Returns the updated config (does not write to disk — caller must call writeAiwgConfig).
@@ -975,6 +1012,8 @@ export function updateInstalled(config, name, provider, counts, opts) {
         delete existing.deployedArtifactHashes;
     }
     config.installed[name] = existing;
+    // Keep providers[] aligned with deployedTo so doctor/parallelism see the right primary (#247).
+    ensureProviderListed(config, provider, { asPrimary: opts.asPrimary === true });
     return config;
 }
 /**

package/dist/src/config/user-registry.js

@@ -25,6 +25,15 @@ import { userScopeConfigPath } from '../cli/scope-resolver.js';
  * never set this — it exists so the test suite can avoid clobbering the real
  * `~/.aiwg/installed.json` on the developer's machine.
  */
+/** True when AIWG_USER_REGISTRY_PATH redirects away from ~/.aiwg/installed.json. */
+export function isUserRegistryPathOverrideActive() {
+    return Boolean(process.env.AIWG_USER_REGISTRY_PATH?.trim());
+}
+/**
+ * Operator-facing warning for a leftover test override (#246).
+ * Docs mark AIWG_USER_REGISTRY_PATH as test-only; doctor/status/use must surface it.
+ */
+export const USER_REGISTRY_PATH_OVERRIDE_WARN = 'AIWG_USER_REGISTRY_PATH is set (test override active); user registry is not writing to default ~/.aiwg/installed.json';
 export function userRegistryPath() {
     const override = process.env.AIWG_USER_REGISTRY_PATH;
     if (override)

package/dist/src/extensions/manifest.js

@@ -121,6 +121,7 @@ export const ProviderConfigSchema = z.object({
         'cursor',
         'deepseek-harness',
         'factory',
+        'grokbot',
         'hermes',
         'opencode',
         'openclaw',