@aiwg/cli 2026.10.11 → 2026.10.12

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

@@ -0,0 +1,172 @@
+// Resolve catalog identities and authorized native paths for the sessions tail verb.
+import { existsSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { readAiwgConfig } from '../../config/aiwg-config.js';
+import { createSessionAdapterRegistry } from '../../sessions/adapter-registry.js';
+import { assertSessionProviderId, SessionContractError } from '../../sessions/contracts.js';
+import { redactSessionValue } from '../../sessions/policy.js';
+import { resolveImportLimits } from '../../sessions/import-limits.js';
+import { acquireImportLease } from '../../sessions/import-lease.js';
+import { SessionRepository } from '../../sessions/repository.js';
+import { assertTailSupported, tailSession } from '../../sessions/tail.js';
+import { defaultDiscoveryManifestPath, readDiscoveryManifest } from '../../sessions/workspace-discovery.js';
+export async function executeSessionsTail(ctx, args, helpers) {
+    const json = args.flags.has('--json');
+    let repository;
+    let lease;
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    const signal = ctx.signal ? AbortSignal.any([ctx.signal, controller.signal]) : controller.signal;
+    process.on('SIGINT', stop);
+    try {
+        const latest = args.flags.has('--latest');
+        const reference = args.positionals[0];
+        const providerInput = args.values.get('--provider');
+        if (args.positionals.length > 1 || (latest ? !providerInput || !!reference : !reference)) {
+            throw new SessionContractError('INVALID_ARGUMENT', 'tail requires <session-id> or --provider <p> --latest');
+        }
+        if (args.flags.has('--import') && (ctx.dryRun || args.flags.has('--dry-run'))) {
+            throw new SessionContractError('INVALID_ARGUMENT', 'tail --import cannot be combined with --dry-run');
+        }
+        const provider = providerInput ? assertSessionProviderId(providerInput) : undefined;
+        if (provider)
+            assertTailSupported(createSessionAdapterRegistry().get(provider));
+        let database = helpers.databasePath(ctx, args);
+        repository = new SessionRepository(database, { readonly: true });
+        const workspace = args.values.has('--workspace') || latest
+            ? helpers.readAuthorizationContext(ctx, args, 'tail', repository).workspaceId : undefined;
+        let matches = latest
+            ? repository.listSessions({ provider, workspaceId: workspace, limit: 1 }).items
+            : repository.findSessionsByReference(reference, workspace);
+        if (provider)
+            matches = matches.filter(session => session.provider === provider);
+        // Account-scoped providers live in the referenced host catalog (#3232).
+        const references = repository.listHostSessionReferences().filter(item => !provider || item.provider === provider);
+        const hosts = new Set(references.map(item => item.hostCatalog));
+        const candidates = matches.map(session => ({ session, database }));
+        for (const hostPath of hosts) {
+            if (!existsSync(hostPath))
+                continue;
+            const host = new SessionRepository(hostPath, { readonly: true });
+            try {
+                const allowed = new Set(references.filter(item => item.hostCatalog === hostPath)
+                    .map(item => item.sessionId));
+                const sessions = latest
+                    ? references.filter(item => item.hostCatalog === hostPath)
+                        .flatMap(item => host.getSession(item.sessionId) ?? [])
+                    : host.findSessionsByReference(reference);
+                candidates.push(...sessions.filter(session => allowed.has(session.sessionId))
+                    .map(session => ({ session, database: hostPath })));
+            }
+            finally {
+                host.close();
+            }
+        }
+        const selected = latest
+            ? candidates.sort((a, b) => (b.session.updatedAt ?? '').localeCompare(a.session.updatedAt ?? '')
+                || b.session.sessionId.localeCompare(a.session.sessionId)).slice(0, 1)
+            : candidates;
+        if (selected.length !== 1) {
+            throw new SessionContractError('INVALID_ARGUMENT', selected.length
+                ? 'session reference is ambiguous; select --workspace or an internal session ID'
+                : 'session not found in the selected catalog and workspace');
+        }
+        const session = selected[0].session;
+        if (selected[0].database !== database) {
+            repository.close();
+            database = selected[0].database;
+            repository = new SessionRepository(database, { readonly: true });
+        }
+        const source = repository.getSource(session.sourceId);
+        if (!source)
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'catalog source is unavailable');
+        const config = await readAiwgConfig(isAbsolute(session.workspaceId) ? session.workspaceId : ctx.cwd);
+        const limits = resolveImportLimits(config?.sessions?.import, {
+            maxRecordBytes: args.values.get('--max-record-bytes'),
+            maxSourceBytes: args.values.get('--max-source-bytes'),
+        });
+        const adapter = createSessionAdapterRegistry(limits).get(session.provider);
+        assertTailSupported(adapter);
+        const selectedSource = await resolveTailSource(ctx, args, session, source.locatorClass, config?.sessions?.discovery_manifests ?? [], resolve(dirname(helpers.databasePath(ctx, args)), 'discovery-manifest.json'));
+        const importing = args.flags.has('--import');
+        if (importing) {
+            repository.close();
+            repository = undefined;
+            lease = await acquireImportLease(database, `sessions-tail-${process.pid}`);
+            repository = new SessionRepository(database);
+        }
+        const checkpoint = repository.getCheckpoint(source.sourceId, adapter.adapterVersion);
+        await tailSession({
+            source, selectedSource, adapter, repository, sessionId: session.sessionId,
+            workspaceId: session.workspaceId, policyVersion: checkpoint?.policyVersion ?? '1.0.0',
+            limits, signal, follow: args.flags.has('--follow'), import: importing,
+            onEvent: event => {
+                if (json)
+                    console.log(JSON.stringify({ contractVersion: '1.0.0', command: 'sessions.tail',
+                        status: 'ok', data: { event }, error: null }));
+                else
+                    console.log(`${event.occurredAt ?? '-'} ${session.provider} ${event.kind}: ${event.searchableText}`);
+            },
+            onPoll: flushStdout,
+        });
+        await flushStdout();
+        return { exitCode: 0 };
+    }
+    catch (error) {
+        if (signal.aborted)
+            return { exitCode: 0 };
+        const cliError = error instanceof Error && 'code' in error && 'exitCode' in error
+            ? error : undefined;
+        const code = error instanceof SessionContractError ? error.code
+            : cliError ? cliError.code
+                : 'code' in Object(error) && error.code === 'IMPORT_LOCKED'
+                    ? 'IMPORT_LOCKED' : 'CATALOG_UNAVAILABLE';
+        const message = redactSessionValue(error instanceof Error ? error.message : 'session tail failed').value;
+        if (json) {
+            console.log(JSON.stringify({ contractVersion: '1.0.0', command: 'sessions.tail', status: 'error',
+                data: null, error: { code, message } }));
+            await flushStdout();
+        }
+        else
+            console.error(`${code}: ${message}`);
+        return { exitCode: cliError?.exitCode ?? (code === 'UNSUPPORTED_PROVIDER' ? 3 : code === 'INVALID_ARGUMENT' ? 2
+                : code === 'IMPORT_LOCKED' ? 7 : code === 'CATALOG_UNAVAILABLE' ? 6 : 5), message };
+    }
+    finally {
+        process.removeListener('SIGINT', stop);
+        repository?.close();
+        await lease?.release();
+    }
+}
+async function resolveTailSource(ctx, args, session, locatorClass, configured, catalogManifest) {
+    const workspace = isAbsolute(session.workspaceId) ? session.workspaceId : ctx.cwd;
+    // Existing explicit input option also supports older direct imports, whose
+    // catalog intentionally never retained the unredacted native pathname.
+    const input = args.values.get('--input');
+    if (input) {
+        const locator = resolve(ctx.cwd, input);
+        return { provider: session.provider, sourceId: session.sourceId, nativeSessionId: session.nativeSessionId, locatorClass, locator,
+            authorizedScope: { workspaceId: session.workspaceId, allowedRoots: [dirname(locator)] } };
+    }
+    const paths = args.values.has('--manifest') ? [resolve(ctx.cwd, args.values.get('--manifest'))] : [
+        defaultDiscoveryManifestPath(workspace), defaultDiscoveryManifestPath(ctx.cwd), catalogManifest,
+        ...configured.map(path => resolve(workspace, path)),
+    ];
+    for (const path of new Set(paths)) {
+        if (!existsSync(path))
+            continue;
+        const manifest = await readDiscoveryManifest(path);
+        const source = manifest.sources.find(item => item.sourceId === session.sourceId
+            && item.provider === session.provider && item.locatorClass === locatorClass && item.status !== 'excluded');
+        if (source)
+            return { provider: session.provider, sourceId: session.sourceId, nativeSessionId: session.nativeSessionId, locatorClass,
+                locator: source.locator, authorizedScope: {
+                    workspaceId: session.workspaceId, allowedRoots: [source.authorizedRoot],
+                } };
+    }
+    throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'native source location is unavailable; pass its saved --manifest or explicitly authorize --input <native-source>');
+}
+function flushStdout() {
+    return new Promise((resolve, reject) => process.stdout.write('', error => error ? reject(error) : resolve()));
+}
+//# sourceMappingURL=sessions-tail.js.map

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

