@aiwg/cli 2026.10.1 → 2026.10.3

package/dist/src/sessions/grok-build-cli.js

@@ -1,7 +1,7 @@
 import { execFile as execFileCallback } from 'node:child_process';
 import { constants as fsConstants } from 'node:fs';
-import { lstat, open, realpath, writeFile } from 'node:fs/promises';
-import { dirname, isAbsolute, join, parse, resolve } from 'node:path';
+import { access, lstat, open, realpath, stat, writeFile } from 'node:fs/promises';
+import { delimiter, dirname, isAbsolute, join, parse, resolve } from 'node:path';
 import { promisify } from 'node:util';
 import { resolveGrokHomeResult } from '../providers/grok-build-paths.js';
 import { SessionContractError } from './contracts.js';
@@ -115,10 +115,10 @@ async function runGrok(options, args) {
     if (!home.ok)
         throw new SessionContractError('SOURCE_NOT_AUTHORIZED', home.message);
     await rejectSymlinkComponents(home.path);
-    const binary = options.binary ?? 'grok';
-    if (binary !== 'grok' && !isAbsolute(binary)) {
+    if (options.binary !== undefined && !isAbsolute(options.binary)) {
         throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Grok Build binary override must be absolute');
     }
+    const binary = options.binary ?? await defaultGrokBinary(env, home.path);
     const runner = options.runner ?? execFile;
     try {
         const result = await runner(binary, ['--no-auto-update', ...args], {
@@ -136,7 +136,69 @@ async function runGrok(options, args) {
         if (error.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
             throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Grok Build CLI output exceeds 2 MB');
         }
-        throw new SessionContractError('UNSUPPORTED_OPERATION', 'Grok Build CLI failed or timed out; check the local `grok` installation, authentication, and selected workspace.');
+        throw grokFailure(error, binary);
+    }
+}
+/**
+ * Map a failed `grok` launch to an actionable error (#2968). stderr is never
+ * echoed: Grok Build diagnostics can carry session content.
+ */
+function grokFailure(error, binary) {
+    const name = binary === 'grok' ? '`grok`' : `\`${binary}\``;
+    if (error.code === 'ENOENT') {
+        return new SessionContractError('UNSUPPORTED_OPERATION', `Grok Build CLI not found: ${name} is not on PATH and no $GROK_HOME/bin/grok was found; `
+            + 'pass --grok-bin <absolute path> or add the Grok Build bin directory to PATH.');
+    }
+    if (error.code === 'EACCES') {
+        return new SessionContractError('UNSUPPORTED_OPERATION', `Grok Build CLI ${name} is not executable; check its permissions or pass --grok-bin <absolute path>.`);
+    }
+    if (error.killed || error.signal) {
+        return new SessionContractError('UNSUPPORTED_OPERATION', `Grok Build CLI ${name} timed out after ${TIMEOUT_MS / 1000}s; check that it is authenticated `
+            + 'and does not prompt for input.');
+    }
+    if (typeof error.code === 'number') {
+        return new SessionContractError('UNSUPPORTED_OPERATION', `Grok Build CLI ${name} exited with code ${error.code}; run \`grok sessions list\` in the selected `
+            + 'workspace to check authentication and installation.');
+    }
+    return new SessionContractError('UNSUPPORTED_OPERATION', 'Grok Build CLI failed; check the local `grok` installation, authentication, and selected workspace.');
+}
+/**
+ * Resolve `grok` from PATH, else the installer's `$GROK_HOME/bin/grok` (#2968).
+ * The installer links `bin/grok` to a versioned binary beside it, so that one
+ * link is followed only when it resolves to a regular file inside `bin`.
+ */
+async function defaultGrokBinary(env, grokHome) {
+    for (const directory of (env.PATH ?? '').split(delimiter)) {
+        if (!directory || !isAbsolute(directory))
+            continue;
+        if (await isExecutableFile(join(directory, 'grok')))
+            return 'grok';
+    }
+    const binDirectory = join(grokHome, 'bin');
+    try {
+        await rejectSymlinkComponents(binDirectory);
+        const canonicalBin = await realpath(binDirectory);
+        const target = await realpath(join(binDirectory, 'grok'));
+        if (dirname(target) !== canonicalBin || !(await isExecutableFile(target)))
+            return 'grok';
+        return target;
+    }
+    catch (error) {
+        if (error instanceof SessionContractError)
+            throw error;
+        return 'grok';
+    }
+}
+async function isExecutableFile(path) {
+    try {
+        const item = await stat(path);
+        if (!item.isFile())
+            return false;
+        await access(path, fsConstants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
     }
 }
 function parseSessionIds(stdout, mode) {

package/dist/src/sessions/importer.js

@@ -65,6 +65,7 @@ export class IncrementalSessionImporter {
             policyVersion: request.policyVersion,
             continuity: continuity
                 ? (!previous || previous.positionKind === 'byte-offset'
+                    || previous.positionKind === 'provider-native'
                     ? continuity.outcome
                     : 'unverified')
                 : (previous ? 'unverified' : 'new-generation'),
@@ -152,6 +153,14 @@ export class IncrementalSessionImporter {
                     checkpoint.cursor = record.sourceCursor;
                     checkpoint.bytesRead = Number(record.sourceCursor.slice(5));
                 }
+                else if (record.sourceCursor?.startsWith('native:')) {
+                    // An opaque provider-native resume token (e.g. a monotonic native
+                    // sequence) — never a byte offset. Stored verbatim; `bytesRead`
+                    // still accumulates so resource limits remain meaningful.
+                    checkpoint.positionKind = 'provider-native';
+                    checkpoint.cursor = record.sourceCursor;
+                    checkpoint.bytesRead += bytes;
+                }
                 else {
                     checkpoint.bytesRead += bytes;
                     checkpoint.cursor = String(checkpoint.recordsRead);
@@ -435,9 +444,15 @@ async function sourceContinuity(request, previous) {
         selectedPath: request.selectedSource.locator,
         allowedRoots: request.selectedSource.authorizedScope.allowedRoots,
     };
+    // Snapshot sources are rewritten wholesale on every save (no stable
+    // append-only byte region, and the file identity may legitimately change
+    // via rename-swap): skip the shrink, file-identity, and prefix-rewrite
+    // throws below. Idempotency instead rests on the adapter's own monotonic
+    // native cursor plus the catalog's identity-keyed inserts.
+    const isSnapshot = request.adapter.sourceContinuity === 'snapshot';
     const skipPrefixBytes = await request.adapter.mutablePrefixBytes?.(request.selectedSource) ?? 0;
     const metadata = await fingerprintSourcePrefix(authorization, 0);
-    if (previous?.sourceSize !== undefined) {
+    if (!isSnapshot && previous?.sourceSize !== undefined) {
         if (metadata.size < previous.sourceSize) {
             throw new SessionContractError('SCHEMA_DRIFT', 'session source was truncated before its durable checkpoint');
         }
@@ -451,17 +466,18 @@ async function sourceContinuity(request, previous) {
         }
     }
     const current = await fingerprintSourcePrefix(authorization, metadata.size, skipPrefixBytes);
-    const generation = previous?.sourceGeneration ?? sha256([
-        sourceGenerationDigest(request),
-        metadata.fileIdentity,
-    ].join('\0'));
+    const generation = previous?.sourceGeneration ?? (isSnapshot
+        ? sourceGenerationDigest(request)
+        : sha256([sourceGenerationDigest(request), metadata.fileIdentity].join('\0')));
     return {
         sourceGeneration: generation,
         outcome: !previous
             ? 'new-generation'
-            : metadata.size === previous.sourceSize
-                && current.digest === previous.prefixDigest
-                ? 'unchanged-replay' : 'validated-append',
+            : isSnapshot
+                ? (current.digest === previous.prefixDigest ? 'unchanged-replay' : 'validated-append')
+                : metadata.size === previous.sourceSize
+                    && current.digest === previous.prefixDigest
+                    ? 'unchanged-replay' : 'validated-append',
         size: metadata.size,
         mtimeMs: metadata.mtimeMs,
         fileIdentity: metadata.fileIdentity,

package/dist/src/sessions/index.js

@@ -42,4 +42,6 @@ export * from './adapters/warp.js';
 export * from './adapters/windsurf.js';
 export * from './adapters/muse.js';
 export * from './adapters/omp.js';
+export * from './adapter-registry.js';
+export * from './coverage-preflight.js';
 //# sourceMappingURL=index.js.map

package/dist/src/sessions/repository.js

@@ -5,6 +5,11 @@ import { redactSessionText, sanitizeNativeExtensions } from './policy.js';
 import { deriveSessionAnalytics, } from './analytics.js';
 const POLICY_PROVIDER_MIGRATION = 'policy-provider-identity:v2';
 const EVENT_ORIGIN_INTENT_MIGRATION = 'event-origin-intent:v1';
+const VISIBLE_SESSION_PREDICATE = `s.lifecycle != 'tombstoned' AND EXISTS (
+  SELECT 1 FROM session_events e
+  JOIN import_runs r ON r.import_run_id=e.import_run_id
+  WHERE e.session_id=s.session_id AND r.status='committed'
+)`;
 export class SessionRepository {
     db;
     constructor(path = ':memory:') {
@@ -620,16 +625,56 @@ export class SessionRepository {
     }
     getSession(id, workspaceId) {
         const row = this.db.prepare(`SELECT s.data FROM sessions s
-       WHERE s.session_id=? AND s.lifecycle != ?
-       ${workspaceId ? 'AND s.workspace_id=?' : ''}
-       AND EXISTS (
-         SELECT 1 FROM session_events e
-         JOIN import_runs r ON r.import_run_id=e.import_run_id
-         WHERE e.session_id=s.session_id AND r.status='committed'
-       )`)
-            .get(...(workspaceId ? [id, 'tombstoned', workspaceId] : [id, 'tombstoned']));
+       WHERE s.session_id=? AND ${VISIBLE_SESSION_PREDICATE}
+       ${workspaceId ? 'AND s.workspace_id=?' : ''}`)
+            .get(...(workspaceId ? [id, workspaceId] : [id]));
         return row ? JSON.parse(String(row.data)) : null;
     }
+    findSessionsByReference(reference, workspaceId) {
+        const internal = this.getSession(reference, workspaceId);
+        if (internal)
+            return [internal];
+        const query = (predicate) => this.db.prepare(`SELECT s.data FROM sessions s
+       WHERE ${workspaceId ? 's.workspace_id=? AND' : ''} ${VISIBLE_SESSION_PREDICATE} AND (${predicate})
+       ORDER BY s.session_id`).all(...(workspaceId ? [workspaceId, reference] : [reference]))
+            .map((row) => JSON.parse(String(row.data)));
+        const exact = query('s.native_session_id=?');
+        if (exact.length === 1)
+            return exact;
+        if (exact.length > 1) {
+            // Artifact IDs are redacted by native-extension sanitization. The
+            // adapter's boolean subagent flag survives. Only prefer a parent when
+            // every other match is a proven Claude subagent in the same workspace.
+            if (exact.every((session) => session.provider === 'claude'
+                && session.workspaceId === exact[0].workspaceId)) {
+                const classified = exact.map((session) => {
+                    const flags = this.db.prepare(`SELECT
+            MAX(json_extract(e.data, '$.extensions."native.claude".transcriptFamily.subagent')=0) AS parent,
+            MAX(json_extract(e.data, '$.extensions."native.claude".transcriptFamily.subagent')=1) AS subagent
+            FROM session_events e JOIN import_runs r ON r.import_run_id=e.import_run_id
+            WHERE e.session_id=? AND r.status='committed'`).get(session.sessionId);
+                    return { session, parent: flags.parent === 1, subagent: flags.subagent === 1 };
+                });
+                const parents = classified.filter((item) => item.parent && !item.subagent);
+                if (parents.length === 1 && classified.every((item) => item === parents[0]
+                    || (item.subagent && !item.parent)))
+                    return [parents[0].session];
+            }
+            return exact;
+        }
+        // substr treats %, _ and other characters literally rather than as LIKE patterns.
+        return this.db.prepare(`SELECT s.data FROM sessions s
+       WHERE ${workspaceId ? 's.workspace_id=? AND' : ''} ${VISIBLE_SESSION_PREDICATE}
+       AND (substr(s.native_session_id, 1, length(?))=?
+         OR substr(s.session_id, 1, length(?))=?)
+       ORDER BY s.session_id`).all(...(workspaceId ? [workspaceId, reference, reference, reference, reference]
+            : [reference, reference, reference, reference]))
+            .map((row) => JSON.parse(String(row.data)));
+    }
+    listWorkspaceSessionCounts() {
+        return this.db.prepare(`SELECT s.workspace_id, COUNT(*) AS count FROM sessions s
+       WHERE ${VISIBLE_SESSION_PREDICATE} GROUP BY s.workspace_id ORDER BY s.workspace_id`).all().map((row) => ({ workspaceId: String(row.workspace_id), count: Number(row.count) }));
+    }
     listSources() {
         return this.db.prepare('SELECT data FROM session_sources ORDER BY provider, source_id').all().map((row) => JSON.parse(String(row.data)));
     }
@@ -670,11 +715,7 @@ export class SessionRepository {
             : coverage;
     }
     listSessions(options) {
-        const where = [`s.lifecycle != 'tombstoned'`, `EXISTS (
-      SELECT 1 FROM session_events e
-      JOIN import_runs r ON r.import_run_id=e.import_run_id
-      WHERE e.session_id=s.session_id AND r.status='committed'
-    )`];
+        const where = [VISIBLE_SESSION_PREDICATE];
         const scopeDigest = sessionListScopeDigest(options);
         const cursor = decodeSessionListCursor(options.cursor);
         if (cursor && cursor.scopeDigest !== scopeDigest) {

package/dist/src/sessions/workspace-discovery.js

@@ -3,46 +3,53 @@ import { access, mkdir, readFile, realpath, rename, stat, writeFile, } from 'nod
 import { homedir, userInfo } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
-import { ClaudeSessionAdapter } from './adapters/claude.js';
-import { CodexSessionAdapter } from './adapters/codex.js';
-import { CursorSessionAdapter } from './adapters/cursor.js';
-import { FactorySessionAdapter } from './adapters/factory.js';
-import { MuseSessionAdapter, museNativeSourceMatchesWorkspace } from './adapters/muse.js';
-import { OmpSessionAdapter, readOmpSessionHeader } from './adapters/omp.js';
+import { inspectMuseNativeWorkspace } from './adapters/muse.js';
+import { readOmpSessionHeader } from './adapters/omp.js';
+import { grokbotConversationIdFromLocator } from './adapters/grokbot-locator.js';
 import { resolveOmpPaths } from '../providers/omp-paths.mjs';
-import { PiSessionAdapter } from './adapters/pi.js';
-import { DeepSeekHarnessSessionAdapter } from './adapters/deepseek-harness.js';
-import { SESSION_PROVIDER_IDS, sha256, } from './contracts.js';
+import { SESSION_PROVIDER_IDS, SessionCoveragePreflightSchema, SessionContractError, sha256, } from './contracts.js';
 import { redactSourceLocator } from './discovery.js';
+import { createSessionAdapterRegistry } from './adapter-registry.js';
+import { coveragePreflight, expectedSessionProviders } from './coverage-preflight.js';
 import { fingerprintSourceFile } from './readers.js';
 export const DISCOVERY_MANIFEST_VERSION = '1.0.0';
 const MANUAL_EXPORT_PROVIDERS = new Set([
-    'copilot', 'hermes', 'opencode', 'openclaw', 'openhuman', 'grokbot', 'grok-build',
+    'copilot', 'hermes', 'opencode', 'openclaw', 'openhuman', 'grok-build',
     'warp', 'devin-desktop', 'generic',
 ]);
 export async function discoverWorkspaceHistories(options) {
+    const registry = options.registry ?? createSessionAdapterRegistry();
+    const expectedProviders = expectedSessionProviders(options.expectedProviders ?? SESSION_PROVIDER_IDS);
+    const supportedProviders = new Set(registry.list().map((adapter) => adapter.provider));
     const workspacePath = await canonicalPath(options.workspace);
     const workspaceId = workspacePath;
     const providerHomes = providerHomeCandidates(options.providerHome, options.operatorHome);
     const keyWithLeadingDash = workspaceKey(workspacePath, true);
     const keyWithoutLeadingDash = workspaceKey(workspacePath, false);
     const discoverable = [
-        { provider: 'deepseek-harness', adapter: new DeepSeekHarnessSessionAdapter(), roots: options.dshRoot
+        { provider: 'deepseek-harness', roots: options.dshRoot
                 ? [resolve(options.dshRoot)] : options.providerHome
                 ? [join(resolve(options.providerHome), '.dsh', 'sessions')] : [] },
-        { provider: 'omp', adapter: new OmpSessionAdapter(), roots: options.ompRoot
+        { provider: 'omp', roots: options.ompRoot
                 ? [resolve(options.ompRoot)] : options.providerHome
                 ? [resolveOmpPaths({ home: resolve(options.providerHome), cwd: workspacePath }).sessionsDir] : [] },
-        { provider: 'muse', adapter: new MuseSessionAdapter(), roots: options.museRoot
+        { provider: 'muse', roots: options.museRoot
                 ? [resolve(options.museRoot)] : [] },
+        // Grok Bot conversations carry no workspace/cwd field, so unlike
+        // claude/cursor/factory there is no per-workspace default path to derive
+        // from providerHome. Native discovery requires an explicit
+        // --grokbot-root (same shared-root authorization model as
+        // codex/omp/deepseek-harness/muse below), and every authorized
+        // conversation surfaces to whichever workspace runs discovery (same
+        // no-filtering behavior already used for `pi`/`deepseek-harness`).
+        { provider: 'grokbot', roots: options.grokbotRoot
+                ? [resolve(options.grokbotRoot)] : [] },
         {
             provider: 'claude',
-            adapter: new ClaudeSessionAdapter(),
             roots: providerHomes.map((providerHome) => join(providerHome, '.claude', 'projects', keyWithLeadingDash)),
         },
         {
             provider: 'codex',
-            adapter: new CodexSessionAdapter(),
             roots: options.codexRoot
                 ? [resolve(options.codexRoot)]
                 : options.providerHome
@@ -51,31 +58,39 @@ export async function discoverWorkspaceHistories(options) {
         },
         {
             provider: 'cursor',
-            adapter: new CursorSessionAdapter(),
             roots: providerHomes.map((providerHome) => join(providerHome, '.cursor', 'projects', keyWithoutLeadingDash, 'agent-transcripts')),
         },
         {
             provider: 'factory',
-            adapter: new FactorySessionAdapter(),
             roots: providerHomes.flatMap((providerHome) => [
                 join(providerHome, '.factory', 'projects', keyWithLeadingDash),
                 join(providerHome, '.factory', 'sessions', keyWithLeadingDash),
             ]),
         },
         {
+            // Pi stores every working directory's sessions in its own
+            // subdirectory of the sessions root, named `--<path>--` where
+            // `<path>` has its leading separator removed and `/`, `\`, and `:`
+            // replaced with `-` (https://pi.dev/docs/latest/session-format,
+            // "File Location", verified 2026-10-12) — the same transform
+            // `workspaceKey(path, false)` already applies for Cursor below.
+            // Scanning the whole sessions root (as before) would import every
+            // other workspace's history into this one's catalog (#2656).
             provider: 'pi',
-            adapter: new PiSessionAdapter(),
-            roots: options.providerHome
-                ? [process.env.PI_CODING_AGENT_SESSION_DIR
-                        ? resolve(process.env.PI_CODING_AGENT_SESSION_DIR)
-                        : join(resolve(options.providerHome), '.pi', 'agent', 'sessions')]
-                : [],
+            roots: (process.env.PI_CODING_AGENT_SESSION_DIR
+                ? [resolve(process.env.PI_CODING_AGENT_SESSION_DIR)]
+                : providerHomes.map((providerHome) => join(providerHome, '.pi', 'agent', 'sessions'))).map((sessionsRoot) => join(sessionsRoot, `--${keyWithoutLeadingDash}--`)),
         },
     ];
     const reports = new Map();
     const candidates = [];
     const seen = new Set();
     for (const entry of discoverable) {
+        if (!expectedProviders.includes(entry.provider) || !supportedProviders.has(entry.provider))
+            continue;
+        const adapter = registry.get(entry.provider);
+        if (adapter.disposition === 'unsupported' || !adapter.supportedOperations.includes('discover'))
+            continue;
         const availableRoots = [];
         for (const root of entry.roots) {
             if (await pathExists(root))
@@ -83,12 +98,13 @@ export async function discoverWorkspaceHistories(options) {
         }
         if (availableRoots.length === 0) {
             const codexNeedsAuthorization = (entry.provider === 'codex' || entry.provider === 'omp'
-                || entry.provider === 'deepseek-harness' || entry.provider === 'muse')
+                || entry.provider === 'deepseek-harness' || entry.provider === 'muse'
+                || entry.provider === 'grokbot')
                 && entry.roots.length === 0;
             reports.set(entry.provider, providerReport(entry.provider, codexNeedsAuthorization ? 'export-required' : 'unavailable', codexNeedsAuthorization ? 'manual-export' : 'discoverable', [], codexNeedsAuthorization
                 ? 'SHARED_ROOT_AUTHORIZATION_REQUIRED'
                 : 'PROVIDER_ROOT_UNAVAILABLE', codexNeedsAuthorization
-                ? `Pass --${entry.provider}-root with an explicitly authorized sessions root.`
+                ? `Pass --${entry.provider === 'deepseek-harness' ? 'dsh' : entry.provider}-root with an explicitly authorized sessions root.`
                 : `No authorized ${entry.provider} workspace history root was found.`));
             continue;
         }
@@ -97,17 +113,25 @@ export async function discoverWorkspaceHistories(options) {
             allowedRoots: availableRoots,
         };
         const providerSources = [];
-        for await (const descriptor of entry.adapter.discover(scope)) {
-            const locator = await canonicalPath(descriptor.locator);
-            if (entry.provider === 'codex'
-                && !await codexSourceMatchesWorkspace(locator, workspacePath))
-                continue;
-            if (entry.provider === 'muse'
-                && !await museNativeSourceMatchesWorkspace({
+        const museSourceInspections = [];
+        for await (const descriptor of adapter.discover(scope)) {
+            if (entry.provider === 'muse') {
+                const inspection = await inspectMuseNativeWorkspace({
                     ...descriptor,
                     sourceId: 'discovery',
                     authorizedScope: scope,
-                }, workspacePath))
+                }, workspacePath);
+                museSourceInspections.push({
+                    sourceKey: sha256(['muse-workspace-inspection-v1', descriptor.locator].join('\0')),
+                    redactedLocator: redactSourceLocator(descriptor.locator),
+                    ...inspection,
+                });
+                if (inspection.outcome !== 'matched')
+                    continue;
+            }
+            const locator = await canonicalPath(descriptor.locator);
+            if (entry.provider === 'codex'
+                && !await codexSourceMatchesWorkspace(locator, workspacePath))
                 continue;
             const ompHeader = entry.provider === 'omp' ? await readOmpSessionHeader({ ...descriptor, sourceId: 'discovery', authorizedScope: scope }) : undefined;
             if (ompHeader && resolve(ompHeader.cwd) !== workspacePath)
@@ -127,17 +151,40 @@ export async function discoverWorkspaceHistories(options) {
             const source = sourceFromDescriptor(descriptor, locator, authorizedRoot, details, fingerprint.digest);
             if (ompHeader)
                 source.sourceId = sha256(['omp-native-source-v1', workspaceId, ompHeader.id].join('\0'));
+            if (entry.provider === 'grokbot') {
+                // The replica is rewritten wholesale as its sliding window evicts
+                // old entries, so a content-digest sourceId (the default above)
+                // would churn every re-discovery and break checkpoint continuity.
+                // Key it on the conversation id instead, same rationale as the OMP
+                // override above.
+                const conversationId = grokbotConversationIdFromLocator(locator);
+                if (conversationId) {
+                    source.sourceId = sha256(['grokbot-native-source-v1', workspaceId, conversationId].join('\0'));
+                }
+            }
             providerSources.push(source);
             candidates.push(source);
         }
-        reports.set(entry.provider, providerReport(entry.provider, 'checked', 'discoverable', providerSources, providerSources.length === 0 ? 'NO_WORKSPACE_SOURCES' : null, providerSources.length === 0
-            ? `The ${entry.provider} root was checked, but no source matched the authorized workspace.`
-            : null));
+        const incompleteMuseInspection = museSourceInspections.some((inspection) => inspection.outcome === 'inconclusive');
+        const report = providerReport(entry.provider, incompleteMuseInspection ? 'not-checked' : 'checked', 'discoverable', providerSources, incompleteMuseInspection ? 'MUSE_SOURCE_INSPECTION_INCOMPLETE'
+            : providerSources.length === 0 ? 'NO_WORKSPACE_SOURCES' : null, incompleteMuseInspection
+            ? 'Review museSourceInspections; authorize a supported Muse export for unresolved sources before claiming workspace coverage.'
+            : providerSources.length === 0
+                ? `The ${entry.provider} root was checked, but no source matched the authorized workspace.`
+                : null);
+        if (entry.provider === 'muse') {
+            report.museSourceInspections = museSourceInspections.sort((a, b) => a.sourceKey.localeCompare(b.sourceKey));
+        }
+        reports.set(entry.provider, report);
     }
-    for (const provider of SESSION_PROVIDER_IDS) {
+    for (const provider of expectedProviders) {
         if (reports.has(provider))
             continue;
         const manual = MANUAL_EXPORT_PROVIDERS.has(provider);
+        if (!supportedProviders.has(provider)) {
+            reports.set(provider, providerReport(provider, 'not-checked', 'unsupported', [], 'MISSING_ADAPTER', 'Deliberately select a compatible runtime or an authorized supported export.'));
+            continue;
+        }
         const grokBuild = provider === 'grok-build';
         reports.set(provider, providerReport(provider, manual ? 'export-required' : 'not-checked', manual ? 'manual-export' : 'unsupported', [], grokBuild ? 'CLI_EXPORT_REQUIRED'
             : manual ? 'EXPLICIT_EXPORT_REQUIRED' : 'PROVIDER_NOT_CHECKED', grokBuild
@@ -148,9 +195,14 @@ export async function discoverWorkspaceHistories(options) {
     }
     const sources = candidates.sort(compareSources);
     const providers = [...reports.values()].sort((a, b) => a.provider.localeCompare(b.provider));
+    const preflight = coveragePreflight({
+        expectedProviders, expectedProviderBasis: options.expectedProviders ? 'explicit' : 'declared-default',
+        registry, runtime: options.runtime, reports: providers,
+    });
     const identity = {
         schemaVersion: DISCOVERY_MANIFEST_VERSION,
         workspaceId,
+        preflight,
         sources: sources.map((source) => ({
             sourceId: source.sourceId,
             provider: source.provider,
@@ -164,6 +216,7 @@ export async function discoverWorkspaceHistories(options) {
             provider: provider.provider,
             status: provider.status,
             reasonCode: provider.reasonCode,
+            ...(provider.museSourceInspections ? { museSourceInspections: provider.museSourceInspections } : {}),
         })),
     };
     return {
@@ -172,6 +225,7 @@ export async function discoverWorkspaceHistories(options) {
         createdAt: options.createdAt ?? new Date().toISOString(),
         workspaceId,
         workspacePath,
+        preflight,
         providers,
         sources,
     };
@@ -194,6 +248,11 @@ export async function readDiscoveryManifest(path) {
         || !Array.isArray(value.sources)) {
         throw new Error('session discovery manifest is malformed or unsupported');
     }
+    if (value.preflight) {
+        const parsed = SessionCoveragePreflightSchema.safeParse(value.preflight);
+        if (!parsed.success)
+            throw new SessionContractError('INVALID_ARGUMENT', 'invalid discovery coverage preflight');
+    }
     const expected = await rediscoverManifestIdentity(value);
     if (expected !== value.manifestId) {
         throw new Error('session discovery manifest identity does not match its contents');
@@ -207,6 +266,7 @@ export function publicDiscoveryManifest(manifest) {
         createdAt: manifest.createdAt,
         workspaceId: manifest.workspaceId,
         workspacePath: manifest.workspacePath,
+        preflight: manifest.preflight,
         providers: manifest.providers,
         sources: manifest.sources.map(({ locator: _locator, authorizedRoot: _root, ...source }) => source),
         totals: {
@@ -250,6 +310,7 @@ async function rediscoverManifestIdentity(manifest) {
     const identity = {
         schemaVersion: manifest.schemaVersion,
         workspaceId: manifest.workspaceId,
+        ...(manifest.preflight ? { preflight: manifest.preflight } : {}),
         sources: manifest.sources.map((source) => ({
             sourceId: source.sourceId,
             provider: source.provider,
@@ -263,6 +324,7 @@ async function rediscoverManifestIdentity(manifest) {
             provider: provider.provider,
             status: provider.status,
             reasonCode: provider.reasonCode,
+            ...(provider.museSourceInspections ? { museSourceInspections: provider.museSourceInspections } : {}),
         })),
     };
     return sha256(JSON.stringify(identity));

package/dist/src/skills/adapters/clawhub.js

@@ -11,7 +11,8 @@
  * @see https://clawhub.ai
  * @see https://docs.openclaw.ai/tools/clawhub
  */
-import { execSync } from 'child_process';
+import { boundedExecFileSync } from '../../process/bounded-child-process.mjs';
+import { cliCommand } from '../../process/cli-command.mjs';
 import fs from 'fs';
 import path from 'path';
 import { getProviderDefinition, resolveProviderPathValue, } from '../../providers/provider-definitions.js';
@@ -47,7 +48,8 @@ async function clawHubFetch(endpoint) {
  */
 function runClawHub(args) {
     try {
-        return execSync(`clawhub ${args}`, {
+        const [file, argv] = cliCommand('clawhub', args);
+        return boundedExecFileSync(file, argv, 'quick', {
             encoding: 'utf-8',
             timeout: 30000,
             stdio: ['pipe', 'pipe', 'pipe'],
@@ -65,7 +67,7 @@ export class ClawHubAdapter {
         if (this.available !== null)
             return this.available;
         // Check CLI
-        const cliAvailable = runClawHub('--version 2>/dev/null') !== null;
+        const cliAvailable = runClawHub(['--version']) !== null;
         if (cliAvailable) {
             this.available = true;
             return true;
@@ -89,7 +91,7 @@ export class ClawHubAdapter {
             }));
         }
         // Try CLI
-        const cliOutput = runClawHub(`search "${query}" --json 2>/dev/null`);
+        const cliOutput = runClawHub(['search', query, '--json']);
         if (cliOutput) {
             try {
                 const parsed = JSON.parse(cliOutput);
@@ -127,7 +129,7 @@ export class ClawHubAdapter {
             };
         }
         // Try CLI
-        const cliOutput = runClawHub(`info "${name}" --json 2>/dev/null`);
+        const cliOutput = runClawHub(['info', name, '--json']);
         if (cliOutput) {
             try {
                 const parsed = JSON.parse(cliOutput);
@@ -162,7 +164,7 @@ export class ClawHubAdapter {
             }));
         }
         // Try CLI
-        const cliOutput = runClawHub('list --json 2>/dev/null');
+        const cliOutput = runClawHub(['list', '--json']);
         if (cliOutput) {
             try {
                 const parsed = JSON.parse(cliOutput);
@@ -195,7 +197,7 @@ export class ClawHubAdapter {
             targetDir = resolveSkillFallbackPath(target, options.projectDir, name);
         }
         // Try CLI install (downloads to a temp location, then we copy)
-        const cliResult = runClawHub(`install "${name}" --output "${targetDir}" 2>/dev/null`);
+        const cliResult = runClawHub(['install', name, '--output', targetDir]);
         if (cliResult !== null)
             return;
         // Try API download
@@ -240,7 +242,7 @@ export class ClawHubAdapter {
             }
         }
         // Try CLI publish
-        const cliResult = runClawHub(`publish "${packageDir}" 2>/dev/null`);
+        const cliResult = runClawHub(['publish', packageDir]);
         if (cliResult !== null)
             return;
         throw new Error('ClawHub publish requires the clawhub CLI. ' +