@lmctl-ai/lmctl 0.1.342 → 0.2.3

package/dist/providers/debug.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Global debug logging.
+ *
+ * Usage:
+ *   initDebug(command)    — call once at startup from the root action
+ *   dlog("message")       — append to ~/.lmctl/debug-YYYY-MM-DD-HH.log if debug, no-op otherwise
+ *   isDebug()             — check current state (re-reads config every 5s)
+ *
+ * Four sources, any one enables debug:
+ *   1. --verbose CLI flag (sets _cliDebug at startup)
+ *   2. LMCTL_DEBUG=1 env var (checked at startup)
+ *   3. debug = true in ~/.lmctl/config.toml (re-read with 5s TTL)
+ *   4. {"debug": true} in ~/.lmctl/config.json (re-read with 5s TTL)
+ *
+ * All debug output goes to ~/.lmctl/debug-YYYY-MM-DD-HH.log
+ * (one file per hour, append mode) — NOT stderr. stderr is consumed by the transport layer and progress
+ * formatting; debug lines on stderr get lost or mixed with progress
+ * events. The log file can be examined after the fact with
+ * `ls -lt ~/.lmctl/debug-*.log | head -1` to find the latest, then
+ * `tail -f` on it.
+ *
+ * The file-based config check means you can enable debug mid-session
+ * by adding 'debug = true' to config.toml or {"debug": true} to config.json — it takes effect within
+ * 5s without restarting any running processes.
+ */
+interface Command {
+    opts(): Record<string, unknown>;
+    optsWithGlobals: () => Record<string, unknown>;
+}
+/**
+ * Initialize debug state. Call once at program startup.
+ * Reads from Commander --verbose flag or LMCTL_DEBUG env.
+ */
+/**
+ * Force CLI-level debug on (the top-level `lmctl --debug` flag). Equivalent to
+ * `--verbose` / `LMCTL_DEBUG=1` but driven by the parsed CLI flag in
+ * src/cli/index.ts, before any subcommand's Commander instance exists. Also
+ * exports LMCTL_DEBUG=1 so spawned children / env-based checks inherit it.
+ */
+export declare function enableCliDebug(): void;
+export interface CliDebugStateSnapshot {
+    cliDebug: boolean;
+    lmctlDebugEnv: string | undefined;
+}
+export declare function snapshotCliDebugState(): CliDebugStateSnapshot;
+export declare function restoreCliDebugState(snapshot: CliDebugStateSnapshot): void;
+export declare function initDebug(command?: Command): void;
+/**
+ * Check if debug mode is enabled. Cheap: the file-based check is
+ * cached with a 5-second TTL so repeated calls in a hot loop are free.
+ */
+export declare function isDebug(): boolean;
+export declare function isCliDebug(): boolean;
+/**
+ * Write a structured JSONL event to the debug log file.
+ * Every line has `ts`, `pid`, and `event` base fields plus any
+ * additional fields from the event object.
+ *
+ * @param event   Object with at least `event: string`. Extra fields
+ *                are spread into the JSON record.
+ * @param opts    `verbose: true` restricts to CLI-level debug only
+ *                (--verbose or LMCTL_DEBUG=1, not config.toml).
+ */
+export declare function debugLog(event: {
+    event: string;
+    [key: string]: unknown;
+}, opts?: {
+    verbose?: boolean;
+    always?: boolean;
+}): void;
+/**
+ * Append a debug message. Wraps in JSONL `{"event":"legacy","msg":"..."}`.
+ * No-op if debug is disabled. Never throws.
+ */
+export declare function dlog(...args: string[]): void;
+/**
+ * Verbose-only debug log. Same as dlog() but only fires when debug was
+ * enabled via --verbose or LMCTL_DEBUG=1 (the CLI sources). Config.toml
+ * debug=true does NOT enable verbose — it only enables the default level.
+ *
+ * Use dlogv() for high-volume / low-value lines (transport request/response,
+ * idle warnings, CWD, seed status). Use dlog() for MCP lifecycle + chat
+ * invocation lines that matter even in config-only debug mode.
+ */
+export declare function dlogv(...args: string[]): void;
+/**
+ * Unconditional structured error log. Bypasses the `isDebug()` gate so
+ * transport-layer failures (errors, timeouts, aborts, unhandled
+ * incoming requests) are ALWAYS recorded to `~/.lmctl/debug-*.log` for
+ * post-mortem — without forcing the user to set `LMCTL_DEBUG=1` ahead
+ * of time. Motivated by the opencode06 hang where the chat ran for
+ * 42+ minutes with no diagnostic in the debug log.
+ *
+ * The convention for the event payload is the same as `debugLog`:
+ *   { event: "transport_error" | "transport_timeout" | "transport_abort"
+ *           | "acp_unhandled_request" | ...,
+ *     provider: "claude"|"codex"|...,
+ *     session_id_short?: string,
+ *     error_class?: string,
+ *     error_message?: string,
+ *     elapsed_ms?: number,
+ *     ...kind-specific fields }
+ *
+ * Never throws (inherits `debugLog`'s best-effort guarantee).
+ */
+export declare function errorLog(event: {
+    event: string;
+    [key: string]: unknown;
+}): void;
+/**
+ * Remove old hourly debug log files, keeping the most recent `keep`
+ * files. Default: keep 24 (one day of hourly logs). Best-effort —
+ * never throws.
+ *
+ * @param keep      Number of newest files to retain.
+ * @param lmctlDir  Directory to scan; defaults to `~/.lmctl/`.
+ *                  Task 81 cleanup invokes this with a custom home
+ *                  so tests don't have to override HOME.
+ * @returns         `{ kept, removed }` filenames in their respective
+ *                  buckets — both arrays are sorted ascending
+ *                  (oldest first within each bucket). Failure
+ *                  produces a partial / empty result; never throws.
+ */
+export declare function rotateDebugLogs(keep?: number, lmctlDir?: string): {
+    kept: string[];
+    removed: string[];
+};
+export {};