@@ -3,11 +3,13 @@ import { randomUUID } from 'node:crypto';
 import { basename, dirname, isAbsolute, join, resolve, } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { providerScopeWarnings } from '../../sessions/coverage-preflight.js';
-import { CLAUDE_ADAPTER_VERSION, ClaudeSessionAdapter, CODEX_ADAPTER_VERSION, CodexSessionAdapter, COPILOT_ADAPTER_VERSION, CopilotSessionAdapter, CURSOR_ADAPTER_VERSION, CursorSessionAdapter, FACTORY_ADAPTER_VERSION, FactorySessionAdapter, HERMES_ADAPTER_VERSION, HermesSessionAdapter, OPENCODE_ADAPTER_VERSION, OpenCodeSessionAdapter, OPENCLAW_ADAPTER_VERSION, OpenClawSessionAdapter, OPENHUMAN_ADAPTER_VERSION, OpenHumanSessionAdapter, GROKBOT_ADAPTER_VERSION, GROKBOT_NATIVE_REPLICA_LOCATOR_CLASS, GrokbotSessionAdapter, GROK_BUILD_ADAPTER_VERSION, GROK_BUILD_CLI_EXPORT_LOCATOR_CLASS, GrokBuildSessionAdapter, grokBuildList, grokBuildSearch, grokBuildExport, grokHeadlessSessionIdFromFile, MUSE_ADAPTER_VERSION, MuseSessionAdapter, PI_ADAPTER_VERSION, PiSessionAdapter, DEEPSEEK_HARNESS_ADAPTER_VERSION, DeepSeekHarnessSessionAdapter, OmpSessionAdapter, OMP_ADAPTER_VERSION, WARP_ADAPTER_VERSION, WarpSessionAdapter, DEVIN_DESKTOP_ADAPTER_VERSION, DevinDesktopSessionAdapter, CandidateExtractionService, GENERIC_ADAPTER_VERSION, GenericSessionInterchangeAdapter, IncrementalSessionImporter, ImportLeaseContentionError, FilesystemMemoryDestination, FilesystemPromotionDispositionCoordinator, MemoryPromotionGateway, SESSION_CONTRACT_VERSION, SessionContractError, SessionRepository, SessionSourceSchema, StructuralCandidateExtractor, resolveMemoryConsumerManifest, assertSessionProviderId, acquireImportLease, countUniqueSessionsAcrossCatalogs, defaultDiscoveryManifestPath, defaultHostCatalogPath, HOST_CATALOG_WORKSPACE_ID, indexIdentitiesBySessionId, manifestNeedsHostCatalog, mergeCrossCatalogRows, mergeSessionLists, resolveHostReferences, summarizeSessionAnalyticsFacts, discoverWorkspaceHistories, createSessionAdapterRegistry, coveragePreflight, expectedSessionProviders, deriveSessionTimeline, importDiscoveryManifest, previewDiscoveryImport, publicDiscoveryManifest, readDiscoveryManifest, redactSourceLocator, sha256, parseTimelineGap, writeDiscoveryManifest, buildSessionExportPlan, reverifySessionExportPlan, buildSessionAiwgFortemiIndexExport, recoverAiwgFortemiIndexFromFullV1Shard, embedAttachmentsInFullV1Shard, recoverEmbeddedAttachments, SESSION_EXPORT_PLAN_SCHEMA_VERSION, } from '../../sessions/index.js';
+import { CLAUDE_ADAPTER_VERSION, ClaudeSessionAdapter, CODEX_ADAPTER_VERSION, CodexSessionAdapter, COPILOT_ADAPTER_VERSION, CopilotSessionAdapter, CURSOR_ADAPTER_VERSION, CursorSessionAdapter, FACTORY_ADAPTER_VERSION, FactorySessionAdapter, HERMES_ADAPTER_VERSION, HermesSessionAdapter, OPENCODE_ADAPTER_VERSION, OpenCodeSessionAdapter, OPENCLAW_ADAPTER_VERSION, OpenClawSessionAdapter, OPENHUMAN_ADAPTER_VERSION, OpenHumanSessionAdapter, GROKBOT_ADAPTER_VERSION, GROKBOT_NATIVE_REPLICA_LOCATOR_CLASS, GrokbotSessionAdapter, GROK_BUILD_ADAPTER_VERSION, GROK_BUILD_CLI_EXPORT_LOCATOR_CLASS, GROK_BUILD_NATIVE_LOCATOR_CLASS, GrokBuildSessionAdapter, grokBuildList, grokBuildSearch, grokBuildExport, grokHeadlessSessionIdFromFile, MUSE_ADAPTER_VERSION, MuseSessionAdapter, PI_ADAPTER_VERSION, PiSessionAdapter, DEEPSEEK_HARNESS_ADAPTER_VERSION, DeepSeekHarnessSessionAdapter, OmpSessionAdapter, OMP_ADAPTER_VERSION, WARP_ADAPTER_VERSION, WarpSessionAdapter, DEVIN_DESKTOP_ADAPTER_VERSION, DevinDesktopSessionAdapter, CandidateExtractionService, GENERIC_ADAPTER_VERSION, GenericSessionInterchangeAdapter, IncrementalSessionImporter, ImportLeaseContentionError, FilesystemMemoryDestination, FilesystemPromotionDispositionCoordinator, MemoryPromotionGateway, SESSION_CONTRACT_VERSION, SessionContractError, SessionRepository, SessionSourceSchema, StructuralCandidateExtractor, resolveMemoryConsumerManifest, assertSessionProviderId, acquireImportLease, countUniqueSessionsAcrossCatalogs, defaultDiscoveryManifestPath, defaultHostCatalogPath, HOST_CATALOG_WORKSPACE_ID, indexIdentitiesBySessionId, manifestNeedsHostCatalog, mergeCrossCatalogRows, mergeSessionLists, resolveHostReferences, summarizeSessionAnalyticsFacts, discoverWorkspaceHistories, createSessionAdapterRegistry, providerDiscoveryCapability, coveragePreflight, expectedSessionProviders, deriveSessionTimeline, importDiscoveryManifest, previewDiscoveryImport, publicDiscoveryManifest, readDiscoveryManifest, redactSourceLocator, sha256, parseTimelineGap, writeDiscoveryManifest, buildSessionExportPlan, reverifySessionExportPlan, buildSessionAiwgFortemiIndexExport, recoverAiwgFortemiIndexFromFullV1Shard, embedAttachmentsInFullV1Shard, recoverEmbeddedAttachments, SESSION_EXPORT_PLAN_SCHEMA_VERSION, } from '../../sessions/index.js';
 import { resolveImportExclusions } from '../../sessions/import-exclusions.js';
 import { resolveImportLimits } from '../../sessions/import-limits.js';
 import { classifyGrokbotBlobName } from '../../sessions/adapters/grokbot-locator.js';
 import { readAiwgConfig } from '../../config/aiwg-config.js';
