@aiwg/cli 2026.10.10 → 2026.10.12

package/dist/src/sessions/refresh.js

@@ -1,4 +1,4 @@
-import { existsSync, realpathSync } from 'node:fs';
+import { existsSync, mkdirSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { requireFeaturePackage } from '../features/runtime.js';
 import { readAiwgConfig } from '../config/aiwg-config.js';
@@ -6,6 +6,7 @@ import { createSessionAdapterRegistry } from './adapter-registry.js';
 import { resolveImportExclusions } from './import-exclusions.js';
 import { resolveImportLimits } from './import-limits.js';
 import { acquireImportLease } from './import-lease.js';
+import { defaultHostCatalogPath, manifestNeedsHostCatalog } from './host-catalog.js';
 import { SessionRepository } from './repository.js';
 import { importDiscoveryManifest } from './batch-import.js';
 import { defaultDiscoveryManifestPath, discoverWorkspaceHistories, readDiscoveryManifest, writeDiscoveryManifest, } from './workspace-discovery.js';
@@ -69,8 +70,26 @@ export async function refreshSessionCatalog(workspace, full, waitMs, signal, wor
             return 'no authorized provider roots';
     }
     const lease = await acquireImportLease(database, `index-refresh-${process.pid}`, { waitMs });
+    let hostLease;
     try {
         const repository = new SessionRepository(database);
+        // Account-scoped providers import once into the host catalog; the
+        // hourly host refresh (#310) routes them there instead of copying
+        // them into every workspace catalog (#3232). The host catalog is only
+        // opened when a manifest actually holds an account-scoped source.
+        const hostCatalogPath = defaultHostCatalogPath();
+        const needsHost = manifests.some((entry) => manifestNeedsHostCatalog(entry.manifest.sources));
+        let hostRepository;
+        if (needsHost) {
+            mkdirSync(path.dirname(hostCatalogPath), { recursive: true, mode: 0o700 });
+            // The workspace lease above does not cover the shared host catalog,
+            // so overlapping refreshes from two workspaces would stage the same
+            // replicas concurrently (#3232). Serialize host writers with the
+            // same lock pattern; the shared checkpoint then turns the second
+            // writer into duplicate references instead of a double import.
+            hostLease = await acquireImportLease(hostCatalogPath, `host-refresh-${process.pid}`, { waitMs });
+            hostRepository = new SessionRepository(hostCatalogPath);
+        }
         try {
             if (full)
                 repository.reindex();
@@ -82,7 +101,9 @@ export async function refreshSessionCatalog(workspace, full, waitMs, signal, wor
                         continue;
                     // Persist the exact discovered batch before its confirmed import.
                     await writeDiscoveryManifest(entry.path, entry.manifest);
-                    const receipt = await importDiscoveryManifest({ manifest: entry.manifest, repository, signal, limits, exclude });
+                    const receipt = await importDiscoveryManifest({
+                        manifest: entry.manifest, repository, hostRepository, hostCatalogPath, signal, limits, exclude,
+                    });
                     if (receipt.totals.pending) {
                         throw new Error(`session import incomplete: ${receipt.totals.rejected} rejected, ${receipt.totals.pending} pending`);
                     }
@@ -94,10 +115,12 @@ export async function refreshSessionCatalog(workspace, full, waitMs, signal, wor
             }
         }
         finally {
+            hostRepository?.close();
             repository.close();
         }
     }
     finally {
+        await hostLease?.release();
         await lease.release();
     }
     return undefined;

package/dist/src/sessions/repository.js

@@ -2,8 +2,10 @@ import { requireFeaturePackage } from '../features/runtime.js';
 import { CandidateReviewReceiptSchema, DeletionReceiptSchema, IntelligenceCandidateSchema, PromotionDependencyDecisionSchema, PromotionReceiptSchema, SessionContractError, sha256, } from './contracts.js';
 import { coverageFromBatchRun, } from './batch-contracts.js';
 import { redactSessionText, redactSessionValue, sanitizeSessionEvent, sanitizeNativeExtensions } from './policy.js';
+import { extractBatchEventImages, isImageDigest, } from './image-blobs.js';
 import { effectiveSessionLifecycle } from './lifecycle.js';
 import { deriveSessionAnalytics, } from './analytics.js';
+import { HOST_REFERENCE_TABLE_DDL, } from './host-catalog.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 (
@@ -114,6 +116,17 @@ export class SessionRepository {
       CREATE TABLE IF NOT EXISTS session_catalog_meta (
         key TEXT PRIMARY KEY, value TEXT NOT NULL
       );
+      -- Content-addressed tool-output image bytes (#3265). One row per
+      -- content hash per catalog: repeat imports of identical images share
+      -- the row (INSERT OR IGNORE). Events reference blobs by digest and
+      -- keep only a bracketed image placeholder (sha256, type, size) in
+      -- searchableText, so image bytes never reach FTS. Pre-#3265 rows with
+      -- inline bytes are left untouched (no destructive migration).
+      CREATE TABLE IF NOT EXISTS session_image_blobs (
+        digest TEXT PRIMARY KEY, media_type TEXT NOT NULL,
+        byte_length INTEGER NOT NULL, source_locator TEXT,
+        source_offset INTEGER, bytes BLOB NOT NULL
+      );
       CREATE TABLE IF NOT EXISTS session_analytics_facts (
         fact_id TEXT PRIMARY KEY, workspace_id TEXT NOT NULL,
         session_id TEXT NOT NULL, event_id TEXT NOT NULL,
@@ -144,6 +157,9 @@ export class SessionRepository {
       -- alignment without reading searchable text or event JSON.
       CREATE INDEX IF NOT EXISTS idx_fts_event_id ON session_event_fts_content(c0);
     `);
+        // Workspace pointers at account-scoped sessions stored in the host
+        // catalog (#3232). References, never copies; legacy copied rows stay.
+        this.db.exec(HOST_REFERENCE_TABLE_DDL);
         const deletionReceiptColumns = this.db.prepare('PRAGMA table_info(deletion_receipts)').all().map((row) => String(row.name));
         if (!deletionReceiptColumns.includes('workspace_id')) {
             this.db.exec('ALTER TABLE deletion_receipts ADD COLUMN workspace_id TEXT');
@@ -479,6 +495,18 @@ export class SessionRepository {
         };
     }
     applyImport(batch, checkpoint, publish = true) {
+        // Lift inline image payloads out of event text before redaction (#3265):
+        // base64 data URLs in text survive redaction and would otherwise be
+        // stored inline. Provider image blocks in extensions keep their existing
+        // redaction to markers; their bytes are not retained.
+        // Idempotent -- placeholder text from an earlier pass matches no image
+        // pattern, so importer-extracted batches and direct writers converge.
+        // Bytes are parked beside the batch: the redaction pass below walks
+        // every value and would flatten Uint8Array into plain objects.
+        const extracted = extractBatchEventImages(batch);
+        const imageBlobs = extracted.imageBlobs;
+        batch = { ...batch, events: extracted.events };
+        delete batch.imageBlobs;
         // Guard callers that submit normalized batches directly as well as adapters.
         batch = redactSessionValue({
             ...batch,
@@ -525,6 +553,17 @@ export class SessionRepository {
                 const merged = mergeSessionAggregate(prior, session);
                 this.db.prepare(`UPDATE sessions SET source_digest=?, lifecycle=?, data=? WHERE session_id=?`).run(merged.sourceDigest, merged.lifecycle, JSON.stringify(merged), merged.sessionId);
             }
+            // Persist image bytes once per content hash per catalog (#3265).
+            // INSERT OR IGNORE keeps the first-seen row when identical images
+            // arrive in later batches or replayed records.
+            const insertImageBlob = this.db.prepare(`INSERT OR IGNORE INTO session_image_blobs
+         (digest, media_type, byte_length, source_locator, source_offset, bytes)
+         VALUES (?, ?, ?, ?, ?, ?)`);
+            for (const image of imageBlobs) {
+                if (!isImageDigest(image.digest))
+                    continue;
+                insertImageBlob.run(image.digest, image.mediaType, image.byteLength, image.locatorClass ?? null, image.offset ?? null, Buffer.from(image.bytes));
+            }
             const insertEvent = this.db.prepare(`INSERT OR IGNORE INTO session_events
          (event_id, session_id, source_id, import_run_id, sequence_no, digest, data)
          VALUES (?, ?, ?, ?, ?, ?, ?)`);
@@ -746,6 +785,49 @@ export class SessionRepository {
     listWorkspaceIds() {
         return this.db.prepare('SELECT DISTINCT workspace_id FROM sessions ORDER BY workspace_id').all().map((row) => String(row.workspace_id));
     }
+    /**
+     * Record a workspace pointer at an account-scoped session stored in the
+     * host catalog (#3232). Non-destructive: existing copied rows are left
+     * untouched and remain readable.
+     */
+    recordHostSessionReference(reference) {
+        this.db.prepare(`INSERT INTO session_host_refs
+         (provider, native_session_id, session_id, source_id, host_catalog)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(provider, native_session_id) DO UPDATE SET
+         session_id=excluded.session_id, source_id=excluded.source_id,
+         host_catalog=excluded.host_catalog`).run(reference.provider, reference.nativeSessionId, reference.sessionId, reference.sourceId, reference.hostCatalog);
+    }
+    listHostSessionReferences() {
+        return this.db.prepare(`SELECT provider, native_session_id, session_id, source_id, host_catalog
+       FROM session_host_refs ORDER BY provider, native_session_id`).all().map((row) => ({
+            provider: String(row.provider),
+            nativeSessionId: String(row.native_session_id),
+            sessionId: String(row.session_id),
+            sourceId: String(row.source_id),
+            hostCatalog: String(row.host_catalog),
+        }));
+    }
+    /**
+     * Visible sessions reduced to aggregate identities (plus the internal ids
+     * reference recording needs). Aggregate search/analytics over several
+     * catalogs dedupe on provider + native session so legacy copied rows
+     * count once (#3232).
+     */
+    listSessionIdentities(workspaceId) {
+        const where = workspaceId
+            ? `s.workspace_id=? AND ${VISIBLE_SESSION_PREDICATE}`
+            : VISIBLE_SESSION_PREDICATE;
+        const params = workspaceId ? [workspaceId] : [];
+        return this.db.prepare(`SELECT json_extract(s.data, '$.provider') AS provider, s.native_session_id,
+              s.session_id, s.source_id
+       FROM sessions s WHERE ${where} ORDER BY s.session_id`).all(...params).map((row) => ({
+            provider: String(row.provider),
+            nativeSessionId: String(row.native_session_id),
+            sessionId: String(row.session_id),
+            sourceId: String(row.source_id),
+        }));
+    }
     saveBatchImportRun(run) {
         run = redactSessionValue(run).value;
         const save = this.db.transaction(() => {
@@ -889,6 +971,62 @@ export class SessionRepository {
        ORDER BY e.sequence_no, e.event_id`).all(...(workspaceId ? [sessionId, workspaceId] : [sessionId]))
             .map((row) => JSON.parse(String(row.data)));
     }
+    /**
+     * Distinct image blobs in this catalog. Identical images share one row
+     * per content hash, so this counts unique images, not references (#3265).
+     */
+    countImageBlobs() {
+        return Number(this.db.prepare('SELECT COUNT(*) AS count FROM session_image_blobs').get()?.count ?? 0);
+    }
+    /**
+     * Fetch one image blob by content digest. Returns null when the blob is
+     * unknown or the digest is malformed -- callers report that as an
+     * "unavailable" reference rather than failing the whole read (#3265).
+     * Pre-#3265 rows carry inline bytes instead of references and never reach
+     * this lookup; they load verbatim through `listEvents`.
+     */
+    getImageBlob(digest) {
+        if (!isImageDigest(digest))
+            return null;
+        const row = this.db.prepare(`SELECT digest, media_type, byte_length, source_locator, source_offset, bytes
+       FROM session_image_blobs WHERE digest=?`).get(digest);
+        if (!row)
+            return null;
+        return {
+            digest: String(row.digest),
+            mediaType: String(row.media_type),
+            byteLength: Number(row.byte_length),
+            sourceLocator: row.source_locator === null ? null : String(row.source_locator),
+            sourceOffset: row.source_offset === null ? null : Number(row.source_offset),
+            bytes: Uint8Array.from(row.bytes),
+        };
+    }
+    /**
+     * Resolve an event's image references against the blob store. Entries
+     * whose bytes are present resolve `available`; entries whose blob is
+     * missing (pruned catalog, legacy reference) resolve `unavailable` with
+     * the reference metadata intact so callers can report it (#3265). Events
+     * without references -- including pre-#3265 inline rows -- resolve to [].
+     */
+    resolveEventImages(event) {
+        return (event.imageRefs ?? []).map((ref) => {
+            const stored = this.getImageBlob(ref.digest);
+            if (!stored)
+                return { ...ref, status: 'unavailable' };
+            return {
+                digest: ref.digest,
+                mediaType: stored.mediaType,
+                byteLength: stored.byteLength,
+                ...(ref.locatorClass !== undefined
+                    ? { locatorClass: ref.locatorClass }
+                    : stored.sourceLocator !== null ? { locatorClass: stored.sourceLocator } : {}),
+                ...(ref.offset !== undefined
+                    ? { offset: ref.offset }
+                    : stored.sourceOffset !== null ? { offset: stored.sourceOffset } : {}),
+                status: 'available',
+            };
+        });
+    }
     listTimelineInputs(workspaceId) {
         return this.db.prepare(`SELECT s.data AS session_data, e.data AS event_data
        FROM session_events e
@@ -1168,28 +1306,7 @@ export class SessionRepository {
     }
     analyticsSummary(options) {
         const facts = this.listAnalyticsFacts({ ...options, limit: options.limit ?? 5_000 });
-        const byCategory = countBy(facts, (fact) => fact.category);
-        const byStatus = countBy(facts, (fact) => fact.status);
-        const byProvider = countBy(facts, (fact) => fact.provider);
-        const byTool = countBy(facts.filter((fact) => fact.toolName), (fact) => fact.toolName);
-        return {
-            analyticsVersion: '1.0.0',
-            workspaceId: options.workspaceId,
-            totals: {
-                facts: facts.length,
-                sessions: new Set(facts.map((fact) => fact.sessionId)).size,
-                toolCalls: facts.filter((fact) => fact.category === 'tool-call').length,
-                toolFailures: facts.filter((fact) => fact.category === 'tool-result' && fact.status === 'failed').length,
-                escalations: facts.filter((fact) => fact.category === 'escalation').length,
-                hitlDecisions: facts.filter((fact) => fact.category === 'hitl').length,
-                indicators: facts.filter((fact) => fact.category === 'indicator').length,
-                retryGroups: new Set(facts.map((fact) => fact.retryGroupId).filter(Boolean)).size,
-            },
-            byCategory,
-            byStatus,
-            byProvider,
-            byTool,
-        };
+        return summarizeSessionAnalyticsFacts(facts, options.workspaceId);
     }
     getAnalyticsEvidence(id, workspaceId) {
         const row = this.db.prepare(`SELECT f.data AS fact_data, e.data AS event_data
@@ -1852,6 +1969,31 @@ function canonicalDevinLocator(value) {
         ? `devin-desktop-${value.slice('windsurf-'.length)}`
         : value;
 }
+/**
+ * Summarize analytics facts without touching a catalog, so cross-catalog
+ * merges (workspace facts plus referenced host facts, #3232) report the
+ * same shape as a single-catalog summary.
+ */
+export function summarizeSessionAnalyticsFacts(facts, workspaceId) {
+    return {
+        analyticsVersion: '1.0.0',
+        workspaceId,
+        totals: {
+            facts: facts.length,
+            sessions: new Set(facts.map((fact) => fact.sessionId)).size,
+            toolCalls: facts.filter((fact) => fact.category === 'tool-call').length,
+            toolFailures: facts.filter((fact) => fact.category === 'tool-result' && fact.status === 'failed').length,
+            escalations: facts.filter((fact) => fact.category === 'escalation').length,
+            hitlDecisions: facts.filter((fact) => fact.category === 'hitl').length,
+            indicators: facts.filter((fact) => fact.category === 'indicator').length,
+            retryGroups: new Set(facts.map((fact) => fact.retryGroupId).filter(Boolean)).size,
+        },
+        byCategory: countBy(facts, (fact) => fact.category),
+        byStatus: countBy(facts, (fact) => fact.status),
+        byProvider: countBy(facts, (fact) => fact.provider),
+        byTool: countBy(facts.filter((fact) => fact.toolName), (fact) => fact.toolName),
+    };
+}
 function countBy(items, key) {
     const counts = {};
     for (const item of items) {

package/dist/src/sessions/tail.js

@@ -0,0 +1,91 @@
+// Follow a native source through the importer's normalization and checkpoint rules.
+import { setTimeout } from 'node:timers/promises';
+import { SessionContractError, assertSessionResourceLimit, assertSupportedSchemaMajor, sha256 } from './contracts.js';
+import { IncrementalSessionImporter } from './importer.js';
+import { normalizeSessionBatch } from './normalization.js';
+import { assertImportByteLimit, DEFAULT_IMPORT_BYTE_LIMITS } from './import-limits.js';
+export function assertTailSupported(adapter) {
+    if (typeof adapter.stream !== 'function' || !adapter.supportedOperations.includes('stream')) {
+        throw new SessionContractError('UNSUPPORTED_PROVIDER', `sessions tail is unsupported for provider ${adapter.provider}: adapter has no stream operation`);
+    }
+}
+export async function tailSession(options) {
+    assertTailSupported(options.adapter);
+    assertSupportedSchemaMajor(options.source.sourceSchemaVersion, options.adapter.sourceSchemaMajor ?? 1);
+    if (options.workspaceId !== options.selectedSource.authorizedScope.workspaceId) {
+        throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'tail workspace is outside the authorized source scope');
+    }
+    const pollMs = options.pollMs ?? 500;
+    if (!Number.isInteger(pollMs) || pollMs < 1 || pollMs > 500) {
+        throw new SessionContractError('INVALID_ARGUMENT', 'tail poll interval must be between 1 and 500 ms');
+    }
+    let checkpoint = options.repository.getCheckpoint(options.source.sourceId, options.adapter.adapterVersion);
+    const port = {
+        getCheckpoint: () => checkpoint,
+        getBatchCheckpoint: () => null,
+        commitStagedImports: () => 0,
+        applyImport: (batch, next) => {
+            // Publish through the existing import transaction only with explicit opt-in.
+            const receipt = options.repository.applyImport(batch, next, true);
+            checkpoint = { ...next };
+            for (const event of batch.events) {
+                if (event.sessionId === options.sessionId)
+                    options.onEvent(event);
+            }
+            return receipt;
+        },
+    };
+    const importer = new IncrementalSessionImporter(port);
+    while (!options.signal?.aborted) {
+        try {
+            if (options.import) {
+                await importer.import({
+                    ...options, publish: true, batchRunId: undefined,
+                    limits: { ...options.limits, batchSize: 1 },
+                });
+            }
+            else {
+                // Do not fingerprint or persist snapshots: export adapters may rewrite
+                // a JSON document as it grows. Each adapter owns its resume semantics.
+                for await (const record of options.adapter.stream(options.selectedSource, checkpoint ? { value: checkpoint.cursor } : undefined)) {
+                    if (options.signal?.aborted)
+                        return;
+                    const serialized = JSON.stringify(record);
+                    const limits = { ...DEFAULT_IMPORT_BYTE_LIMITS, ...options.limits };
+                    assertImportByteLimit('maxRecordBytes', limits, Buffer.byteLength(serialized));
+                    const count = (checkpoint?.recordsRead ?? 0) + 1;
+                    assertSessionResourceLimit('maxRecords', options.limits?.maxRecords ?? 1_000_000, count);
+                    const digest = sha256(serialized);
+                    const runId = sha256([options.source.sourceId, options.adapter.adapterVersion,
+                        count - 1, count, digest].join('\0'));
+                    const { events } = normalizeSessionBatch(options, [record], [digest], runId);
+                    checkpoint = { ...checkpoint, cursor: record.sourceCursor ?? String(count),
+                        recordsRead: count, bytesRead: (checkpoint?.bytesRead ?? 0) + Buffer.byteLength(serialized) };
+                    for (const event of events) {
+                        if (event.sessionId === options.sessionId)
+                            options.onEvent(event);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                return;
+            // Some native JSONL adapters report an in-progress final line explicitly.
+            if (!(options.follow && error instanceof SessionContractError
+                && error.code === 'TRUNCATED_SOURCE'))
+                throw error;
+        }
+        await options.onPoll?.();
+        if (!options.follow || options.signal?.aborted)
+            return;
+        try {
+            await setTimeout(pollMs, undefined, { signal: options.signal });
+        }
+        catch (error) {
+            if (!options.signal?.aborted)
+                throw error;
+        }
+    }
+}
+//# sourceMappingURL=tail.js.map

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

@@ -4,6 +4,8 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { inspectMuseNativeWorkspace } from './adapters/muse.js';
 import { readOmpSessionHeader } from './adapters/omp.js';
 import { grokbotConversationIdFromLocator } from './adapters/grokbot-locator.js';
+import { GROK_BUILD_ACTIVE_FRESHNESS_MS, grokBuildLiveState, grokBuildSourceWorkspaceMatch, readGrokBuildActiveRegistry, } from './adapters/grok-build-native.js';
+import { hermesSnapshotStagingDir } from './adapters/hermes-state-db.js';
 import { resolveOmpPaths } from '../providers/omp-paths.mjs';
 import { readAiwgConfig } from '../config/aiwg-config.js';
 import { SessionCoveragePreflightSchema, SessionContractError, sha256, } from './contracts.js';
@@ -15,7 +17,7 @@ import { matchSessionWorkspace } from './workspace-matching.js';
 import { matchImportExclusion, nativeSessionIdFromLocator, resolveImportExclusions } from './import-exclusions.js';
 export const DISCOVERY_MANIFEST_VERSION = '1.0.0';
 const MANUAL_EXPORT_PROVIDERS = new Set([
-    'copilot', 'hermes', 'opencode', 'openclaw', 'openhuman', 'grok-build',
+    'copilot', 'opencode', 'openclaw', 'openhuman',
     'warp', 'devin-desktop', 'generic',
 ]);
 export async function discoverWorkspaceHistories(options) {
@@ -31,6 +33,8 @@ export async function discoverWorkspaceHistories(options) {
         ...(options.museRoot ? ['muse'] : []),
         ...(options.dshRoot ? ['deepseek-harness'] : []),
         ...(options.grokbotRoot ? ['grokbot'] : []),
+        ...(options.grokRoot ? ['grok-build'] : []),
+        ...(options.hermesRoot ? ['hermes'] : []),
     ];
     const savedRoots = options.authorizedRoots ?? options.refreshFrom?.authorizedRoots;
     const authorizedProviders = options.refreshFrom
@@ -68,6 +72,15 @@ export async function discoverWorkspaceHistories(options) {
         // no-filtering behavior already used for `pi`/`deepseek-harness`).
         { provider: 'grokbot', roots: options.grokbotRoot
                 ? [resolve(options.grokbotRoot)] : [] },
+        // Grok Build authorizes the sessions directory itself, never Grok home:
+        // `<root>/<url-encoded cwd>/<id>/chat_history.jsonl`. No fallback through
+        // $HOME, GROK_HOME, or --provider-home grants access.
+        { provider: 'grok-build', roots: options.grokRoot
+                ? [resolve(options.grokRoot)] : [] },
+        // Hermes authorizes `<root>/state.db` for a read-only backup snapshot.
+        // Staging joins the scope below; nothing else under the root is read.
+        { provider: 'hermes', roots: options.hermesRoot
+                ? [resolve(options.hermesRoot)] : [] },
         {
             provider: 'claude',
             // Same scope rule as codex: configured providers keep their root grant
@@ -155,14 +168,17 @@ export async function discoverWorkspaceHistories(options) {
             }
         }
         if (availableRoots.length === 0) {
-            const codexNeedsAuthorization = (entry.provider === 'codex' || entry.provider === 'omp'
+            const needsExplicitRoot = (entry.provider === 'codex' || entry.provider === 'omp'
                 || entry.provider === 'deepseek-harness' || entry.provider === 'muse'
-                || entry.provider === 'grokbot')
+                || entry.provider === 'grokbot' || entry.provider === 'grok-build'
+                || entry.provider === 'hermes')
                 && entry.roots.length === 0;
-            reports.set(entry.provider, providerReport(entry.provider, codexNeedsAuthorization ? 'export-required' : 'unavailable', codexNeedsAuthorization ? 'manual-export' : 'discoverable', [], codexNeedsAuthorization
+            const expectedFlag = entry.provider === 'deepseek-harness' ? 'dsh' : entry.provider;
+            const rootKind = entry.provider === 'hermes' ? 'Hermes home (state.db is snapshotted read-only)' : 'sessions root';
+            reports.set(entry.provider, providerReport(entry.provider, needsExplicitRoot ? 'export-required' : 'unavailable', needsExplicitRoot ? 'manual-export' : 'discoverable', [], needsExplicitRoot
                 ? 'SHARED_ROOT_AUTHORIZATION_REQUIRED'
-                : 'PROVIDER_ROOT_UNAVAILABLE', codexNeedsAuthorization
-                ? `Pass --${entry.provider === 'deepseek-harness' ? 'dsh' : entry.provider}-root with an explicitly authorized sessions root.`
+                : 'PROVIDER_ROOT_UNAVAILABLE', needsExplicitRoot
+                ? `Pass --${expectedFlag}-root with an explicitly authorized ${rootKind}.`
                 : `No authorized ${entry.provider} workspace history root was found.`));
             if (entry.provider === 'codex')
                 reports.get(entry.provider).rootCounts = [...rootCounts.values()];
@@ -173,13 +189,48 @@ export async function discoverWorkspaceHistories(options) {
             workspaceId,
             allowedRoots: availableRoots,
         };
+        if (entry.provider === 'hermes') {
+            // The consistent snapshot is staged under owned workspace staging (the
+            // provider home stays read-only); staged locators need scope cover, and
+            // refresh must retain both the origin grant and the staging grant.
+            const staging = hermesSnapshotStagingDir(workspacePath);
+            if (!scope.allowedRoots.includes(staging))
+                scope.allowedRoots.push(staging);
+            authorizedRoots[entry.provider] = [...new Set([...availableRoots, staging])];
+            if (!rootCounts.has(staging)) {
+                rootCounts.set(staging, {
+                    root: redactSourceLocator(staging), rootId: sha256(staging),
+                    status: 'checked', sourceCount: 0, duplicateCount: 0,
+                });
+            }
+        }
         const providerSources = [];
         let matchedBySubfolder = 0;
         let matchedByWorktree = 0;
         const museSourceInspections = [];
+        // Grok Build live detection reads exactly one explicitly authorized file
+        // (never the sessions root's parent implicitly); absence means unknown.
+        let grokActiveRegistry = null;
+        let grokActiveRegistryLoaded = false;
+        const grokActiveEvidence = async () => {
+            if (grokActiveRegistryLoaded || entry.provider !== 'grok-build' || !options.grokActiveSessions)
+                return grokActiveRegistry;
+            grokActiveRegistryLoaded = true;
+            try {
+                grokActiveRegistry = await readGrokBuildActiveRegistry(resolve(options.grokActiveSessions), [resolve(options.grokActiveSessions)].map((file) => dirname(file)));
+            }
+            catch {
+                grokActiveRegistry = null;
+            }
+            return grokActiveRegistry;
+        };
         for await (const descriptor of adapter.discover(scope)) {
             const known = options.knownSources?.find(source => source.provider === descriptor.provider && source.locator === descriptor.locator);
-            const nativeSessionId = known?.nativeSessionId ?? descriptor.nativeSessionId ?? nativeSessionIdFromLocator(descriptor);
+            // A Hermes projection holds many sessions, so its locator basename is
+            // never a session identity.
+            const nativeSessionId = entry.provider === 'hermes'
+                ? (known?.nativeSessionId ?? descriptor.nativeSessionId)
+                : (known?.nativeSessionId ?? descriptor.nativeSessionId ?? nativeSessionIdFromLocator(descriptor));
             const exclusion = matchImportExclusion({ ...descriptor, nativeSessionId }, exclusions);
             if (exclusion) {
                 const locator = resolve(descriptor.locator);
@@ -224,6 +275,13 @@ export async function discoverWorkspaceHistories(options) {
                 if (!workspaceMatch)
                     continue;
             }
+            if (entry.provider === 'grok-build') {
+                // The url-encoded cwd directory is the only workspace evidence; an
+                // unresolvable or conflicting value never attaches to the caller.
+                workspaceMatch = await grokBuildSourceWorkspaceMatch(locator, workspacePath);
+                if (!workspaceMatch)
+                    continue;
+            }
             const ompHeader = entry.provider === 'omp' ? await readOmpSessionHeader({ ...descriptor, sourceId: 'discovery', authorizedScope: scope }) : undefined;
             if (ompHeader) {
                 workspaceMatch = await matchSessionWorkspace(ompHeader.cwd, workspacePath);
@@ -262,6 +320,24 @@ export async function discoverWorkspaceHistories(options) {
             rootCount.sourceCount += 1;
             const source = sourceFromDescriptor(descriptor, locator, authorizedRoot, details, fingerprint.digest);
             source.nativeSessionId = rolloutId ?? ompHeader?.id ?? nativeSessionId;
+            if (entry.provider === 'hermes') {
+                // A state.db projection holds many sessions; the locator basename is
+                // not a session identity.
+                delete source.nativeSessionId;
+            }
+            if (entry.provider === 'grok-build' && source.nativeSessionId) {
+                // Provider-reported activity only; histories stay usable without it.
+                const observedAt = options.createdAt ?? new Date().toISOString();
+                const registry = await grokActiveEvidence();
+                const evidence = grokBuildLiveState(registry, source.nativeSessionId);
+                source.liveEvidence = {
+                    ...evidence,
+                    observedAt,
+                    expiresAt: evidence.state === 'active'
+                        ? new Date(Date.parse(observedAt) + GROK_BUILD_ACTIVE_FRESHNESS_MS).toISOString()
+                        : null,
+                };
+            }
             if (ompHeader)
                 source.sourceId = sha256(['omp-native-source-v1', workspaceId, ompHeader.id].join('\0'));
             if (entry.provider === 'grokbot') {
@@ -269,10 +345,13 @@ export async function discoverWorkspaceHistories(options) {
                 // 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.
+                // override above. Unlike OMP, the key carries no workspaceId: Grok
+                // Bot conversations are account-scoped (#3232), so the same replica
+                // must resolve to one host-catalog source no matter which workspace
+                // authorizes it; workspace catalogs keep a reference instead of a copy.
                 const conversationId = grokbotConversationIdFromLocator(locator);
                 if (conversationId) {
-                    source.sourceId = sha256(['grokbot-native-source-v1', workspaceId, conversationId].join('\0'));
+                    source.sourceId = sha256(['grokbot-native-source-v1', conversationId].join('\0'));
                 }
             }
             providerSources.push(source);

package/dist/src/skills/agent-skill-sidecar.js

@@ -0,0 +1,28 @@
+// Preserve non-portable skill metadata across the portable boundary.
+import { AGENT_SKILLS_SIDECAR_SCHEMA } from './agent-skills.js';
+export function createAgentSkillSidecar(document, provenance, validationProfile, trust) {
+    return {
+        $schema: AGENT_SKILLS_SIDECAR_SCHEMA,
+        schemaVersion: 1,
+        aiwg: structuredClone(document.aiwg),
+        ...(document.providers ? { providers: structuredClone(document.providers) } : {}),
+        provenance: structuredClone(provenance),
+        validationProfile,
+        trust: { ...trust },
+    };
+}
+/**
+ * Restore AIWG metadata omitted at a strict portability boundary. Portable
+ * content remains authoritative for standard fields, body, and resources.
+ */
+export function restoreAgentSkillFromSidecar(standard, body, resources, sidecar) {
+    return {
+        standard: structuredClone(standard),
+        body,
+        resources: resources.map((resource) => ({ ...resource })),
+        aiwg: structuredClone(sidecar.aiwg),
+        ...(sidecar.providers ? { providers: structuredClone(sidecar.providers) } : {}),
+        unknownFields: [],
+    };
+}
+//# sourceMappingURL=agent-skill-sidecar.js.map

package/dist/src/skills/agent-skills.js

@@ -6,6 +6,9 @@
  *
  * @implements #1875
  */
+import { CLAUDE_SKILL_FIELDS } from './provider-extensions.js';
+export { CLAUDE_SKILL_FIELDS } from './provider-extensions.js';
+export { createAgentSkillSidecar, restoreAgentSkillFromSidecar } from './agent-skill-sidecar.js';
 export const AGENT_SKILLS_BASELINE = {
     repository: 'agentskills/agentskills',
     revision: '38a2ff82958afee88dadf4831509e6f7e9d8ef4e',
@@ -174,6 +177,7 @@ export function validateCompatibleAgentSkillMetadata(frontmatter, directoryName,
     const recognizedFields = new Set([
         ...STANDARD_SKILL_FIELDS,
         ...AIWG_SKILL_CONTROL_FIELDS,
+        ...CLAUDE_SKILL_FIELDS,
     ]);
     for (const key of Object.keys(frontmatter).sort()) {
         if (!recognizedFields.has(key)) {
@@ -223,27 +227,4 @@ export function equivalentPortableAllowedTools(aiwg) {
     }
     return aiwg.allowedTools.join(' ');
 }
-export function createAgentSkillSidecar(document, provenance, validationProfile, trust) {
-    return {
-        $schema: AGENT_SKILLS_SIDECAR_SCHEMA,
-        schemaVersion: 1,
-        aiwg: structuredClone(document.aiwg),
-        provenance: structuredClone(provenance),
-        validationProfile,
-        trust: { ...trust },
-    };
-}
-/**
- * Restore AIWG metadata omitted at a strict portability boundary. Portable
- * content remains authoritative for standard fields, body, and resources.
- */
-export function restoreAgentSkillFromSidecar(standard, body, resources, sidecar) {
-    return {
-        standard: structuredClone(standard),
-        body,
-        resources: resources.map((resource) => ({ ...resource })),
-        aiwg: structuredClone(sidecar.aiwg),
-        unknownFields: [],
-    };
-}
 //# sourceMappingURL=agent-skills.js.map