package/dist/providers/dsh-sidecar.d.ts

@@ -0,0 +1,65 @@
+/**
+ * dsh `web` profile sidecar manager.
+ *
+ * dsh's headless profile is one-shot-only (no session resume, verified in
+ * `backlog/DESIGN-add-dsh-provider.md`). The only proven continuity path is
+ * `dsh web`'s internal HTTP RPC surface: it can cold-resume any session
+ * (headless- or web-created) by caller-supplied id, and `session.prompt`
+ * genuinely carries context forward turn to turn — proven end-to-end in the
+ * design doc's research.
+ *
+ * This module owns exactly one `dsh web` child process per lmctl process,
+ * spawned lazily on first use and reused for every `provider=dsh` member's
+ * turns (sessions are addressed by id over RPC, so one sidecar can serve
+ * many members/teams concurrently — there is no per-member sidecar needed).
+ *
+ * Verified live (2026-08-23): `dsh web --no-open --port 0` prints exactly
+ * one line, `dsh web: http://127.0.0.1:<port>`, once it's ready to accept
+ * connections.
+ */
+export interface DshRpcError {
+    message?: string;
+    code?: string;
+    [key: string]: unknown;
+}
+export declare class DshRpcCallError extends Error {
+    readonly method: string;
+    readonly detail: unknown;
+    constructor(method: string, detail: unknown);
+}
+export declare class DshSidecar {
+    readonly baseUrl: string;
+    private readonly child;
+    private constructor();
+    /** Test seam: a handle bound to an arbitrary base URL with no child
+     *  process (alive reports false; shutdown is a no-op). */
+    static forTesting(baseUrl: string): DshSidecar;
+    /**
+     * POST to `${baseUrl}/api/<method>` wrapped in the required envelope
+     * `{type: "client-request", rpcId, method, payload}` — verified live
+     * (2026-08-23) that the server rejects unwrapped bodies with a
+     * self-describing zod validation error naming exactly these four
+     * fields as missing/wrong, for `session.prompt` specifically (an
+     * earlier reading of the design doc's research assumed this endpoint
+     * took an unwrapped body; that was wrong, corrected here against the
+     * real server).
+     */
+    rpc(method: string, payload: unknown): Promise<unknown>;
+    /** True while the sidecar's child process is still alive. */
+    get alive(): boolean;
+    shutdown(): void;
+    static spawn(env: NodeJS.ProcessEnv): Promise<DshSidecar>;
+}
+/**
+ * Lazily spawn (once) and return the shared `dsh web` sidecar for this
+ * lmctl process. If a previously-spawned sidecar's process has died, spawns
+ * a fresh one rather than returning a dead handle. A FAILED boot attempt
+ * must not poison future calls either (F2): the rejected promise is dropped
+ * from the cache so the next call retries with whatever environment it
+ * brings, instead of rethrowing the stale boot error forever.
+ *
+ * `spawnFn` is a test seam — production callers always use the default.
+ */
+export declare function ensureDshSidecar(env: NodeJS.ProcessEnv, spawnFn?: (env: NodeJS.ProcessEnv) => Promise<DshSidecar>): Promise<DshSidecar>;
+/** Test/shutdown seam — not used by normal adapter turns. */
+export declare function shutdownDshSidecar(): Promise<void>;