+import { importFromDir } from './sessions-intake.js';
+import { executeSessionsTail } from './sessions-tail.js';
 const JSON_CONTRACT_VERSION = '1.0.0';
 async function createLineMemoryPromotionDestination(projectRoot, manifestPath) {
     const modulePath = resolve(dirname(manifestPath), 'commands', 'line-memory.mjs');
@@ -38,9 +40,13 @@ Commands:
   grok-export <id> --workspace <path> --out <dir>  Export one CLI transcript
   grok-id <file> --format json|streaming-json  Read a headless session ID
   import <file> --source-id <id>  Import a supported provider JSONL source
+  import --from-dir <dir> [--source-id <prefix>]  Batch-import every recognised export in a directory
   list [--workspace <path-or-id>] [--limit N] [--cursor N]  List normalized sessions
   timeline [--workspace <path-or-id>] [--gap 30m]  Report chronological activity segments
   show <session-id> [--workspace <path-or-id>]  Show a session with events and tags
+  tail <session-id> | --provider <p> --latest [--workspace <path-or-id>] [--follow] [--json] [--import]
+                                  Read new native events; --follow polls every 500 ms
+                                  Read-only unless --import; --input <file> authorizes older direct imports
   search <query> [--workspace <path-or-id>]  Search authorized normalized content
   extract [session-id] --workspace <id> Extract structural candidates
   export plan --workspace <id> --out <file> <session-id...>  Select sessions into a reviewable plan
@@ -81,6 +87,9 @@ Options:
   --muse-root <path>  Explicitly authorize a Muse Code sessions root
   --dsh-root <path>  Explicitly authorize a DeepSeek Harness sessions root
   --grokbot-root <path>  Explicitly authorize a Grok Bot sand-client-persistence root
+  --grok-root <path>  Explicitly authorize a Grok Build sessions root (native chat_history.jsonl discovery)
+  --grok-active-sessions <path>  Explicitly authorize active_sessions.json for Grok Build live detection (read-only; requires --grok-root)
+  --hermes-root <path>  Explicitly authorize a Hermes home for a read-only state.db backup snapshot
   --grok-bin <path>  Absolute Grok Build CLI path for grok-list/grok-search/grok-export
                    (default: grok on PATH, then $GROK_HOME/bin/grok)
   --confirm, --yes  Confirm a persistent discovered batch import
@@ -92,6 +101,9 @@ Options:
   --inactivity-threshold <duration>  Historical inactivity threshold (default 24h)
   --min-coverage <0..1>  Fail list/report commands below a coverage ratio
   --provider <id> Filter list or select an import adapter
+  --from-dir <dir>  Batch-import every recognised export file in a directory (import only);
+                   --source-id becomes an optional per-file source-ID prefix;
+                   files already imported are skipped by content digest
   --consumer <id> Select a named memory consumer for promotion
   --tag <tag>, --limit <n>, --cursor <n>
   --page-size <n>  Extraction scan page size (default 250, maximum 500)
@@ -156,6 +168,8 @@ export const sessionsHandler = {
             const explicitHelp = parsed.flags.has('--help') || parsed.flags.has('-h');
             return printHelp(ctx, explicitHelp ? EXIT.ok : EXIT.usage);
         }
+        if (parsed.command === 'tail')
+            return executeSessionsTail(ctx, parsed, { databasePath, readAuthorizationContext });
         try {
             const result = await executeCommand(ctx, parsed);
             if (json)
@@ -179,7 +193,10 @@ async function executeCommand(ctx, args) {
     const command = args.command;
     if (command === 'sources') {
         const registry = createSessionAdapterRegistry();
-        const reports = registry.list().map((adapter) => providerDisposition(adapter.provider));
+        const reports = registry.list().map((adapter) => ({
+            ...providerDisposition(adapter.provider),
+            discovery: providerDiscoveryCapability(adapter.provider, adapter.supportedOperations),
+        }));
         const preflight = coveragePreflight({ expectedProviders: requestedProviders(args), registry });
         return ok(command, { providers: reports, count: reports.length, preflight });
     }
@@ -794,10 +811,7 @@ async function executeCommand(ctx, args) {
         repository.close();
     }
 }
-async function importSource(ctx, args) {
-    const limits = await configuredImportLimits(ctx, args);
-    const input = resolve(ctx.cwd, requiredPositional(args, 0, 'file'));
-    const providerInput = args.values.get('--provider') ?? 'generic';
+function assertSupportedImportProvider(providerInput) {
     const provider = assertSessionProviderId(providerInput);
     if (provider !== 'generic' && provider !== 'claude' && provider !== 'codex'
         && provider !== 'copilot' && provider !== 'cursor' && provider !== 'factory'
@@ -805,6 +819,57 @@ async function importSource(ctx, args) {
         && provider !== 'openhuman' && provider !== 'grokbot' && provider !== 'grok-build' && provider !== 'muse' && 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);
     }
+    return provider;
+}
+function adapterVersionFor(provider) {
+    switch (provider) {
+        case 'claude': return CLAUDE_ADAPTER_VERSION;
+        case 'codex': return CODEX_ADAPTER_VERSION;
+        case 'copilot': return COPILOT_ADAPTER_VERSION;
+        case 'cursor': return CURSOR_ADAPTER_VERSION;
+        case 'factory': return FACTORY_ADAPTER_VERSION;
+        case 'hermes': return HERMES_ADAPTER_VERSION;
+        case 'opencode': return OPENCODE_ADAPTER_VERSION;
+        case 'openclaw': return OPENCLAW_ADAPTER_VERSION;
+        case 'openhuman': return OPENHUMAN_ADAPTER_VERSION;
+        case 'grokbot': return GROKBOT_ADAPTER_VERSION;
+        case 'grok-build': return GROK_BUILD_ADAPTER_VERSION;
+        case 'muse': return MUSE_ADAPTER_VERSION;
+        case 'pi': return PI_ADAPTER_VERSION;
+        case 'omp': return OMP_ADAPTER_VERSION;
+        case 'deepseek-harness': return DEEPSEEK_HARNESS_ADAPTER_VERSION;
+        case 'warp': return WARP_ADAPTER_VERSION;
+        case 'devin-desktop': return DEVIN_DESKTOP_ADAPTER_VERSION;
+        default: return GENERIC_ADAPTER_VERSION;
+    }
+}
+/**
+ * `aiwg sessions import --from-dir <dir>` (#3168). Batch-imports every
+ * recognised provider export file in one intake directory: one receipt per
+ * file plus a summary. Files already imported are skipped by content digest
+ * before any adapter work; unrecognised files are skipped with a reason.
+ * Each remaining file imports through the single-file path, so adapter
+ * selection, redaction, and idempotency semantics are identical.
+ */
+function importFailureReason(error) {
+    if (error instanceof CliError)
+        return `${error.code}: ${error.message}`;
+    if (error instanceof SessionContractError)
+        return `${error.code}: ${error.message}`;
+    return `IMPORT_INTERRUPTED: ${error instanceof Error ? error.message : String(error)}`;
+}
+async function importSource(ctx, args) {
+    const fromDir = args.values.get('--from-dir');
+    if (fromDir !== undefined) {
+        return importFromDir(ctx, args, resolve(ctx.cwd, fromDir), {
+            assertSupportedImportProvider, normalizeWorkspaceId, isDryRun, preview, ok,
+            openRepository, adapterVersionFor, importSource, importFailureReason,
+        });
+    }
+    const limits = await configuredImportLimits(ctx, args);
+    const input = resolve(ctx.cwd, requiredPositional(args, 0, 'file'));
+    const providerInput = args.values.get('--provider') ?? 'generic';
+    const provider = assertSupportedImportProvider(providerInput);
     const sourceId = requiredValue(args, '--source-id');
     const workspaceId = args.values.has('--workspace')
         ? normalizeWorkspaceId(ctx.cwd, args.values.get('--workspace'))
@@ -822,6 +887,8 @@ async function importSource(ctx, args) {
     const isGrokbotNative = isGrokbot
         && classifyGrokbotBlobName(basename(input))?.kind === 'transcript-replica';
     const isGrokBuild = provider === 'grok-build';
+    const isGrokBuildNative = isGrokBuild
+        && basename(input) === 'chat_history.jsonl';
     const isMuse = provider === 'muse';
     const isPi = provider === 'pi';
     const isOmp = provider === 'omp';
@@ -880,7 +947,7 @@ async function importSource(ctx, args) {
                                         : isGrokbot
                                             ? (isGrokbotNative ? GROKBOT_NATIVE_REPLICA_LOCATOR_CLASS : 'manual-export')
                                             : isGrokBuild
-                                                ? GROK_BUILD_CLI_EXPORT_LOCATOR_CLASS
+                                                ? (isGrokBuildNative ? GROK_BUILD_NATIVE_LOCATOR_CLASS : GROK_BUILD_CLI_EXPORT_LOCATOR_CLASS)
                                                 : isMuse
                                                     ? 'manual-export'
                                                     : isPi
@@ -919,7 +986,7 @@ async function importSource(ctx, args) {
                                             : isGrokbot
                                                 ? (isGrokbotNative ? 'grokbot-native-transcript-replica-v1' : 'manual-interchange')
                                                 : isGrokBuild
-                                                    ? 'documented-cli-markdown-export'
+                                                    ? (isGrokBuildNative ? 'grok-build-native-chat-history-v1' : 'documented-cli-markdown-export')
                                                     : isMuse
                                                         ? 'muse-export-trajectory-v1'
                                                         : isWarp
@@ -986,7 +1053,7 @@ async function importSource(ctx, args) {
                                             : isGrokbot
                                                 ? { 'native.grokbot': {} }
                                                 : isGrokBuild
-                                                    ? { 'native.grok-build': { acquisition: 'grok-cli-export-markdown' } }
+                                                    ? { 'native.grok-build': { acquisition: isGrokBuildNative ? GROK_BUILD_NATIVE_LOCATOR_CLASS : 'grok-cli-export-markdown' } }
                                                     : isMuse
                                                         ? { 'native.muse': {} }
                                                         : isWarp
@@ -1335,6 +1402,12 @@ async function discoverWorkspace(ctx, args) {
             ? resolve(ctx.cwd, args.values.get('--dsh-root')) : undefined,
         grokbotRoot: args.values.has('--grokbot-root')
             ? resolve(ctx.cwd, args.values.get('--grokbot-root')) : undefined,
+        grokRoot: args.values.has('--grok-root')
+            ? resolve(ctx.cwd, args.values.get('--grok-root')) : undefined,
+        grokActiveSessions: args.values.has('--grok-active-sessions')
+            ? resolve(ctx.cwd, args.values.get('--grok-active-sessions')) : undefined,
+        hermesRoot: args.values.has('--hermes-root')
+            ? resolve(ctx.cwd, args.values.get('--hermes-root')) : undefined,
         codexRoots: [
             ...(config?.sessions?.codex_roots ?? []).map((root) => resolve(workspace, root)),
             ...args.codexRoots.map((root) => resolve(ctx.cwd, root)),
@@ -1532,10 +1605,10 @@ function providerDisposition(provider) {
     if (provider === 'hermes') {
         return {
             provider, disposition: 'implemented', operationalState: 'available',
-            supportedOperations: ['inspect', 'stream'],
+            supportedOperations: ['discover', 'inspect', 'stream'],
             acquisitionModes: ['jsonl', 'api', 'sqlite-snapshot'],
             reasonCode: null,
-            remediation: 'Use `hermes sessions export` or an explicitly verified sqlite3.backup() snapshot export.',
+            remediation: 'Pass --hermes-root with an explicitly authorized Hermes home for a read-only state.db backup snapshot; or use `hermes sessions export` and import the explicitly authorized JSONL file.',
             evidence: {
                 adapterVersion: HERMES_ADAPTER_VERSION,
                 verifiedAt: '2026-07-27',
@@ -1643,10 +1716,10 @@ function providerDisposition(provider) {
     if (provider === 'grok-build') {
         return {
             provider, disposition: 'implemented', operationalState: 'available',
-            supportedOperations: ['inspect', 'stream'],
-            acquisitionModes: ['manual-export'],
-            reasonCode: 'CLI_EXPORT_REQUIRED',
-            remediation: 'Run `grok sessions list`, then `grok export <session-id> <session-id>.md` and import the explicitly authorized Markdown file. `aiwg sessions grok-list` finds `grok` on PATH or in $GROK_HOME/bin; pass --grok-bin <absolute path> otherwise.',
+            supportedOperations: ['discover', 'inspect', 'stream'],
+            acquisitionModes: ['manual-export', 'jsonl'],
+            reasonCode: null,
+            remediation: 'Pass --grok-root with an explicitly authorized sessions root for native chat_history.jsonl discovery, optionally with --grok-active-sessions for live detection; or run `grok export <session-id> <session-id>.md` and import the explicitly authorized Markdown file.',
             evidence: {
                 adapterVersion: GROK_BUILD_ADAPTER_VERSION,
                 verifiedAt: '2026-09-21',
@@ -1922,12 +1995,12 @@ function parseArgs(argv) {
     const exclude = [];
     const positionals = [];
     const valueFlags = new Set([
-        '--db', '--provider', '--workspace', '--tag', '--limit', '--cursor', '--source-id',
+        '--db', '--provider', '--workspace', '--tag', '--limit', '--cursor', '--source-id', '--from-dir',
         '--date-from', '--date-to', '--participant', '--model', '--role', '--tool',
         '--entity', '--sensitivity', '--extraction-state', '--page-size', '--max-documents',
         '--state', '--reviewer', '--reason', '--policy-version', '--min-confidence',
         '--consumer', '--actor-class', '--reason-code', '--dependent-action', '--basis',
-        '--carry-forward', '--manifest', '--provider-home', '--codex-root', '--omp-root', '--muse-root', '--dsh-root', '--grokbot-root', '--lock-wait-ms', '--min-coverage', '--gap',
+        '--carry-forward', '--manifest', '--provider-home', '--codex-root', '--omp-root', '--muse-root', '--dsh-root', '--grokbot-root', '--grok-root', '--grok-active-sessions', '--hermes-root', '--lock-wait-ms', '--min-coverage', '--gap',
         '--inactivity-threshold', '--expected-providers', '--exclude', '--max-record-bytes', '--max-source-bytes',
         '--control-events',
         '--session', '--status', '--actor', '--group-by',

package/dist/src/cli/handlers/skill-lint.js

@@ -13,6 +13,8 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { validateSkillFrontmatter } from '../../extensions/validation.js';
 import { validateAgentSkillFile } from '../../skills/validator.js';
+import { CLAUDE_SKILL_FIELDS } from '../../skills/provider-extensions.js';
+import { projectClaudeSkillSurfaces } from '../../skills/claude-surface-projection.js';
 const THRESHOLDS = {
     strict: 80,
     standard: 60,
@@ -44,7 +46,10 @@ function scoreSchema(frontmatter, diagnostics) {
             : `${item.yamlPath}: ${item.message} [${item.code}]`));
         return scoreDimension(false, notes);
     }
-    const result = validateSkillFrontmatter(frontmatter);
+    // Native Claude fields belong to the provider layer, including string effort.
+    const portableAndAiwg = Object.fromEntries(Object.entries(frontmatter)
+        .filter(([key]) => !CLAUDE_SKILL_FIELDS.includes(key)));
+    const result = validateSkillFrontmatter(portableAndAiwg);
     if (result.success)
         return scoreDimension(true);
     const notes = result.errors.issues.map((e) => `${e.path.join('.') || '<root>'}: ${e.message}`);
@@ -211,6 +216,7 @@ export async function lintSkillFile(filePath, rubric = 'standard', profile = 'co
     return {
         file: filePath,
         score,
+        projections: projectClaudeSkillSurfaces(body),
         conformance: {
             profile,
             state: validation.state,
@@ -321,14 +327,15 @@ function parseArgs(args) {
 function renderTextReport(report) {
     const { files, threshold, rubric, profile, averageScore, failedCount } = report;
     for (const f of files) {
-        if (f.passes && f.conformance.diagnostics.length === 0)
-            continue;
         const mark = !f.passes
             ? '✗'
             : f.conformance.diagnostics.some((item) => item.severity === 'warning')
                 ? '⚠'
                 : '✓';
         console.log(`${mark} ${f.file} (${f.score}/100, conformance=${f.conformance.state})`);
+        for (const p of f.projections) {
+            console.log(`    ${p.provider}/${p.surface}: ${p.status}${p.shellInterpolation ? ` (shell: ${p.shellInterpolation})` : ''}; ${p.reasons.join(' ')}`);
+        }
         for (const item of f.conformance.diagnostics) {
             console.log(`    ${item.severity} ${item.code} ${item.yamlPath}: ${item.message}; `
                 + `fix: ${item.remediation}`);

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

@@ -0,0 +1,100 @@
+// Formats the steward capability matrix and permission command usage.
+import { isExternalStrategy } from '../../providers/capability-matrix.js';
+export function printFullMatrix(matrix) {
+    const { providers, features } = matrix;
+    const providerIds = Object.keys(providers);
+    const featureIds = Object.keys(features);
+    console.log(`\n  Provider Capability Matrix (v${matrix.version})`);
+    console.log(`  ✓ = native   ~ = AIWG emulation   - = not supported\n`);
+    const featureColW = 20;
+    const provColW = 14;
+    const header = '  ' + 'Feature'.padEnd(featureColW) + providerIds.map(p => p.padEnd(provColW)).join('');
+    console.log(header);
+    console.log('  ' + '─'.repeat(featureColW + providerIds.length * provColW));
+    for (const featureId of featureIds) {
+        const feat = features[featureId];
+        let row = '  ' + featureId.padEnd(featureColW);
+        for (const providerId of providerIds) {
+            const provider = providers[providerId];
+            const isNative = provider?.native_features?.[featureId] === true;
+            const emulation = provider?.emulation?.[featureId] ?? null;
+            const mark = isNative ? '✓' : (emulation ? '~' : '-');
+            row += mark.padEnd(provColW);
+        }
+        console.log(row);
+        if (feat?.description) {
+            console.log('  ' + ' '.repeat(featureColW) + feat.description);
+        }
+        console.log('');
+    }
+}
+// ── Main execution ─────────────────────────────────────────────────────────────
+export function permissionsUsage() {
+    return `
+  aiwg steward permissions — authorization model audit and normalization
+
+  Usage:
+    aiwg steward permissions audit                 Find normalized-model errors and legacy grants
+    aiwg steward permissions migrate --dry-run     Preview legacy permission normalization
+    aiwg steward permissions migrate --apply       Back up and atomically normalize config
+
+  Reads .aiwg/aiwg.config authorization block. Migration backs up before writing.
+`;
+}
+const NATIVE_MARK = '✓ native';
+const EMULATED_MARK = '~ emulated';
+const EXTERNAL_MARK = '↗ external';
+const UNSUPPORTED_MARK = '- not supported';
+export function emulationLabel(strategy) {
+    if (!strategy)
+        return 'none';
+    if (strategy === 'native')
+        return 'native (no fallback needed)';
+    return strategy;
+}
+export function formatProvider(id, provider, matrix, meta) {
+    const lines = [];
+    lines.push(`\n  Provider: ${provider.display_name} (${id})`);
+    if (meta) {
+        lines.push(`  Project-local: yes`);
+        lines.push(`  Base adapter:   ${meta.baseAdapter}`);
+    }
+    lines.push(`  Status:   ${provider.status}`);
+    lines.push(`  Daemon:   ${provider.daemon_tier}${provider.daemon_pty_adapter ? ' (+ pty-adapter)' : ''}`);
+    lines.push(`  ${'─'.repeat(60)}`);
+    const featureKeys = Object.keys(matrix.features);
+    for (const featureId of featureKeys) {
+        const isNative = provider.native_features?.[featureId] === true;
+        const emulation = provider.emulation?.[featureId] ?? null;
+        const status = isNative
+            ? NATIVE_MARK
+            : isExternalStrategy(emulation) ? EXTERNAL_MARK : (emulation ? EMULATED_MARK : UNSUPPORTED_MARK);
+        const feat = matrix.features[featureId];
+        lines.push(`\n  ${featureId} — ${status}`);
+        if (feat?.description)
+            lines.push(`    ${feat.description}`);
+        if (isNative) {
+            if (id === 'omp' && featureId === 'mcp') {
+                lines.push('    OMP supplies the native client. AIWG persistent injection/removal is available for project and profile scope; ephemeral injection is unsupported.');
+                lines.push('    example: aiwg mcp inject --provider omp --servers local-tools');
+            }
+            else if (id === 'omp' && featureId === 'behaviors') {
+                lines.push('    AIWG bridges selected handlers through an OMP extension; no default policy is installed. Permission-request and pre-compaction enforcement are unsupported.');
+            }
+            else if (id === 'omp' && (featureId === 'tasks' || featureId === 'agent_teams')) {
+                lines.push('    OMP native leaf tasks use AIWG workspace admission limits and verified child results; nested requests share the same scheduler.');
+                lines.push('    example: aiwg team run --provider omp --body-file tasks.json');
+            }
+            else if (feat?.native_example)
+                lines.push(`    example: ${feat.native_example}`);
+        }
+        else if (isExternalStrategy(emulation)) {
+            lines.push(`    trigger: system cron, systemd timer, or CI; AIWG does not own the clock`);
+        }
+        else if (emulation) {
+            lines.push(`    fallback: ${emulationLabel(emulation)}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=steward-format.js.map