@aiwg/cli 2026.10.10 → 2026.10.12

package/dist/src/sessions/adapters/grok-build-native.js

@@ -0,0 +1,269 @@
+// Native Grok Build session-store reader (synthetic schema v1; real stores never inspected).
+import { opendir, readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { z } from 'zod';
+import { integer, number } from '../../schema/zod-validation.mjs';
+import { schemaIssueDetail, schemaRejectionDetail, SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
+import { matchSessionWorkspace } from '../workspace-matching.js';
+import { authorizeSourceFile } from '../policy.js';
+import { streamBoundedJsonLines, } from '../readers.js';
+export const GROK_BUILD_NATIVE_SCHEMA_VERSION = '1.0.0';
+export const GROK_BUILD_NATIVE_SCHEMA_MAJOR = 1;
+export const GROK_BUILD_NATIVE_LOCATOR_CLASS = 'grok-build-native-chat-history';
+export const GROK_BUILD_NATIVE_SESSION_FILENAME = 'chat_history.jsonl';
+export const GROK_BUILD_ACTIVE_SESSIONS_SCHEMA_VERSION = 1;
+export const GROK_BUILD_ACTIVE_FRESHNESS_MS = 120_000;
+export const GROK_BUILD_NATIVE_DISCOVERY_MAX_FILES = 10_000;
+const ACTIVE_SESSIONS_MAX_BYTES = 1024 * 1024;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+// Synthetic native record shape (v1): one JSON object per line. Real
+// chat_history.jsonl schemas are unqualified (real stores are never read),
+// so any record outside this shape fails closed with SCHEMA_DRIFT.
+const NativeRecordSchema = z.looseObject({
+    schemaVersion: z.union([z.string(), z.number()]),
+    sessionId: z.string().regex(UUID),
+    seq: integer().nonnegative(),
+    role: z.enum(['user', 'assistant', 'tool']),
+    content: z.string(),
+    timestamp: number().optional(),
+    toolName: z.string().min(1).optional(),
+    toolCallId: z.string().optional(),
+    id: z.string().min(1).optional(),
+});
+const ActiveSessionsSchema = z.looseObject({
+    schemaVersion: z.union([z.string(), z.number()]),
+    sessions: z.array(z.looseObject({
+        sessionId: z.string().regex(UUID),
+        cwd: z.string().optional(),
+        lastHeartbeatAt: number().optional(),
+    })),
+});
+/** Decode a url-encoded cwd directory name exactly once; null means skip. */
+export function decodeGrokBuildWorkspaceDir(name) {
+    if (!name || name.includes('/') || name.includes('\\'))
+        return null;
+    let decoded;
+    try {
+        decoded = decodeURIComponent(name);
+    }
+    catch {
+        return null;
+    }
+    if (!decoded.startsWith('/') || decoded.includes('\0'))
+        return null;
+    return decoded;
+}
+export function grokBuildNativeSessionId(locator) {
+    const sessionId = dirname(locator).split('/').pop()?.split('\\').pop() ?? '';
+    return UUID.test(sessionId) ? sessionId.toLowerCase() : null;
+}
+/** Enumerate documented `<root>/<url-encoded cwd>/<id>/chat_history.jsonl` paths. */
+export async function* discoverGrokBuildNativeChatHistories(root, maxFiles = GROK_BUILD_NATIVE_DISCOVERY_MAX_FILES) {
+    const resolved = resolve(root);
+    let workspaces;
+    try {
+        workspaces = await opendir(resolved);
+    }
+    catch {
+        return;
+    }
+    let count = 0;
+    for await (const workspace of workspaces) {
+        if (!workspace.isDirectory())
+            continue;
+        const decoded = decodeGrokBuildWorkspaceDir(workspace.name);
+        if (!decoded)
+            continue;
+        const workspacePath = resolve(resolved, workspace.name);
+        if (workspacePath !== resolved && !workspacePath.startsWith(`${resolved}/`))
+            continue;
+        let sessions;
+        try {
+            sessions = await opendir(workspacePath);
+        }
+        catch {
+            continue;
+        }
+        for await (const session of sessions) {
+            if (!session.isDirectory() || !UUID.test(session.name))
+                continue;
+            const sessionPath = resolve(workspacePath, session.name);
+            if (!sessionPath.startsWith(`${workspacePath}/`))
+                continue;
+            let entries;
+            try {
+                entries = await opendir(sessionPath);
+            }
+            catch {
+                continue;
+            }
+            for await (const entry of entries) {
+                if (!entry.isFile() || entry.name !== GROK_BUILD_NATIVE_SESSION_FILENAME)
+                    continue;
+                if (++count > maxFiles) {
+                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Grok Build native session discovery exceeded the authorized file limit', { limit: 'maxFiles', configured: maxFiles, observed: count });
+                }
+                yield {
+                    provider: 'grok-build',
+                    locator: resolve(sessionPath, entry.name),
+                    locatorClass: GROK_BUILD_NATIVE_LOCATOR_CLASS,
+                    nativeSessionId: session.name.toLowerCase(),
+                };
+            }
+        }
+    }
+}
+/** Match a native locator against the authorized workspace via its cwd directory. */
+export async function grokBuildSourceWorkspaceMatch(locator, workspacePath) {
+    const segments = locator.replace(/\\/g, '/').split('/');
+    const encoded = segments.at(-3);
+    if (!encoded)
+        return null;
+    const decoded = decodeGrokBuildWorkspaceDir(encoded);
+    if (!decoded)
+        return null;
+    return matchSessionWorkspace(decoded, workspacePath);
+}
+export async function readGrokBuildNativeChatHistory(source, limits) {
+    const sessionId = grokBuildNativeSessionId(source.locator);
+    if (source.locatorClass !== GROK_BUILD_NATIVE_LOCATOR_CLASS || !sessionId) {
+        throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Grok Build native source must be an explicitly authorized chat_history.jsonl path');
+    }
+    await authorizeSourceFile({
+        selectedPath: source.locator,
+        allowedRoots: source.authorizedScope.allowedRoots,
+    });
+    const input = await streamBoundedJsonLines({
+        selectedPath: source.locator,
+        allowedRoots: source.authorizedScope.allowedRoots,
+    }, { consistency: 'provisional', limits });
+    const records = [];
+    let lastSeq = -1;
+    for await (const line of input) {
+        const parsed = NativeRecordSchema.safeParse(line.value);
+        if (!parsed.success) {
+            throw new SessionContractError('SCHEMA_DRIFT', 'unrecognized Grok Build native chat_history.jsonl record', schemaRejectionDetail(parsed.error));
+        }
+        assertSupportedSchemaMajor(declaredSchema(parsed.data.schemaVersion), GROK_BUILD_NATIVE_SCHEMA_MAJOR);
+        if (parsed.data.sessionId.toLowerCase() !== sessionId) {
+            throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build native record session does not match its session directory', schemaIssueDetail('sessionId'));
+        }
+        if (parsed.data.seq <= lastSeq) {
+            throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build native chat history sequence is not strictly increasing', schemaIssueDetail('seq'));
+        }
+        lastSeq = parsed.data.seq;
+        if (parsed.data.role === 'tool' && !parsed.data.toolName) {
+            throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build native tool record is missing its tool name', schemaIssueDetail('toolName'));
+        }
+        records.push({ record: parsed.data, line });
+    }
+    if (records.length === 0) {
+        throw new SessionContractError('MALFORMED_SOURCE', 'Grok Build native chat history is empty', schemaIssueDetail('<root>'));
+    }
+    return { records, incompleteTail: input.incompleteTail };
+}
+export function toGrokBuildNativeRecord(sessionId, entry) {
+    const { record, line } = entry;
+    const occurredAt = timestamp(record.timestamp);
+    const nativeEventId = record.id ?? `${sessionId}:${record.seq}`;
+    const common = {
+        lifecycle: 'unknown-at-import',
+        provenance: {
+            product: 'grok-build',
+            acquisition: GROK_BUILD_NATIVE_LOCATOR_CLASS,
+            sourceSchema: GROK_BUILD_NATIVE_SCHEMA_VERSION,
+            nativeStoreInspected: true,
+        },
+        identity: { nativeSessionIdKnown: true, nativeEventIdKnown: true },
+    };
+    if (record.role === 'tool') {
+        return {
+            nativeSessionId: sessionId,
+            nativeEventId,
+            sequence: line.sequence * 1_000,
+            kind: 'tool-call',
+            role: 'tool',
+            toolName: record.toolName,
+            toolCallId: record.toolCallId,
+            occurredAt,
+            text: record.content,
+            rawReference: { locatorClass: GROK_BUILD_NATIVE_LOCATOR_CLASS, sequence: line.sequence },
+            extensions: common,
+        };
+    }
+    return {
+        nativeSessionId: sessionId,
+        nativeEventId,
+        sequence: line.sequence * 1_000,
+        kind: 'message',
+        role: record.role,
+        occurredAt,
+        text: record.content,
+        rawReference: { locatorClass: GROK_BUILD_NATIVE_LOCATOR_CLASS, sequence: line.sequence },
+        extensions: common,
+    };
+}
+/** Read and validate active_sessions.json (read-only, bounded); throws on misuse. */
+export async function readGrokBuildActiveRegistry(selectedPath, allowedRoots) {
+    const authorized = await authorizeSourceFile({
+        selectedPath, allowedRoots, maxBytes: ACTIVE_SESSIONS_MAX_BYTES,
+    });
+    const raw = await readFile(authorized.canonicalPath, 'utf8');
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build active_sessions.json is not valid JSON', schemaIssueDetail('<root>'));
+    }
+    const parsed = ActiveSessionsSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new SessionContractError('SCHEMA_DRIFT', 'unrecognized Grok Build active_sessions.json shape', schemaRejectionDetail(parsed.error));
+    }
+    assertSupportedSchemaMajor(declaredSchema(parsed.data.schemaVersion), GROK_BUILD_ACTIVE_SESSIONS_SCHEMA_VERSION);
+    return parsed.data;
+}
+/** Provider-reported activity only; never a verified running process. */
+export function grokBuildLiveState(registry, sessionId, nowMs = Date.now()) {
+    if (!registry)
+        return { state: 'unknown', basis: 'none', reasonCode: 'NO_ACTIVE_SESSIONS_GRANT' };
+    const entry = registry.sessions.find((item) => item.sessionId.toLowerCase() === sessionId.toLowerCase());
+    if (!entry)
+        return { state: 'unknown', basis: 'grok-active-sessions', reasonCode: 'SESSION_NOT_LISTED' };
+    if (entry.lastHeartbeatAt === undefined) {
+        return { state: 'unknown', basis: 'grok-active-sessions', reasonCode: 'NO_HEARTBEAT' };
+    }
+    const heartbeatMs = entry.lastHeartbeatAt < 10_000_000_000
+        ? entry.lastHeartbeatAt * 1_000
+        : entry.lastHeartbeatAt;
+    if (!Number.isFinite(heartbeatMs)) {
+        return { state: 'unknown', basis: 'grok-active-sessions', reasonCode: 'INVALID_HEARTBEAT' };
+    }
+    if (heartbeatMs > nowMs) {
+        return { state: 'unknown', basis: 'grok-active-sessions', reasonCode: 'FUTURE_HEARTBEAT' };
+    }
+    if (nowMs - heartbeatMs > GROK_BUILD_ACTIVE_FRESHNESS_MS) {
+        return { state: 'unknown', basis: 'grok-active-sessions', reasonCode: 'STALE_HEARTBEAT' };
+    }
+    return { state: 'active', basis: 'grok-active-sessions', reasonCode: 'FRESH_HEARTBEAT' };
+}
+export function parseGrokBuildNativeCursor(value) {
+    if (!value)
+        return 0;
+    if (!/^\d+$/.test(value)) {
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Grok Build native cursor', schemaIssueDetail('cursor'));
+    }
+    return Number(value);
+}
+function declaredSchema(value) {
+    if (typeof value === 'number')
+        return `${value}.0.0`;
+    return /^\d+$/.test(String(value)) ? `${value}.0.0` : String(value);
+}
+function timestamp(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const date = new Date(value < 10_000_000_000 ? value * 1_000 : value);
+    return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
+}
+//# sourceMappingURL=grok-build-native.js.map

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