package/dist/providers/dsh-zstd.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Concatenated-frame zstd decoding for dsh session files.
+ *
+ * dsh's `dsh-session-persistence-jsonl` appends to `session.jsonl.zstd`
+ * in flush batches, producing MULTIPLE concatenated zstd frames in one
+ * file (verified against real sessions: 12 frames in a 25 KB file, frame
+ * descriptor 0x04 = windowed frames with a 4-byte content checksum).
+ * Node's `zstdDecompressSync` / `createZstdDecompress` decode only the
+ * FIRST frame and silently drop the rest — so the frames must be walked
+ * and split manually before decoding.
+ *
+ * Frame layout (https://github.com/facebook/zstd/blob/dev/doc/zstd_compression_format.md):
+ *   magic (4) | frame header (variable) | blocks... | checksum (0|4)
+ * Frame header:
+ *   descriptor (1) | window descriptor (0|1) | dict id (0|1|2|4) | content size (0|1|2|4|8)
+ * Block header (3 bytes LE): bit0 = last, bits1-2 = type, bits3-23 = size.
+ */
+/**
+ * Split a buffer of concatenated zstd frames into per-frame slices.
+ * Trailing non-frame garbage (a torn append) is dropped silently.
+ */
+export declare function splitZstdFrames(buf: Buffer): Buffer[];
+/**
+ * Decode a dsh `session.jsonl.zstd` buffer (one or more concatenated
+ * zstd frames) to its full JSONL text.
+ */
+export declare function decompressDshSessionFile(buf: Buffer): string;

package/dist/providers/dsh.d.ts

@@ -0,0 +1,37 @@
+/**
+ * DeepSeek Harness (`dsh`) session provider.
+ *
+ * Reads dsh's own on-disk session files directly (`~/.dsh/sessions/<mangled-
+ * cwd>/session-<id>/session.jsonl.zstd`) — same read path whether the
+ * session was created by the `headless` profile or the `web` sidecar this
+ * provider's adapter drives (verified in `backlog/DESIGN-add-dsh-provider.md`:
+ * both profiles share one session store).
+ *
+ * cwd mangling (verified live, 2026-08-23): the absolute cwd has its
+ * leading/trailing slashes stripped, remaining `/` replaced with `-`, then
+ * the whole thing wrapped in `--` on both ends — e.g. `/tmp/dsh-probe` ->
+ * `--tmp-dsh-probe--`. Since a sessionId alone doesn't reveal which mangled
+ * directory it lives under, lookups by id scan all of them.
+ */
+import type { SessionDetail, SessionProvider, SessionSummary } from "./types.js";
+interface DshProviderOptions {
+    dshHome?: string;
+}
+export declare class DshProvider implements SessionProvider {
+    name: "dsh";
+    private sessionsDir;
+    constructor(opts?: DshProviderOptions);
+    discoverSessions(): Promise<SessionSummary[]>;
+    loadSession(sessionId: string): Promise<SessionDetail | null>;
+    resolveSessionPath(sessionId: string): Promise<string | null>;
+    deleteSession(sessionId: string): Promise<boolean>;
+    /** Absolute path a fresh session for `cwd` will be written to, given a
+     *  caller-chosen `sessionId` — used by the adapter to poll for the
+     *  session file after `session.create` + `session.prompt`, without a
+     *  discovery scan (it already knows both inputs). */
+    sessionFilePath(cwd: string, sessionId: string): string;
+    private findSessionDir;
+    private readRecords;
+    private readSummary;
+}
+export {};

package/dist/providers/frontmatter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Legacy strict-subset YAML-style frontmatter for `.lmctl` files.
+ *
+ * Format (visually SKILL.md-like, parser hand-rolled — no js-yaml dep):
+ *
+ *   ---
+ *   title: Frontend Team
+ *   description: Builds and maintains the frontend UI
+ *   members: Lead, Coder, Reviewer
+ *   ---
+ *   # Frontend Team
+ *   …body…
+ *
+ * Current `.lmctl` files do not require frontmatter. This parser is
+ * still used for older files and custom templates that choose to carry
+ * metadata. When a file does start with `---`, the block must list the
+ * three required keys (`title`, `description`, `members`) and close
+ * with `---` on its own line. Anything else — multi-line values, lists,
+ * unknown keys — is a hard error.
+ *
+ * `members` is a comma-separated alias list; whitespace around each
+ * is stripped, empty entries dropped (so `"a, , b"` parses as
+ * `["a", "b"]`; `""` parses as `[]`).
+ */
+export interface Frontmatter {
+    title: string;
+    description: string;
+    /** Aliases as written, in source order. May be `[]` if the value
+     *  was empty. Caller decides if empty is a problem. */
+    members: string[];
+    /** Character offset in the original text where the body starts —
+     *  i.e., the character right after the closing `---` newline. Use
+     *  `text.slice(bodyOffset)` to get the post-frontmatter content. */
+    bodyOffset: number;
+}
+export declare class FrontmatterError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse the strict-subset frontmatter block at the start of `text`.
+ *
+ * Throws `FrontmatterError` for any deviation: missing leading `---`,
+ * missing closing `---`, malformed key/value line, unknown key, or
+ * absent required key.
+ */
+export declare function parseFrontmatter(text: string): Frontmatter;

package/dist/providers/gemini-session-reader.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Format-aware reader for Gemini session files.
+ *
+ * Gemini ships TWO on-disk formats and both must coexist indefinitely:
+ *
+ * ── Old format ─ `.json`, single pretty-printed document
+ *
+ *     {
+ *       "sessionId": "<uuid>",
+ *       "projectHash": "<sha>",
+ *       "startTime": "...",
+ *       "lastUpdated": "...",
+ *       "messages": [
+ *         { "id": "...", "timestamp": "...", "type": "user|gemini",
+ *           "content": "...", "tokens": { ... } },
+ *         ...
+ *       ]
+ *     }
+ *
+ *   `tokens.input` is per-call prompt usage; cached prompt tokens
+ *   are a subset carried in `tokens.cached`.
+ *
+ * ── New format ─ `.jsonl`, line-delimited
+ *
+ *   Line 1 (metadata, no `messages`):
+ *     {"sessionId":"...","projectHash":"...","startTime":"...",
+ *      "lastUpdated":"...","kind":"main"}
+ *
+ *   Subsequent lines are EITHER messages (same shape as old
+ *   `messages[]` entries, with `content` possibly an array of
+ *   `{text}` parts) OR `$set` patches that mutate metadata fields:
+ *
+ *     {"id":"...","timestamp":"...","type":"user","content":[{"text":"..."}]}
+ *     {"$set":{"lastUpdated":"..."}}
+ *     {"id":"...","type":"gemini","tokens":{"input":N,...}}
+ *
+ *   `$set` patches apply in order; last write wins. We reconstruct
+ *   the equivalent of the old document's top-level fields plus a
+ *   synthesized `messages[]` so downstream code stays unchanged.
+ *
+ * ── Detection (content-based, NOT extension-based) ─
+ *
+ *   Try `JSON.parse(rawText)`. Success AND result has an array
+ *   `messages` field → old shape. Anything else (parse throws, OR
+ *   parsed object lacks `messages`) → JSONL. The extension is a
+ *   hint, not a decision; a renamed `.jsonl` containing a single
+ *   whole-doc JSON still parses as old, and a `.json`-named JSONL
+ *   still falls through to the line-by-line path.
+ */
+/**
+ * Result of `detectGeminiSessionFormat`. The third state — `"unknown"` —
+ * is Round 11 correction: rather than silently classifying garbage as
+ * one format and letting the parser fall over later, detection
+ * surfaces it explicitly so callers can emit a structured warning
+ * (`gemini_session_format_unknown`) and skip the file. Loud failure
+ * on future format drift instead of silent disappearance from
+ * `lmctl ls`.
+ */
+export type GeminiSessionFormat = "json" | "jsonl" | "unknown";
+/** Common shape returned by the parser regardless of source format.
+ *  Mirrors the old document's top-level fields plus an optional
+ *  `kind` (new-format marker). */
+export interface ParsedGeminiSession {
+    sessionId?: string;
+    projectHash?: string;
+    startTime?: string;
+    lastUpdated?: string;
+    /** "main" | "compact" on JSONL files; absent on old JSON files. */
+    kind?: string;
+    messages: ParsedGeminiMessage[];
+}
+/** Loose message shape covering both formats — `tokens` and
+ *  `thoughts` are the audit-relevant fields; `content` is the
+ *  display-relevant one and may be a string or an array of parts. */
+export interface ParsedGeminiMessage {
+    id?: string;
+    timestamp?: string;
+    type?: string;
+    content?: string | Array<{
+        text?: string;
+    }>;
+    thoughts?: Array<{
+        subject?: string;
+        description?: string;
+        timestamp?: string;
+    }>;
+    model?: string;
+    tokens?: {
+        input?: number;
+        output?: number;
+        cached?: number;
+        thoughts?: number;
+        tool?: number;
+        total?: number;
+    };
+}
+/**
+ * Detect the on-disk format of a Gemini session purely from its raw
+ * text content. Does NOT touch the filesystem and does NOT consult
+ * the file's extension.
+ *
+ * Detection order — JSONL FIRST (Round 11 correction):
+ *
+ *   1. JSONL fast path: file has multiple non-blank lines AND line
+ *      1 parses as a JSON object with a `kind` field (the de-facto
+ *      version marker for the new format). This is cheaper than a
+ *      whole-file parse on large old-format documents and matches
+ *      the format users will increasingly see going forward.
+ *   2. Whole-file JSON parse: if the file parses as a single object,
+ *      classify by content — `messages` array means old format;
+ *      a `kind` field (no messages yet) means a fresh JSONL session
+ *      that's just one metadata line so far.
+ *   3. Anything else → `"unknown"`.
+ *
+ * Empty / blank input also returns `"unknown"` — callers emit the
+ * `gemini_session_format_unknown` warning and skip the file. Throwing
+ * here would force every caller to wrap in try/catch and risks the
+ * "silently dropped session" failure mode this round was opened to fix.
+ */
+export declare function detectGeminiSessionFormat(raw: string): GeminiSessionFormat;
+/**
+ * Parse a Gemini session file's raw text into a uniform shape.
+ * Detects format via `detectGeminiSessionFormat`; old documents are
+ * returned as-is, new JSONL is replayed line-by-line into the
+ * equivalent old shape (metadata + synthesized `messages[]`).
+ *
+ * Throws when format is unknown (empty, malformed, or matching
+ * neither known shape). Callers — production code paths that read
+ * sessions — should detect with `detectGeminiSessionFormat` FIRST
+ * and emit a `gemini_session_format_unknown` warning before letting
+ * this function throw, so users see "which file was skipped, why"
+ * in the debug log.
+ *
+ * Individual subsequent JSONL lines that fail to parse (after the
+ * metadata line) are skipped silently — partial corruption shouldn't
+ * take out the rest of the session.
+ */
+export declare function parseGeminiSessionContent(raw: string): ParsedGeminiSession;
+/**
+ * Serialize a ParsedGeminiSession back to disk text in the requested
+ * format. Used by the fork path to preserve the source file's format
+ * (forking a `.jsonl` produces a `.jsonl`; forking a `.json` produces
+ * a `.json`).
+ *
+ * For JSONL output we DO NOT emit `$set` patches — those are append-
+ * only history that gemini writes incrementally; a fresh fork has
+ * already merged everything into its top-level metadata, so the
+ * minimal valid JSONL (metadata line + message lines) round-trips
+ * cleanly through gemini's own loader.
+ */
+export declare function serializeGeminiSession(session: ParsedGeminiSession, format: GeminiSessionFormat): string;

package/dist/providers/gemini.d.ts

@@ -0,0 +1,39 @@
+import type { SessionDetail, SessionProvider, SessionSummary } from "./types.js";
+interface GeminiProviderOptions {
+    geminiDir?: string;
+    claudeDir?: string;
+    codexDirs?: string[];
+    codexDir?: string;
+    codeDir?: string;
+    extraWorkspacePaths?: string[];
+}
+export declare class GeminiProvider implements SessionProvider {
+    name: "gemini";
+    private workspaceHashMap?;
+    private geminiProjectsFile;
+    private geminiTmpDir;
+    private claudeProjectsDir;
+    private codexSessionDirs;
+    private extraWorkspacePaths;
+    constructor(options?: GeminiProviderOptions);
+    getWatchPaths(): {
+        directory: string;
+        filePattern: RegExp;
+    }[];
+    discoverSessions(): Promise<SessionSummary[]>;
+    loadSession(sessionId: string): Promise<SessionDetail | null>;
+    private extractSummary;
+    private readSessionFile;
+    private extractSessionIdFromFilename;
+    private findSessionFiles;
+    resolveSessionPath(sessionId: string): Promise<string | null>;
+    deleteSession(sessionId: string): Promise<boolean>;
+    private resolveSessionFile;
+    private resolveWorkspace;
+    private getWorkspaceHashMap;
+    private collectGeminiProjectPaths;
+    private collectCodexCwds;
+    private collectClaudeCwds;
+    private findJsonlFiles;
+}
+export {};

package/dist/providers/hermes.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Hermes Agent ("hermes") session provider.
+ *
+ * Hermes persists every conversation in ONE SQLite store,
+ * `<HERMES_HOME>/state.db` (default `~/.hermes`), whose `sessions` table
+ * carries a `source` discriminator (`cli` / gateway platforms / `acp`).
+ * The ACP server (`hermes acp`) writes `source='acp'` rows, and its own
+ * resume path refuses anything else (`acp_adapter/session.py:341`:
+ * `row.get("source") != "acp"` ⇒ no restore). This reader mirrors that
+ * contract exactly: ACP-source rows only.
+ *
+ * Shape facts this reader depends on, each verified against a real store
+ * and against `acp_adapter/session.py`:
+ *
+ *  1. An ACP session only becomes a row once it has history
+ *     (`_persist()` returns early on empty history), so a session that
+ *     was created but never prompted does not exist for discovery.
+ *  2. Assistant rows keep tool calls in a JSON `tool_calls` column
+ *     (`[{id, call_id, function:{name, arguments}}]`) while results land
+ *     on separate `role='tool'` rows keyed by `tool_call_id`. Emitting
+ *     both keeps tool-call/result pairing intact for session inspection.
+ *  3. A resume replays the `active = 1` set only
+ *     (`get_messages_as_conversation` defaults to `include_inactive=False`),
+ *     so the transcript here does too: compaction archives pre-summary
+ *     turns and a rewind flags taken-back rows `active = 0`, and neither
+ *     belongs in the conversation a resumed member sees.
+ *
+ * Schema contract: every column both queries name exists in Hermes's real
+ * `SCHEMA_SQL` (`hermes_state_common.py`) — asserted against a store a real
+ * `SessionDB` produced, not a hand-written fixture
+ * (`tests/providers/hermes-real-schema.test.ts`).
+ *
+ * Token accounting: the `sessions` row carries aggregate counters only
+ * (input/output/cache-read/cache-write/reasoning), which is the same
+ * "partial" standard as codex/gemini/qwen.
+ */
+import type { SessionProvider, SessionSummary, SessionDetail } from "./types.js";
+export interface HermesProviderOptions {
+    /**
+     * Explicit effective HERMES_HOME. Defaults to `$HERMES_HOME`, then
+     * `~/.hermes`. A PROFILE is a different home (`<root>/profiles/<name>`
+     * — see `hermes_constants.get_default_hermes_root`), so a caller
+     * selecting a profile passes that profile's home path here; there is no
+     * separate profile knob and `HERMES_PROFILE` is only the profile's
+     * display NAME, never a path segment.
+     */
+    hermesHome?: string;
+    /** Read-only connection `PRAGMA busy_timeout` in ms. Default 5000. */
+    busyTimeoutMs?: number;
+    /** Max sessions returned by discovery. Default 200. */
+    discoverLimit?: number;
+}
+/**
+ * Resolve HERMES_HOME the way `hermes_constants.get_hermes_home()` does:
+ * an explicit override, then the `HERMES_HOME` env var, then the platform
+ * default `~/.hermes`.
+ */
+export declare function resolveHermesHome(opts?: {
+    hermesHome?: string;
+}): string;
+/** `<HERMES_HOME>/state.db` — the one store every Hermes session lives in. */
+export declare function resolveHermesStateDbPath(opts?: HermesProviderOptions): string;
+export declare class HermesProvider implements SessionProvider {
+    readonly name: "hermes";
+    private readonly dbPath;
+    private readonly busyTimeoutMs;
+    private readonly discoverLimit;
+    constructor(opts?: HermesProviderOptions);
+    /** Exposed for diagnostics (`lmctl ls --provider hermes` shows nothing
+     *  when this path does not exist, which is the common first-run state). */
+    get stateDbPath(): string;
+    private openDb;
+    private selectSessionRow;
+    discoverSessions(): Promise<SessionSummary[]>;
+    /**
+     * Read the live (`active = 1`) transcript rows for a session.
+     *
+     * Same set a Hermes resume replays: `active = 0` rows are turns a rewind
+     * took back, and the pre-compaction turns an archive flagged
+     * `active = 0, compacted = 1` were replaced by the summary in the
+     * conversation the member sees. A store old enough to predate the column
+     * has no archived rows either, so the fallback is faithful, not lenient.
+     */
+    private activeMessageRows;
+    /** Read only the preview endpoints, not every transcript body. */
+    private previewTexts;
+    loadSession(sessionId: string): Promise<SessionDetail | null>;
+    resolveSessionPath(sessionId: string): Promise<string | null>;
+    deleteSession(_sessionId: string): Promise<boolean>;
+}