@@ -1,31 +1,49 @@
 import { basename, extname } from 'node:path';
 import { SessionContractError, schemaIssueDetail, } from '../contracts.js';
 import { readBoundedText } from '../readers.js';
+import { discoverGrokBuildNativeChatHistories, GROK_BUILD_NATIVE_DISCOVERY_MAX_FILES, GROK_BUILD_NATIVE_LOCATOR_CLASS, GROK_BUILD_NATIVE_SCHEMA_VERSION, grokBuildNativeSessionId, parseGrokBuildNativeCursor, readGrokBuildNativeChatHistory, toGrokBuildNativeRecord, } from './grok-build-native.js';
 export const GROK_BUILD_ADAPTER_VERSION = '1.0.0';
 export const GROK_BUILD_CLI_EXPORT_SCHEMA_VERSION = '1.0.0';
 export const GROK_BUILD_CLI_EXPORT_LOCATOR_CLASS = 'grok-build-cli-markdown-export';
 /**
- * Imports the documented `grok export <session-id> <file>` surface.
+ * Imports the documented `grok export <session-id> <file>` surface plus the
+ * native `chat_history.jsonl` store under an explicitly authorized
+ * sessions root (`--grok-root`).
  *
- * The public export contract is intentionally lossy. Direct reads from
- * $GROK_HOME/sessions are prohibited until a released native schema has been
- * qualified independently.
+ * The public export contract is intentionally lossy. Native reads use the
+ * synthetic v1 schema in grok-build-native.ts (real stores were never
+ * inspected); anything outside it fails closed. AIWG never runs
+ * `grok export` itself: export remains an operator-selected fallback.
  */
 export class GrokBuildSessionAdapter {
     limits;
+    maxFiles;
     provider = 'grok-build';
     adapterVersion = GROK_BUILD_ADAPTER_VERSION;
     disposition = 'implemented';
-    supportedOperations = ['inspect', 'stream'];
-    acquisitionModes = ['manual-export'];
-    constructor(limits) {
+    supportedOperations = ['discover', 'inspect', 'stream'];
+    acquisitionModes = ['manual-export', 'jsonl'];
+    constructor(limits, maxFiles = GROK_BUILD_NATIVE_DISCOVERY_MAX_FILES) {
         this.limits = limits;
+        this.maxFiles = maxFiles;
     }
-    async *discover(_scope) {
-        throw new SessionContractError('UNSUPPORTED_OPERATION', 'Grok Build native-store discovery is disabled. Run `grok sessions list`, then '
-            + '`grok export <session-id> <session-id>.md` and import that authorized export.');
+    async *discover(scope) {
+        if (scope.allowedRoots.length === 0) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Grok Build native discovery requires an explicitly authorized sessions root; pass --grok-root.');
+        }
+        for (const root of [...scope.allowedRoots].sort()) {
+            yield* discoverGrokBuildNativeChatHistories(root, this.maxFiles);
+        }
     }
     async inspect(source) {
+        if (source.locatorClass === GROK_BUILD_NATIVE_LOCATOR_CLASS) {
+            const native = await readGrokBuildNativeChatHistory(source, this.limits);
+            return {
+                sourceSchemaVersion: GROK_BUILD_NATIVE_SCHEMA_VERSION,
+                consistency: native.incompleteTail ? 'provisional' : 'complete',
+                operationalState: 'available',
+            };
+        }
         await this.readSource(source);
         return {
             sourceSchemaVersion: GROK_BUILD_CLI_EXPORT_SCHEMA_VERSION,
@@ -34,13 +52,33 @@ export class GrokBuildSessionAdapter {
         };
     }
     async *stream(source, cursor) {
+        if (source.locatorClass === GROK_BUILD_NATIVE_LOCATOR_CLASS) {
+            const sessionId = grokBuildNativeSessionId(source.locator);
+            if (!sessionId) {
+                throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Grok Build native source must be an explicitly authorized chat_history.jsonl path');
+            }
+            const native = await readGrokBuildNativeChatHistory(source, this.limits);
+            const start = parseGrokBuildNativeCursor(cursor?.value);
+            let outputIndex = 0;
+            for (const entry of native.records) {
+                const position = outputIndex;
+                outputIndex += 1;
+                if (position < start)
+                    continue;
+                const record = toGrokBuildNativeRecord(sessionId, entry);
+                record.sourceCursor = String(outputIndex);
+                yield record;
+            }
+            return;
+        }
         const parsed = await this.readSource(source);
         const start = parseCursor(cursor?.value);
+        let outputIndex = 0;
         for (const [sequence, block] of parsed.blocks.entries()) {
-            if (sequence < start)
-                continue;
             if (block.heading === 'Tools') {
-                for (const tool of parseTools(block.text, sequence))
+                for (const tool of parseTools(block.text, sequence)) {
+                    if (outputIndex++ < start)
+                        continue;
                     yield {
                         nativeSessionId: parsed.sessionId,
                         nativeEventId: undefined,
@@ -53,8 +91,11 @@ export class GrokBuildSessionAdapter {
                         rawReference: { locatorClass: source.locatorClass, sequence },
                         extensions: provenance(source, parsed.sessionId, 'Tools'),
                     };
+                }
                 continue;
             }
+            if (outputIndex++ < start)
+                continue;
             yield {
                 nativeSessionId: parsed.sessionId,
                 nativeEventId: undefined,
@@ -70,8 +111,9 @@ export class GrokBuildSessionAdapter {
     }
     async readSource(source) {
         if (source.locatorClass !== GROK_BUILD_CLI_EXPORT_LOCATOR_CLASS) {
-            throw new SessionContractError('UNSUPPORTED_OPERATION', 'Grok Build accepts only a documented `grok export` Markdown transcript; '
-                + 'native session files, Grok Bot exports, and Cursor stores are not supported.');
+            throw new SessionContractError('UNSUPPORTED_OPERATION', 'Grok Build accepts only a documented `grok export` Markdown transcript or an '
+                + `explicitly authorized \`${GROK_BUILD_NATIVE_LOCATOR_CLASS}\` source; `
+                + 'Grok Bot exports and Cursor stores are not supported.');
         }
         const filename = basename(source.locator, extname(source.locator));
         if (extname(source.locator).toLowerCase() !== '.md' || !UUID.test(filename)) {

package/dist/src/sessions/adapters/grokbot.js

@@ -152,6 +152,13 @@ export class GrokbotSessionAdapter {
      * rename-swap), not appended to. See the class-level doc comment.
      */
     sourceContinuity = 'snapshot';
+    /**
+     * Account scope (#3232): conversations carry no workspace identity, so
+     * every workspace authorizing the same `--grokbot-root` would otherwise
+     * import the same conversations. The importer routes account-scoped
+     * sources to the host catalog once; workspace catalogs keep a reference.
+     */
+    scopeClass = 'account';
     interchange;
     constructor(limits, maxFiles = 10_000) {
         this.limits = limits;

package/dist/src/sessions/adapters/hermes-state-db.js

@@ -0,0 +1,252 @@
+// Hermes state.db snapshot reader: read-only backup, schema-gated projection (synthetic physical schema v1).
+import { chmod, lstat, mkdir, realpath, rm, stat, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { sha256, SessionContractError } from '../contracts.js';
+import { requireFeaturePackage } from '../../features/runtime.js';
+import { matchSessionWorkspace } from '../workspace-matching.js';
+export const HERMES_STATE_DB_FILENAME = 'state.db';
+export const HERMES_NATIVE_PHYSICAL_SCHEMA = 'hermes-synthetic-v1';
+export const HERMES_SNAPSHOT_LOCATOR_CLASS = 'hermes-consistent-snapshot-jsonl';
+const STAGING_DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+const MAX_SOURCE_BYTES = 1024 * 1024 * 1024;
+const MAX_SESSIONS = 1_000_000;
+/** Owned staging beneath the workspace session store; never inside the provider tree. */
+export function hermesSnapshotStagingDir(workspacePath) {
+    return join(resolve(workspacePath), '.aiwg', 'sessions', 'staging', 'hermes');
+}
+export function hermesSnapshotProjectionPath(stagingDir, canonicalRoot) {
+    return join(stagingDir, `state-${sha256(canonicalRoot).slice(7, 23)}.snapshot.jsonl`);
+}
+function loadSqlite() {
+    try {
+        return requireFeaturePackage('better-sqlite3');
+    }
+    catch {
+        throw new SessionContractError('UNSUPPORTED_OPERATION', 'Hermes native discovery requires the optional sqlite backend; '
+            + 'run `aiwg features install sqlite`, then rediscover with --hermes-root.');
+    }
+}
+function sqliteUnavailable(error, what) {
+    if (error instanceof SessionContractError)
+        throw error;
+    const code = typeof error.code === 'string'
+        ? error.code
+        : 'SQLITE_ERROR';
+    return new SessionContractError('UNSUPPORTED_OPERATION', `Hermes snapshot is unavailable while ${what} (sqlite ${code}); `
+        + 'start Hermes so a consistent backup can be taken without writing to its directory, '
+        + 'or import a `hermes sessions export` file instead.');
+}
+/**
+ * WAL reads need the provider's shared-memory index, and any first read
+ * would create it as a provider-tree write. A WAL database without its
+ * sidecars present therefore refuses BEFORE any SQLite contact — fail closed
+ * rather than writing sidecars or reopening writable. (Hermes runs WAL mode;
+ * the export fallback covers a stopped provider.) When the index pre-exists,
+ * the read-only open reuses it without creating files; its volatile
+ * read-marks may advance through normal WAL read concurrency — the same as
+ * any Hermes reader — but tree membership, sizes, and database content never
+ * change.
+ */
+async function assertReadableWithoutSidecarWrites(live) {
+    const shm = await lstat(`${live}-shm`).then((item) => item.isFile()).catch(() => false);
+    if (!shm) {
+        throw new SessionContractError('UNSUPPORTED_OPERATION', 'Hermes snapshot needs the provider WAL sidecars (state.db-shm); '
+            + 'start Hermes so a consistent backup can be taken without writing to its directory, '
+            + 'or import a `hermes sessions export` file instead.');
+    }
+}
+async function authorizeLiveDb(liveDbPath, allowedRoots) {
+    if (allowedRoots.length === 0) {
+        throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Hermes discovery requires --hermes-root.');
+    }
+    const selected = resolve(liveDbPath);
+    const link = await lstat(selected).catch(() => null);
+    if (!link) {
+        throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Hermes state.db is not available under --hermes-root.');
+    }
+    if (link.isSymbolicLink()) {
+        throw new SessionContractError('SOURCE_SYMLINK', 'Hermes state.db cannot be a symlink.');
+    }
+    const canonical = await realpath(selected).catch(() => null);
+    if (!canonical) {
+        throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Hermes state.db is not available under --hermes-root.');
+    }
+    const canonicalRoots = await Promise.all(allowedRoots.map(async (root) => resolve(root)));
+    const inside = canonicalRoots.some((root) => canonical === root || canonical.startsWith(`${root}/`));
+    if (!inside) {
+        throw new SessionContractError('SOURCE_OUTSIDE_ALLOWED_ROOT', 'Hermes state.db escapes the authorized roots.');
+    }
+    const details = await stat(canonical);
+    if (!details.isFile()) {
+        throw new SessionContractError('SOURCE_NOT_REGULAR_FILE', 'Hermes state.db must be a regular file.');
+    }
+    if (details.size > MAX_SOURCE_BYTES) {
+        throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Hermes state.db exceeds the snapshot byte limit', {
+            limit: 'maxBytes', configured: MAX_SOURCE_BYTES, observed: details.size,
+        });
+    }
+    return canonical;
+}
+const REQUIRED_SESSION_COLUMNS = new Set([
+    'id', 'source', 'user_id', 'model', 'model_config', 'parent_session_id',
+    'compressed_from_session_id', 'started_at', 'ended_at', 'end_reason',
+    'archived', 'inactive', 'cwd', 'git_branch', 'routing_key', 'input_tokens',
+    'output_tokens', 'cache_read_tokens', 'cache_write_tokens', 'reasoning_tokens',
+    'estimated_cost_usd', 'actual_cost_usd', 'billing_provider',
+    'export_deleted_at', 'provider_deleted_at',
+]);
+const REQUIRED_MESSAGE_COLUMNS = new Set([
+    'session_id', 'seq', 'id', 'role', 'content', 'tool_call_id', 'tool_calls',
+    'tool_name', 'timestamp', 'token_count', 'finish_reason', 'reasoning',
+    'reasoning_content', 'reasoning_details', 'codex_reasoning_items',
+]);
+function assertPhysicalSchema(backup) {
+    const tables = new Set(backup.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((row) => String(row.name)));
+    if (!tables.has('meta') || !tables.has('sessions') || !tables.has('messages')) {
+        throw new SessionContractError('SCHEMA_DRIFT', 'unrecognized Hermes state.db physical schema', { issues: [{ path: 'tables', code: 'custom' }] });
+    }
+    const marker = backup.prepare('SELECT value FROM meta WHERE key = ?').get('native_schema');
+    if (!marker || marker.value !== HERMES_NATIVE_PHYSICAL_SCHEMA) {
+        throw new SessionContractError('SCHEMA_DRIFT', 'unsupported Hermes state.db physical schema version', { issues: [{ path: 'meta.native_schema', code: 'custom' }] });
+    }
+    for (const [table, required] of [['sessions', REQUIRED_SESSION_COLUMNS], ['messages', REQUIRED_MESSAGE_COLUMNS]]) {
+        const columns = new Set(backup.prepare(`PRAGMA table_info(${table})`).all().map((row) => String(row.name)));
+        for (const column of required) {
+            if (!columns.has(column)) {
+                throw new SessionContractError('SCHEMA_DRIFT', `Hermes state.db table ${table} is missing column ${column}`, { issues: [{ path: `${table}.${column}`, code: 'custom' }] });
+            }
+        }
+    }
+}
+function parseJsonColumn(value, path) {
+    if (value === null || value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new SessionContractError('SCHEMA_DRIFT', `Hermes state.db column ${path} is not valid JSON`, { issues: [{ path, code: 'invalid_json' }] });
+    }
+}
+function optional(value) {
+    return value === null || value === undefined ? undefined : value;
+}
+/**
+ * Take a consistent backup of the live database (never opened for writing)
+ * and project workspace-matching sessions to snapshot JSONL. Returns null
+ * when no session matches the authorized workspace.
+ */
+export async function snapshotHermesStateDb(options) {
+    const canonicalRoot = await realpath(resolve(options.hermesRoot)).catch(() => resolve(options.hermesRoot));
+    const live = await authorizeLiveDb(join(options.hermesRoot, HERMES_STATE_DB_FILENAME), options.allowedRoots);
+    await assertReadableWithoutSidecarWrites(live);
+    const Database = loadSqlite();
+    await mkdir(options.stagingDir, { recursive: true, mode: STAGING_DIR_MODE });
+    const staging = await realpath(options.stagingDir);
+    const backupPath = join(staging, `.backup-${process.pid}-${Date.now()}.db`);
+    const projectionPath = hermesSnapshotProjectionPath(staging, canonicalRoot);
+    let source;
+    let backup;
+    try {
+        source = new Database(live, { readonly: true, fileMustExist: true });
+        await source.backup(backupPath);
+    }
+    catch (error) {
+        throw sqliteUnavailable(error, 'opening the provider database for backup');
+    }
+    finally {
+        source?.close();
+    }
+    try {
+        backup = new Database(backupPath, { readonly: true, fileMustExist: true });
+        assertPhysicalSchema(backup);
+        const sessions = backup.prepare('SELECT * FROM sessions ORDER BY started_at ASC, id ASC').all();
+        const lines = [];
+        let matched = 0;
+        let excluded = 0;
+        let bytes = 0;
+        for (const row of sessions) {
+            if (matched + excluded >= MAX_SESSIONS) {
+                throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Hermes snapshot exceeds the session limit', {
+                    limit: 'maxSessions', configured: MAX_SESSIONS, observed: matched + excluded + 1,
+                });
+            }
+            const cwd = typeof row.cwd === 'string' && row.cwd.length > 0 ? row.cwd : null;
+            const workspaceMatch = cwd ? await matchSessionWorkspace(cwd, options.workspaceId) : null;
+            if (!workspaceMatch) {
+                excluded += 1;
+                continue;
+            }
+            const messages = backup.prepare('SELECT * FROM messages WHERE session_id = ? ORDER BY seq ASC').all(String(row.id));
+            const record = {
+                schemaVersion: 23,
+                id: String(row.id),
+                source: String(row.source ?? 'cli'),
+                user_id: optional(row.user_id),
+                model: optional(row.model),
+                model_config: parseJsonColumn(row.model_config, 'sessions.model_config'),
+                parent_session_id: optional(row.parent_session_id),
+                compressed_from_session_id: optional(row.compressed_from_session_id),
+                started_at: row.started_at,
+                ended_at: optional(row.ended_at),
+                end_reason: optional(row.end_reason),
+                archived: row.archived,
+                inactive: row.inactive,
+                cwd,
+                git_branch: optional(row.git_branch),
+                routing_key: optional(row.routing_key),
+                input_tokens: optional(row.input_tokens),
+                output_tokens: optional(row.output_tokens),
+                cache_read_tokens: optional(row.cache_read_tokens),
+                cache_write_tokens: optional(row.cache_write_tokens),
+                reasoning_tokens: optional(row.reasoning_tokens),
+                estimated_cost_usd: optional(row.estimated_cost_usd),
+                actual_cost_usd: optional(row.actual_cost_usd),
+                billing_provider: optional(row.billing_provider),
+                messages: messages.map((message) => ({
+                    id: message.id,
+                    role: String(message.role),
+                    content: parseJsonColumn(message.content, 'messages.content'),
+                    tool_call_id: optional(message.tool_call_id),
+                    tool_calls: parseJsonColumn(message.tool_calls, 'messages.tool_calls'),
+                    tool_name: optional(message.tool_name),
+                    timestamp: optional(message.timestamp),
+                    token_count: optional(message.token_count),
+                    finish_reason: optional(message.finish_reason),
+                    reasoning: optional(message.reasoning),
+                    reasoning_content: optional(message.reasoning_content),
+                    reasoning_details: parseJsonColumn(message.reasoning_details, 'messages.reasoning_details'),
+                    codex_reasoning_items: parseJsonColumn(message.codex_reasoning_items, 'messages.codex_reasoning_items'),
+                })),
+                export_deleted_at: optional(row.export_deleted_at),
+                provider_deleted_at: optional(row.provider_deleted_at),
+                snapshotConsistency: 'sqlite-backup',
+            };
+            const line = `${JSON.stringify(record)}\n`;
+            bytes += Buffer.byteLength(line);
+            if (bytes > MAX_SOURCE_BYTES) {
+                throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Hermes snapshot exceeds the projection byte limit', {
+                    limit: 'maxBytes', configured: MAX_SOURCE_BYTES, observed: bytes,
+                });
+            }
+            lines.push(line);
+            matched += 1;
+        }
+        if (matched === 0)
+            return null;
+        await writeFile(projectionPath, lines.join(''), { mode: FILE_MODE });
+        await chmod(projectionPath, FILE_MODE);
+        return { projectionPath, authorizedRoot: staging, matched, excluded };
+    }
+    catch (error) {
+        throw sqliteUnavailable(error, 'reading the snapshot');
+    }
+    finally {
+        backup?.close();
+        await rm(backupPath, { force: true });
+    }
+}
+//# sourceMappingURL=hermes-state-db.js.map