sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/providers/openCode.js

@@ -0,0 +1,2008 @@
+/**
+ * @fileoverview OpenCode session provider for the shared package.
+ *
+ * Implements SessionProviderBase for monitoring OpenCode CLI sessions.
+ * Uses SQLite database as primary data source (opencode.db), with
+ * file-based scanning as fallback for older OpenCode installations.
+ *
+ * Ported from sidekick-vscode/src/services/providers/OpenCodeSessionProvider.ts
+ *
+ * OpenCode file storage layout (legacy):
+ * - Base: $XDG_DATA_HOME/opencode/ or ~/.local/share/opencode/
+ * - Sessions: storage/session/{projectID}/{sessionID}.json
+ * - Messages: storage/message/{sessionID}/{messageID}.json
+ * - Parts: storage/part/{messageID}/{partID}.json
+ *
+ * @module providers/openCode
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { readSessionContextSnapshot } from '../context/sessionContext';
+import { readSessionFileStats } from '../sessionStats';
+import { convertOpenCodeMessage, parseDbMessageData, parseDbPartData, normalizeToolName, normalizeToolInput, } from '../parsers/openCodeParser';
+import { OpenCodeDatabase } from './openCodeDatabase';
+import { normalizeProviderUsage } from '../usageNormalization';
+import { addUsageToSubagent } from '../usage/subagentUsage';
+import { accumulateZaiUsage, inferZaiQuotaState, parseZaiQuotaError, ZAI_PROVIDER_IDS, } from '../zaiQuota';
+import { ProviderDiagnosticTracker, diagnosticFromRuntimeStatus } from './diagnostics';
+import { getModelContextWindowSize } from '../modelContext';
+// ---------------------------------------------------------------------------
+// Helper functions
+// ---------------------------------------------------------------------------
+/**
+ * Gets the OpenCode data directory.
+ *
+ * Resolves in priority order: `XDG_DATA_HOME` (if set), then whichever of
+ * the platform-default candidates actually contains an `opencode.db` file.
+ * OpenCode's CLI has historically used the Linux-style `~/.local/share/opencode`
+ * path even on macOS, so we probe both and pick whichever exists — falling
+ * back to the platform default when neither is present yet.
+ */
+export function getOpenCodeDataDir() {
+    const xdg = process.env.XDG_DATA_HOME;
+    if (xdg)
+        return path.join(xdg, 'opencode');
+    const candidates = [path.join(os.homedir(), '.local', 'share', 'opencode')];
+    if (process.platform === 'darwin') {
+        candidates.push(path.join(os.homedir(), 'Library', 'Application Support', 'opencode'));
+    }
+    else if (process.platform === 'win32') {
+        candidates.push(path.join(process.env.LOCALAPPDATA ||
+            process.env.APPDATA ||
+            path.join(os.homedir(), 'AppData', 'Local'), 'opencode'));
+    }
+    for (const candidate of candidates) {
+        try {
+            if (fs.existsSync(path.join(candidate, 'opencode.db')))
+                return candidate;
+        }
+        catch {
+            // ignore — try the next candidate.
+        }
+    }
+    // Nothing found yet — return the platform default so a fresh OpenCode
+    // install gets detected at the conventional location for this OS.
+    if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', 'opencode');
+    }
+    if (process.platform === 'win32') {
+        return path.join(process.env.LOCALAPPDATA ||
+            process.env.APPDATA ||
+            path.join(os.homedir(), 'AppData', 'Local'), 'opencode');
+    }
+    return path.join(os.homedir(), '.local', 'share', 'opencode');
+}
+/**
+ * Gets the storage base directory within OpenCode's data dir.
+ */
+function getStorageDir() {
+    return path.join(getOpenCodeDataDir(), 'storage');
+}
+/**
+ * Pattern matching model IDs and generic agent names that don't convey type info.
+ */
+const GENERIC_AGENT_RE = /^(gpt-|claude-|o[1-9]|gemini|default|agent|worker)/i;
+/**
+ * Returns true if the raw agent type is a model ID or generic name
+ * that doesn't convey meaningful type information.
+ */
+function isGenericAgentType(type) {
+    return GENERIC_AGENT_RE.test(type);
+}
+/**
+ * Detects a meaningful agent type from the description using keyword matching.
+ * Returns undefined if no keywords match.
+ */
+function detectAgentTypeFromDescription(desc) {
+    const lower = desc.toLowerCase();
+    if (lower.includes('explore') || lower.includes('research') || lower.includes('investigate')) {
+        return 'Explore';
+    }
+    if (lower.includes('plan') || lower.includes('architect') || lower.includes('design')) {
+        return 'Plan';
+    }
+    if (lower.includes('task') ||
+        lower.includes('execute') ||
+        lower.includes('implement') ||
+        lower.includes('build')) {
+        return 'Task';
+    }
+    return undefined;
+}
+/**
+ * Normalizes a raw agent type. If the raw type is a model ID or generic name,
+ * falls back to keyword detection from the description.
+ */
+function normalizeAgentType(rawType, description) {
+    if (!rawType)
+        return rawType;
+    if (!isGenericAgentType(rawType))
+        return rawType;
+    // Raw type is a model ID or generic name -- try to detect from description
+    if (description) {
+        return detectAgentTypeFromDescription(description) || rawType;
+    }
+    return rawType;
+}
+/** Prefix for synthetic DB session paths */
+const DB_SESSION_PREFIX = 'db-sessions';
+/** Build a synthetic session path for a DB-backed session. */
+function makeDbSessionPath(dataDir, projectId, sessionId) {
+    return path.join(dataDir, DB_SESSION_PREFIX, projectId, `${sessionId}.json`);
+}
+/** Check if a path is a synthetic DB session path. */
+function isDbSessionPath(sessionPath) {
+    return sessionPath.includes(path.sep + DB_SESSION_PREFIX + path.sep);
+}
+/**
+ * Whether a session recorded in `sessionDirectory` belongs to `workspacePath`.
+ *
+ * A session started inside the workspace (the workspace itself or any
+ * subdirectory, e.g. a monorepo package) matches. A session started in a
+ * *parent* of the workspace does not: a sub-package workspace must not list
+ * every session of the enclosing repo as its own.
+ */
+function workspaceMatches(sessionDirectory, workspacePath) {
+    const session = path
+        .resolve(sessionDirectory)
+        .replace(/[\\/]+$/, '')
+        .toLowerCase();
+    const workspace = path
+        .resolve(workspacePath)
+        .replace(/[\\/]+$/, '')
+        .toLowerCase();
+    return session === workspace || session.startsWith(workspace + path.sep);
+}
+/** Extract project ID from a synthetic DB session path. */
+function extractProjectIdFromDbPath(sessionPath) {
+    const prefix = path.sep + DB_SESSION_PREFIX + path.sep;
+    const idx = sessionPath.indexOf(prefix);
+    if (idx < 0)
+        return null;
+    const rest = sessionPath.substring(idx + prefix.length);
+    const slashIdx = rest.indexOf(path.sep);
+    return slashIdx > 0 ? rest.substring(0, slashIdx) : null;
+}
+/** Extract role from a DB message row payload. */
+function extractRoleFromDbMessage(row) {
+    try {
+        const data = JSON.parse(row.data);
+        if (data.role === 'user' || data.role === 'assistant' || data.role === 'system') {
+            return data.role;
+        }
+    }
+    catch {
+        // Ignore malformed payloads
+    }
+    return 'unknown';
+}
+/** Extract parent message ID from a DB message row payload. */
+function extractParentIdFromDbMessage(row) {
+    try {
+        const data = JSON.parse(row.data);
+        return typeof data.parentID === 'string' && data.parentID.length > 0 ? data.parentID : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolves the OpenCode project ID for a workspace path.
+ *
+ * Tries DB first, then file-based project metadata, then git root commit hash.
+ */
+function resolveProjectId(workspacePath, db, runtimeStatus) {
+    // Strategy 1: DB lookup
+    if (db) {
+        const dbProject = db.findProjectByWorktree(workspacePath);
+        if (dbProject)
+            return dbProject.id;
+        const byDirectory = db.findProjectBySessionDirectory(workspacePath);
+        if (byDirectory)
+            return byDirectory.id;
+    }
+    if (runtimeStatus.kind !== 'db_missing') {
+        return null;
+    }
+    // Strategy 2: scan project files to find matching path
+    return resolveProjectIdFromFiles(workspacePath);
+}
+function resolveProjectIdFromFiles(workspacePath) {
+    const workspaceResolved = normalizePath(workspacePath);
+    try {
+        const projectDir = path.join(getStorageDir(), 'project');
+        if (!fs.existsSync(projectDir))
+            return resolveProjectIdFromGit(workspacePath);
+        const files = fs.readdirSync(projectDir).filter((f) => f.endsWith('.json'));
+        const matches = [];
+        for (const file of files) {
+            try {
+                const project = JSON.parse(fs.readFileSync(path.join(projectDir, file), 'utf-8'));
+                if (project.path) {
+                    const projectPath = normalizePath(project.path);
+                    if (projectPath === workspaceResolved) {
+                        matches.push({ id: project.id, path: projectPath });
+                        continue;
+                    }
+                    if (workspaceResolved.startsWith(projectPath + path.sep)) {
+                        matches.push({ id: project.id, path: projectPath });
+                        continue;
+                    }
+                    if (projectPath.startsWith(workspaceResolved + path.sep)) {
+                        matches.push({ id: project.id, path: projectPath });
+                    }
+                }
+            }
+            catch {
+                // Skip malformed project files
+            }
+        }
+        if (matches.length > 0) {
+            matches.sort((a, b) => b.path.length - a.path.length);
+            return matches[0].id;
+        }
+    }
+    catch {
+        // Can't read project directory
+    }
+    return resolveProjectIdFromGit(workspacePath);
+}
+function resolveProjectIdFromGit(workspacePath) {
+    try {
+        const hash = execSync('git rev-list --max-parents=0 HEAD', {
+            cwd: workspacePath,
+            encoding: 'utf-8',
+            timeout: 4000,
+            killSignal: 'SIGKILL',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        })
+            .trim()
+            .split('\n')[0];
+        if (hash && /^[a-f0-9]+$/i.test(hash)) {
+            return hash;
+        }
+    }
+    catch {
+        // Git not available or not a git repo
+    }
+    return null;
+}
+/**
+ * Safely reads and parses a JSON file, returning null on failure.
+ */
+function readJsonSafe(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Truncate a title to 60 chars with ellipsis. */
+function truncateTitle(title) {
+    const trimmed = title.trim();
+    if (trimmed.length > 60) {
+        return trimmed.substring(0, 57) + '...';
+    }
+    return trimmed;
+}
+function normalizePath(input) {
+    try {
+        return fs.realpathSync(input);
+    }
+    catch {
+        return path.resolve(input);
+    }
+}
+function messageCreatedMs(message) {
+    const created = message.time?.created;
+    const ms = typeof created === 'number' ? created : Date.parse(String(created ?? ''));
+    return Number.isFinite(ms) ? ms : 0;
+}
+class OpenCodeFileReader {
+    sessionId;
+    seenMessages = new Map();
+    pendingSkip = 0;
+    storageBase;
+    constructor(sessionId) {
+        this.sessionId = sessionId;
+        this.storageBase = getStorageDir();
+    }
+    readNew() {
+        const messageDir = path.join(this.storageBase, 'message', this.sessionId);
+        if (!fs.existsSync(messageDir))
+            return [];
+        let messageFiles;
+        try {
+            messageFiles = fs.readdirSync(messageDir).filter((f) => f.endsWith('.json'));
+        }
+        catch {
+            return [];
+        }
+        const entries = [];
+        for (const file of messageFiles) {
+            const msgId = path.basename(file, '.json');
+            const messagePath = path.join(messageDir, file);
+            const message = readJsonSafe(messagePath);
+            if (!message)
+                continue;
+            let mtimeMs = 0;
+            try {
+                mtimeMs = fs.statSync(messagePath).mtimeMs;
+            }
+            catch {
+                mtimeMs = 0;
+            }
+            const parts = this.readParts(msgId);
+            entries.push({ msgId, message, mtimeMs, parts, partIds: new Set(parts.map((p) => p.id)) });
+        }
+        if (this.pendingSkip > 0) {
+            // A position for this reader is a message count (see getPosition()), so a
+            // seek marks the oldest N messages as already seen without emitting them.
+            const ordered = [...entries].sort((a, b) => messageCreatedMs(a.message) - messageCreatedMs(b.message) ||
+                a.msgId.localeCompare(b.msgId));
+            for (const entry of ordered.slice(0, this.pendingSkip)) {
+                this.seenMessages.set(entry.msgId, { partIds: entry.partIds, mtimeMs: entry.mtimeMs });
+            }
+            this.pendingSkip = 0;
+        }
+        const newEvents = [];
+        for (const entry of entries) {
+            const previous = this.seenMessages.get(entry.msgId);
+            const isNewMessage = !previous;
+            let hasNewParts = false;
+            if (previous) {
+                if (previous.mtimeMs !== entry.mtimeMs) {
+                    hasNewParts = true;
+                }
+                else if (entry.partIds.size !== previous.partIds.size) {
+                    hasNewParts = true;
+                }
+                else {
+                    for (const partId of entry.partIds) {
+                        if (!previous.partIds.has(partId)) {
+                            hasNewParts = true;
+                            break;
+                        }
+                    }
+                }
+            }
+            if (isNewMessage || hasNewParts) {
+                newEvents.push(...convertOpenCodeMessage(entry.message, entry.parts));
+                this.seenMessages.set(entry.msgId, { partIds: entry.partIds, mtimeMs: entry.mtimeMs });
+            }
+        }
+        // Sort by timestamp
+        return newEvents.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    }
+    readParts(msgId) {
+        const partDir = path.join(this.storageBase, 'part', msgId);
+        if (!fs.existsSync(partDir))
+            return [];
+        try {
+            return fs
+                .readdirSync(partDir)
+                .filter((f) => f.endsWith('.json'))
+                .map((f) => readJsonSafe(path.join(partDir, f)))
+                .filter((p) => p !== null);
+        }
+        catch {
+            // Skip unreadable part directories
+            return [];
+        }
+    }
+    readAll() {
+        this.reset();
+        return this.readNew();
+    }
+    reset() {
+        this.seenMessages.clear();
+        this.pendingSkip = 0;
+    }
+    exists() {
+        return fs.existsSync(path.join(this.storageBase, 'message', this.sessionId));
+    }
+    flush() {
+        // No-op for JSON file reading
+    }
+    getPosition() {
+        return this.seenMessages.size;
+    }
+    seekTo(position) {
+        // Positions are message counts (getPosition()), so the next readNew() marks
+        // the oldest `position` messages as seen and emits only what follows.
+        this.pendingSkip = Number.isFinite(position) && position > 0 ? Math.floor(position) : 0;
+    }
+    wasTruncated() {
+        return false; // JSON files don't truncate
+    }
+}
+// ---------------------------------------------------------------------------
+// DB-backed reader
+// ---------------------------------------------------------------------------
+/**
+ * Incremental reader for DB-backed OpenCode sessions.
+ *
+ * Uses time_updated timestamps to track which data has been seen,
+ * querying only for newer messages/parts on each readNew() call.
+ */
+/** How long a database-backed reader trusts its last session-row check. */
+const DB_EXISTS_MEMO_MS = 30_000;
+class OpenCodeDbReader {
+    sessionId;
+    db;
+    lastTimeUpdated = 0;
+    hasReadOnce = false;
+    existsCheckedAtMs = 0;
+    existsResult = true;
+    constructor(sessionId, db) {
+        this.sessionId = sessionId;
+        this.db = db;
+    }
+    readNew() {
+        // On first call, load the full session history so that attaching to an
+        // existing session populates the dashboard with all prior events.
+        // This matches the behavior of OpenCodeFileReader and the Claude Code
+        // JSONL reader where the first readNew() returns all existing data.
+        if (!this.hasReadOnce) {
+            this.hasReadOnce = true;
+            return this.readAllInternal();
+        }
+        return this.readIncremental();
+    }
+    /**
+     * Reads all messages and parts for the session, converting them to events.
+     * Used for initial history load and readAll().
+     */
+    readAllInternal() {
+        const events = [];
+        const messages = this.db.getMessagesForSession(this.sessionId);
+        const parts = this.db.getPartsForSession(this.sessionId);
+        if (messages.length === 0) {
+            return [];
+        }
+        // Group parts by message_id
+        const partsByMessage = new Map();
+        for (const part of parts) {
+            const existing = partsByMessage.get(part.message_id);
+            if (existing) {
+                existing.push(part);
+            }
+            else {
+                partsByMessage.set(part.message_id, [part]);
+            }
+        }
+        // Sort messages by creation time
+        messages.sort((a, b) => a.time_created - b.time_created);
+        // Filter user messages that haven't been processed yet
+        const userMessageIds = messages
+            .filter((m) => extractRoleFromDbMessage(m) === 'user')
+            .map((m) => m.id);
+        const processedUserMessageIds = new Set(this.db.getProcessedUserMessageIds(this.sessionId, userMessageIds));
+        for (const msgRow of messages) {
+            try {
+                if (extractRoleFromDbMessage(msgRow) === 'user' &&
+                    !processedUserMessageIds.has(msgRow.id)) {
+                    continue;
+                }
+                const message = parseDbMessageData(msgRow);
+                const msgParts = (partsByMessage.get(msgRow.id) || [])
+                    .map((row) => {
+                    try {
+                        return parseDbPartData(row);
+                    }
+                    catch {
+                        return null;
+                    }
+                })
+                    .filter((p) => p !== null);
+                events.push(...convertOpenCodeMessage(message, msgParts));
+            }
+            catch {
+                // Skip malformed messages
+            }
+        }
+        // Set cursor to max time_updated across all results
+        let maxTimeUpdated = this.lastTimeUpdated;
+        for (const m of messages) {
+            if (m.time_updated > maxTimeUpdated)
+                maxTimeUpdated = m.time_updated;
+        }
+        for (const p of parts) {
+            if (p.time_updated > maxTimeUpdated)
+                maxTimeUpdated = p.time_updated;
+        }
+        this.lastTimeUpdated = maxTimeUpdated;
+        return events.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    }
+    /**
+     * Reads only messages/parts newer than the last cursor position.
+     * Used for subsequent polling calls after the initial history load.
+     */
+    readIncremental() {
+        const events = [];
+        // Get messages and parts that are newer than what we've seen
+        const messages = this.db.getMessagesNewerThan(this.sessionId, this.lastTimeUpdated);
+        const parts = this.db.getPartsNewerThan(this.sessionId, this.lastTimeUpdated);
+        if (messages.length === 0 && parts.length === 0) {
+            return [];
+        }
+        // Build set of affected message IDs from both message and part changes
+        const affectedMessageIds = new Set(messages.map((m) => m.id));
+        for (const part of parts) {
+            affectedMessageIds.add(part.message_id);
+        }
+        // If an assistant reply arrives, include its parent user message so
+        // queued user prompts are surfaced only once they are actually processed.
+        for (const msg of messages) {
+            const parentId = extractParentIdFromDbMessage(msg);
+            if (parentId) {
+                affectedMessageIds.add(parentId);
+            }
+        }
+        // Fetch missing message rows for part-only updates
+        const messageMap = new Map(messages.map((m) => [m.id, m]));
+        const missingMessageIds = [...affectedMessageIds].filter((id) => !messageMap.has(id));
+        if (missingMessageIds.length > 0) {
+            const missingRows = this.db.getMessagesByIds(this.sessionId, missingMessageIds);
+            for (const row of missingRows) {
+                messageMap.set(row.id, row);
+            }
+            const unresolved = missingMessageIds.filter((id) => !messageMap.has(id));
+            if (unresolved.length > 0) {
+                // Keep cursor unchanged so we can retry on next polling cycle.
+                return [];
+            }
+        }
+        const targetMessages = [...messageMap.values()];
+        const targetMessageIds = targetMessages.map((m) => m.id);
+        // Fetch complete part sets for all affected messages in one batched query
+        const allParts = this.db.getPartsForMessages(this.sessionId, targetMessageIds);
+        const partsByMessage = new Map();
+        for (const part of allParts) {
+            const existing = partsByMessage.get(part.message_id);
+            if (existing) {
+                existing.push(part);
+            }
+            else {
+                partsByMessage.set(part.message_id, [part]);
+            }
+        }
+        // Track max time_updated across all results
+        let maxTimeUpdated = this.lastTimeUpdated;
+        for (const m of messages) {
+            if (m.time_updated > maxTimeUpdated)
+                maxTimeUpdated = m.time_updated;
+        }
+        for (const p of parts) {
+            if (p.time_updated > maxTimeUpdated)
+                maxTimeUpdated = p.time_updated;
+        }
+        // Convert each message + its parts to events
+        // Sort messages by creation time
+        targetMessages.sort((a, b) => a.time_created - b.time_created);
+        const userMessageIds = targetMessages
+            .filter((m) => extractRoleFromDbMessage(m) === 'user')
+            .map((m) => m.id);
+        const processedUserMessageIds = new Set(this.db.getProcessedUserMessageIds(this.sessionId, userMessageIds));
+        for (const msgRow of targetMessages) {
+            try {
+                if (extractRoleFromDbMessage(msgRow) === 'user' &&
+                    !processedUserMessageIds.has(msgRow.id)) {
+                    continue;
+                }
+                const message = parseDbMessageData(msgRow);
+                const msgParts = (partsByMessage.get(msgRow.id) || [])
+                    .map((row) => {
+                    try {
+                        return parseDbPartData(row);
+                    }
+                    catch {
+                        return null;
+                    }
+                })
+                    .filter((p) => p !== null);
+                events.push(...convertOpenCodeMessage(message, msgParts));
+            }
+            catch {
+                // Skip malformed messages
+            }
+        }
+        this.lastTimeUpdated = maxTimeUpdated;
+        return events;
+    }
+    readAll() {
+        this.reset();
+        return this.readAllInternal();
+    }
+    reset() {
+        this.lastTimeUpdated = 0;
+        this.hasReadOnce = false;
+    }
+    exists() {
+        // DB-backed sessions are durable rows rather than ephemeral files. The row
+        // check costs a sqlite3 subprocess, so it is memoised, and a transient
+        // query failure still reports "exists" so SessionMonitor does not flap
+        // into discovery mode.
+        const now = Date.now();
+        if (now - this.existsCheckedAtMs < DB_EXISTS_MEMO_MS)
+            return this.existsResult;
+        this.existsCheckedAtMs = now;
+        try {
+            const row = this.db.getSession(this.sessionId);
+            this.existsResult = row !== null || this.db.getRuntimeStatus().kind === 'query_failed';
+        }
+        catch {
+            this.existsResult = true;
+        }
+        return this.existsResult;
+    }
+    flush() {
+        // No-op for DB reading
+    }
+    getPosition() {
+        return this.lastTimeUpdated;
+    }
+    seekTo(position) {
+        this.lastTimeUpdated = position;
+        this.hasReadOnce = true; // Skip full history load on next readNew()
+    }
+    wasTruncated() {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Main provider
+// ---------------------------------------------------------------------------
+/**
+ * Session provider for OpenCode CLI.
+ *
+ * Uses SQLite database as primary data source, with file-based
+ * scanning as fallback for older OpenCode installations.
+ */
+export class OpenCodeProvider {
+    id = 'opencode';
+    displayName = 'OpenCode';
+    db = null;
+    dbInitialized = false;
+    dbStatus = { available: false, kind: 'db_missing' };
+    diagnostics;
+    /** Cache of session metadata populated during listing */
+    sessionMetaCache = new Map();
+    /** Runtime-reported context window limit (overrides static map when set). */
+    dynamicContextWindowLimit = null;
+    constructor(options = {}) {
+        this.diagnostics = new ProviderDiagnosticTracker(this.id, options);
+    }
+    /** Lazy-initialize the database connection. */
+    ensureDb() {
+        if (this.dbInitialized)
+            return this.db;
+        this.dbInitialized = true;
+        const dataDir = getOpenCodeDataDir();
+        const db = new OpenCodeDatabase(dataDir);
+        if (db.open()) {
+            this.db = db;
+        }
+        this.dbStatus = db.getRuntimeStatus();
+        return this.db;
+    }
+    async ensureDbAsync() {
+        if (this.db)
+            return this.db;
+        return new OpenCodeDatabase(getOpenCodeDataDir());
+    }
+    /**
+     * Cache an async-created database only after an operation proved it usable.
+     * Sync paths treat a cached `db` as "open() succeeded", so adopting an
+     * unproven instance would cut them off from the file-storage fallback.
+     */
+    adoptDbIfAvailable(db) {
+        if (this.db || !db.getRuntimeStatus().available)
+            return;
+        this.db = db;
+        this.dbInitialized = true;
+    }
+    getRuntimeStatus() {
+        const db = this.ensureDb();
+        if (db)
+            return db.getRuntimeStatus();
+        return this.dbStatus;
+    }
+    getLastOperationStatus() {
+        return this.diagnostics.getLastOperationStatus();
+    }
+    canMonitorDirectory(dir) {
+        if (fs.existsSync(dir))
+            return true;
+        const db = this.ensureDb();
+        if (!db)
+            return false;
+        const projectId = extractProjectIdFromDbPath(dir + path.sep + 'dummy.json') || path.basename(dir);
+        return projectId.length > 0 && db.hasProject(projectId);
+    }
+    mapDbSessions(projectId) {
+        const db = this.ensureDb();
+        if (!db)
+            return [];
+        const sessions = db.getSessionsForProject(projectId);
+        const dataDir = getOpenCodeDataDir();
+        return sessions.map((session) => {
+            const syntheticPath = makeDbSessionPath(dataDir, projectId, session.id);
+            this.sessionMetaCache.set(syntheticPath, {
+                title: session.title,
+                timeUpdated: session.time_updated,
+            });
+            return syntheticPath;
+        });
+    }
+    // --- Path resolution ---
+    getSessionDirectory(workspacePath) {
+        const db = this.ensureDb();
+        const dbStatus = this.getRuntimeStatus();
+        const projectId = resolveProjectId(workspacePath, db, dbStatus);
+        if (projectId) {
+            // For DB sessions, return a synthetic directory path
+            if (db) {
+                return path.join(getOpenCodeDataDir(), DB_SESSION_PREFIX, projectId);
+            }
+            return path.join(getStorageDir(), 'session', projectId);
+        }
+        if (dbStatus.kind !== 'db_missing') {
+            return path.join(getOpenCodeDataDir(), DB_SESSION_PREFIX);
+        }
+        return path.join(getStorageDir(), 'session');
+    }
+    discoverSessionDirectory(workspacePath) {
+        const db = this.ensureDb();
+        const dbStatus = this.getRuntimeStatus();
+        const projectId = resolveProjectId(workspacePath, db, dbStatus);
+        if (!projectId)
+            return null;
+        // DB: check if project has sessions
+        if (db) {
+            if (db.hasProject(projectId)) {
+                return path.join(getOpenCodeDataDir(), DB_SESSION_PREFIX, projectId);
+            }
+        }
+        if (dbStatus.kind !== 'db_missing') {
+            return null;
+        }
+        // File fallback
+        const dir = path.join(getStorageDir(), 'session', projectId);
+        return fs.existsSync(dir) ? dir : null;
+    }
+    // --- Session discovery ---
+    findActiveSession(workspacePath) {
+        const db = this.ensureDb();
+        const dbStatus = this.getRuntimeStatus();
+        const projectId = resolveProjectId(workspacePath, db, dbStatus);
+        if (!projectId) {
+            this.recordDatabaseStatus('findActiveSession', dbStatus.kind === 'db_missing');
+            return null;
+        }
+        // DB primary
+        if (db) {
+            const session = db.getMostRecentSession(projectId);
+            if (session) {
+                const syntheticPath = makeDbSessionPath(getOpenCodeDataDir(), projectId, session.id);
+                this.sessionMetaCache.set(syntheticPath, {
+                    title: session.title,
+                    timeUpdated: session.time_updated,
+                });
+                this.recordDatabaseStatus('findActiveSession', true);
+                return syntheticPath;
+            }
+        }
+        if (dbStatus.kind !== 'db_missing') {
+            this.recordDatabaseStatus('findActiveSession', dbStatus.available);
+            return null;
+        }
+        // File fallback
+        const result = this.findActiveSessionFromFiles(projectId);
+        this.recordDatabaseStatus('findActiveSession', true);
+        return result;
+    }
+    findActiveSessionFromFiles(projectId) {
+        const sessionDir = path.join(getStorageDir(), 'session', projectId);
+        if (!fs.existsSync(sessionDir))
+            return null;
+        let bestPath = null;
+        let bestMtime = 0;
+        try {
+            const files = fs.readdirSync(sessionDir).filter((f) => f.endsWith('.json'));
+            for (const file of files) {
+                const fullPath = path.join(sessionDir, file);
+                try {
+                    const stats = fs.statSync(fullPath);
+                    if (stats.size > 0 && stats.mtime.getTime() > bestMtime) {
+                        bestMtime = stats.mtime.getTime();
+                        bestPath = fullPath;
+                    }
+                }
+                catch {
+                    // Skip
+                }
+            }
+        }
+        catch {
+            return null;
+        }
+        if (bestPath) {
+            const sessionId = path.basename(bestPath, '.json');
+            const messageDir = path.join(getStorageDir(), 'message', sessionId);
+            if (fs.existsSync(messageDir)) {
+                try {
+                    const messageFiles = fs.readdirSync(messageDir).filter((f) => f.endsWith('.json'));
+                    for (const mf of messageFiles) {
+                        try {
+                            const mstat = fs.statSync(path.join(messageDir, mf));
+                            if (mstat.mtime.getTime() > bestMtime) {
+                                bestMtime = mstat.mtime.getTime();
+                            }
+                        }
+                        catch {
+                            // Skip
+                        }
+                    }
+                }
+                catch {
+                    // Skip
+                }
+            }
+            return bestPath;
+        }
+        return null;
+    }
+    /** Backward-compatible alias for findAllSessions. */
+    findSessionFiles(workspacePath) {
+        return this.findAllSessions(workspacePath);
+    }
+    findAllSessions(workspacePath) {
+        const db = this.ensureDb();
+        const dbStatus = this.getRuntimeStatus();
+        const projectId = resolveProjectId(workspacePath, db, dbStatus);
+        if (!projectId) {
+            this.recordDatabaseStatus('findAllSessions', dbStatus.kind === 'db_missing');
+            return [];
+        }
+        // DB primary
+        if (db) {
+            const sessions = this.mapDbSessions(projectId);
+            this.recordDatabaseStatus('findAllSessions', true);
+            return sessions;
+        }
+        if (dbStatus.kind !== 'db_missing') {
+            this.recordDatabaseStatus('findAllSessions', dbStatus.available);
+            return [];
+        }
+        // File fallback
+        const sessionDir = path.join(getStorageDir(), 'session', projectId);
+        const sessions = this.findSessionsInDirectoryFromFiles(sessionDir);
+        this.recordDatabaseStatus('findAllSessions', true);
+        return sessions;
+    }
+    findSessionById(workspacePath, sessionId) {
+        const normalizedId = sessionId.trim();
+        if (!normalizedId || path.basename(normalizedId) !== normalizedId)
+            return null;
+        try {
+            const db = this.ensureDb();
+            if (db) {
+                const session = db.getSession(normalizedId);
+                if (session && workspaceMatches(session.directory, workspacePath)) {
+                    const syntheticPath = makeDbSessionPath(getOpenCodeDataDir(), session.project_id, session.id);
+                    this.sessionMetaCache.set(syntheticPath, {
+                        title: session.title,
+                        timeUpdated: session.time_updated,
+                    });
+                    this.recordDatabaseStatus('findSessionById', true);
+                    return syntheticPath;
+                }
+            }
+            const projectId = resolveProjectId(workspacePath, db, this.getRuntimeStatus());
+            if (projectId) {
+                const candidate = path.join(getStorageDir(), 'session', projectId, `${normalizedId}.json`);
+                try {
+                    if (fs.statSync(candidate).isFile()) {
+                        this.recordDatabaseStatus('findSessionById', true);
+                        return candidate;
+                    }
+                }
+                catch {
+                    // Missing legacy session is a normal miss.
+                }
+            }
+            this.recordDatabaseStatus('findSessionById', true);
+            return null;
+        }
+        catch {
+            this.recordDatabaseStatus('findSessionById', false);
+            return null;
+        }
+    }
+    findSessionsInDirectory(dir) {
+        const db = this.ensureDb();
+        const dbStatus = this.getRuntimeStatus();
+        // Check if this is a synthetic DB session directory
+        if (db && dir.includes(path.sep + DB_SESSION_PREFIX + path.sep)) {
+            const projectId = extractProjectIdFromDbPath(dir + path.sep + 'dummy.json');
+            if (projectId) {
+                const sessions = this.mapDbSessions(projectId);
+                this.recordDatabaseStatus('findSessionsInDirectory', true);
+                return sessions;
+            }
+        }
+        // For a DB-backed directory path ending with the project ID,
+        // try to extract project ID from dir name
+        if (db) {
+            const dirName = path.basename(dir);
+            if (db.hasProject(dirName)) {
+                const sessions = this.mapDbSessions(dirName);
+                this.recordDatabaseStatus('findSessionsInDirectory', true);
+                return sessions;
+            }
+        }
+        if (dbStatus.kind !== 'db_missing') {
+            this.recordDatabaseStatus('findSessionsInDirectory', dbStatus.available);
+            return [];
+        }
+        // File fallback
+        const sessions = this.findSessionsInDirectoryFromFiles(dir);
+        this.recordDatabaseStatus('findSessionsInDirectory', true);
+        return sessions;
+    }
+    findSessionsInDirectoryFromFiles(dir) {
+        try {
+            if (!fs.existsSync(dir))
+                return [];
+            return fs
+                .readdirSync(dir)
+                .filter((f) => f.endsWith('.json'))
+                .map((f) => {
+                const fullPath = path.join(dir, f);
+                try {
+                    const stats = fs.statSync(fullPath);
+                    return { path: fullPath, mtime: stats.mtime.getTime(), size: stats.size };
+                }
+                catch {
+                    return null;
+                }
+            })
+                .filter((f) => f !== null && f.size > 0)
+                .sort((a, b) => b.mtime - a.mtime)
+                .map((f) => f.path);
+        }
+        catch {
+            return [];
+        }
+    }
+    listAllSessionFiles() {
+        try {
+            const db = this.ensureDb();
+            if (db) {
+                const dataDir = getOpenCodeDataDir();
+                const files = db.getAllSessions().map((session) => {
+                    const syntheticPath = makeDbSessionPath(dataDir, session.project_id, session.id);
+                    this.sessionMetaCache.set(syntheticPath, {
+                        title: session.title,
+                        timeUpdated: session.time_updated,
+                    });
+                    return {
+                        path: syntheticPath,
+                        mtime: new Date(session.time_updated),
+                        label: session.title ?? undefined,
+                        sizeBytes: 0,
+                        sessionId: session.id,
+                        workspacePath: session.directory,
+                        createdAt: new Date(session.time_created),
+                    };
+                });
+                this.recordDatabaseStatus('listAllSessionFiles', true);
+                return files;
+            }
+            if (this.getRuntimeStatus().kind !== 'db_missing') {
+                this.recordDatabaseStatus('listAllSessionFiles', true);
+                return [];
+            }
+            const root = path.join(getStorageDir(), 'session');
+            const results = [];
+            let projectDirs = [];
+            try {
+                projectDirs = fs.readdirSync(root, { withFileTypes: true });
+            }
+            catch {
+                this.recordDatabaseStatus('listAllSessionFiles', true);
+                return [];
+            }
+            for (const entry of projectDirs) {
+                if (!entry.isDirectory())
+                    continue;
+                for (const sessionPath of this.findSessionsInDirectoryFromFiles(path.join(root, entry.name))) {
+                    try {
+                        const stats = fs.statSync(sessionPath);
+                        results.push({
+                            path: sessionPath,
+                            mtime: stats.mtime,
+                            sizeBytes: stats.size,
+                            sessionId: path.basename(sessionPath, '.json'),
+                        });
+                    }
+                    catch {
+                        // Session vanished between listing and stat.
+                    }
+                }
+            }
+            this.recordDatabaseStatus('listAllSessionFiles', true);
+            return results.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+        }
+        catch {
+            this.recordDatabaseStatus('listAllSessionFiles', false);
+            return [];
+        }
+    }
+    async listSessionFilesAsync(workspacePath) {
+        const db = await this.ensureDbAsync();
+        const sessions = await db.getAllSessionsAsync();
+        this.dbStatus = db.getRuntimeStatus();
+        this.adoptDbIfAvailable(db);
+        if (this.dbStatus.available) {
+            const dataDir = getOpenCodeDataDir();
+            const files = [];
+            for (const session of sessions) {
+                if (workspacePath && !workspaceMatches(session.directory, workspacePath))
+                    continue;
+                const syntheticPath = makeDbSessionPath(dataDir, session.project_id, session.id);
+                this.sessionMetaCache.set(syntheticPath, {
+                    title: session.title,
+                    timeUpdated: session.time_updated,
+                });
+                files.push({
+                    path: syntheticPath,
+                    mtime: new Date(session.time_updated),
+                    label: session.title ?? undefined,
+                    sizeBytes: 0,
+                    sessionId: session.id,
+                    workspacePath: session.directory,
+                    createdAt: new Date(session.time_created),
+                });
+            }
+            this.recordDatabaseStatus('listSessionFilesAsync', true);
+            return files;
+        }
+        const root = path.join(getStorageDir(), 'session');
+        const results = [];
+        let projectDirs = [];
+        try {
+            projectDirs = await fs.promises.readdir(root, { withFileTypes: true });
+        }
+        catch {
+            this.recordDatabaseStatus('listSessionFilesAsync', true);
+            return [];
+        }
+        for (const project of projectDirs) {
+            if (!project.isDirectory())
+                continue;
+            let entries = [];
+            try {
+                entries = await fs.promises.readdir(path.join(root, project.name), {
+                    withFileTypes: true,
+                });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (!entry.isFile() || !entry.name.endsWith('.json'))
+                    continue;
+                const sessionPath = path.join(root, project.name, entry.name);
+                try {
+                    const [stat, raw] = await Promise.all([
+                        fs.promises.stat(sessionPath),
+                        workspacePath ? fs.promises.readFile(sessionPath, 'utf8') : Promise.resolve(null),
+                    ]);
+                    let session = null;
+                    if (raw !== null) {
+                        try {
+                            session = JSON.parse(raw);
+                        }
+                        catch {
+                            continue;
+                        }
+                        const directory = session.directory;
+                        if (directory && !workspaceMatches(directory, workspacePath))
+                            continue;
+                    }
+                    results.push({
+                        path: sessionPath,
+                        mtime: stat.mtime,
+                        sizeBytes: stat.size,
+                        sessionId: path.basename(entry.name, '.json'),
+                        workspacePath: session?.directory,
+                    });
+                }
+                catch {
+                    // Skip inaccessible sessions.
+                }
+                await new Promise((resolve) => setImmediate(resolve));
+            }
+        }
+        this.recordDatabaseStatus('listSessionFilesAsync', true);
+        return results.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+    }
+    getAllProjectFolders(workspacePath) {
+        const db = this.ensureDb();
+        const folders = [];
+        const dbStatus = this.getRuntimeStatus();
+        // DB primary
+        if (db) {
+            const projects = db.getAllProjects();
+            const stats = db.getProjectSessionStats();
+            const statsMap = new Map(stats.map((s) => [s.projectId, s]));
+            let currentProjectId = null;
+            if (workspacePath) {
+                currentProjectId = resolveProjectId(workspacePath, db, dbStatus);
+            }
+            const dataDir = getOpenCodeDataDir();
+            for (const project of projects) {
+                const projStats = statsMap.get(project.id);
+                if (!projStats || projStats.sessionCount === 0)
+                    continue;
+                folders.push({
+                    dir: path.join(dataDir, DB_SESSION_PREFIX, project.id),
+                    name: project.worktree || project.name || project.id,
+                    encodedName: project.id,
+                    sessionCount: projStats.sessionCount,
+                    lastModified: new Date(projStats.maxTimeUpdated),
+                });
+            }
+            // Sort: current project first, then by recency
+            folders.sort((a, b) => {
+                if (currentProjectId) {
+                    const aIsCurrent = a.encodedName === currentProjectId;
+                    const bIsCurrent = b.encodedName === currentProjectId;
+                    if (aIsCurrent && !bIsCurrent)
+                        return -1;
+                    if (!aIsCurrent && bIsCurrent)
+                        return 1;
+                }
+                return b.lastModified.getTime() - a.lastModified.getTime();
+            });
+            if (folders.length > 0) {
+                this.recordDatabaseStatus('getAllProjectFolders', true);
+                return folders;
+            }
+        }
+        if (dbStatus.kind !== 'db_missing') {
+            this.recordDatabaseStatus('getAllProjectFolders', dbStatus.available);
+            return [];
+        }
+        // File fallback
+        const fallback = this.getAllProjectFoldersFromFiles(workspacePath);
+        this.recordDatabaseStatus('getAllProjectFolders', true);
+        return fallback;
+    }
+    getAllProjectFoldersFromFiles(workspacePath) {
+        const folders = [];
+        const sessionBase = path.join(getStorageDir(), 'session');
+        try {
+            if (!fs.existsSync(sessionBase))
+                return [];
+            const projectIds = fs.readdirSync(sessionBase).filter((name) => {
+                try {
+                    return fs.statSync(path.join(sessionBase, name)).isDirectory();
+                }
+                catch {
+                    return false;
+                }
+            });
+            const projectDir = path.join(getStorageDir(), 'project');
+            const projectNames = new Map();
+            if (fs.existsSync(projectDir)) {
+                try {
+                    for (const file of fs.readdirSync(projectDir).filter((f) => f.endsWith('.json'))) {
+                        const proj = readJsonSafe(path.join(projectDir, file));
+                        if (proj) {
+                            projectNames.set(proj.id, proj.path || proj.name || proj.id);
+                        }
+                    }
+                }
+                catch {
+                    // Skip
+                }
+            }
+            let currentProjectId = null;
+            if (workspacePath) {
+                currentProjectId = resolveProjectIdFromFiles(workspacePath);
+            }
+            for (const projectId of projectIds) {
+                const projSessionDir = path.join(sessionBase, projectId);
+                let sessionCount = 0;
+                let lastModified = new Date(0);
+                try {
+                    const sessions = fs.readdirSync(projSessionDir).filter((f) => f.endsWith('.json'));
+                    for (const session of sessions) {
+                        try {
+                            const fstats = fs.statSync(path.join(projSessionDir, session));
+                            if (fstats.size > 0) {
+                                sessionCount++;
+                                if (fstats.mtime > lastModified) {
+                                    lastModified = fstats.mtime;
+                                }
+                            }
+                        }
+                        catch {
+                            // Skip
+                        }
+                    }
+                }
+                catch {
+                    continue;
+                }
+                folders.push({
+                    dir: projSessionDir,
+                    name: projectNames.get(projectId) || projectId,
+                    encodedName: projectId,
+                    sessionCount,
+                    lastModified,
+                });
+            }
+            folders.sort((a, b) => {
+                if (currentProjectId) {
+                    const aIsCurrent = a.encodedName === currentProjectId;
+                    const bIsCurrent = b.encodedName === currentProjectId;
+                    if (aIsCurrent && !bIsCurrent)
+                        return -1;
+                    if (!aIsCurrent && bIsCurrent)
+                        return 1;
+                }
+                return b.lastModified.getTime() - a.lastModified.getTime();
+            });
+        }
+        catch {
+            // Skip
+        }
+        return folders;
+    }
+    // --- File identification ---
+    isSessionFile(filename) {
+        return filename.endsWith('.json');
+    }
+    getSessionId(sessionPath) {
+        return path.basename(sessionPath, '.json');
+    }
+    encodeWorkspacePath(workspacePath) {
+        const db = this.ensureDb();
+        return resolveProjectId(workspacePath, db, this.getRuntimeStatus()) || workspacePath;
+    }
+    /** Session title from the metadata cache or the database; null without either. */
+    extractSessionLabelFromMetadata(sessionPath) {
+        // Check metadata cache first
+        const cached = this.sessionMetaCache.get(sessionPath);
+        if (cached?.title) {
+            return truncateTitle(cached.title);
+        }
+        // DB lookup
+        const db = this.ensureDb();
+        if (db) {
+            const session = db.getSession(this.getSessionId(sessionPath));
+            if (session?.title) {
+                this.recordDatabaseStatus('extractSessionLabel', true);
+                return truncateTitle(session.title);
+            }
+        }
+        return null;
+    }
+    extractSessionLabel(sessionPath) {
+        const fromMetadata = this.extractSessionLabelFromMetadata(sessionPath);
+        if (fromMetadata)
+            return fromMetadata;
+        // File fallback
+        const sessionId = this.getSessionId(sessionPath);
+        const label = this.extractSessionLabelFromFiles(sessionPath, sessionId);
+        this.recordDatabaseStatus('extractSessionLabel', label !== null || !isDbSessionPath(sessionPath));
+        return label;
+    }
+    async extractSessionLabelsAsync(sessionPaths) {
+        const results = new Map();
+        const unresolved = [];
+        for (const sessionPath of sessionPaths) {
+            const cached = this.sessionMetaCache.get(sessionPath);
+            if (cached)
+                results.set(sessionPath, cached.title ? truncateTitle(cached.title) : null);
+            else
+                unresolved.push(sessionPath);
+        }
+        if (unresolved.length > 0 && (!this.dbInitialized || this.dbStatus.available)) {
+            const db = await this.ensureDbAsync();
+            const byId = new Map(unresolved.map((item) => [this.getSessionId(item), item]));
+            const sessions = await db.getSessionsByIdsAsync([...byId.keys()]);
+            this.dbStatus = db.getRuntimeStatus();
+            this.adoptDbIfAvailable(db);
+            for (const session of sessions) {
+                const sessionPath = byId.get(session.id);
+                if (!sessionPath)
+                    continue;
+                this.sessionMetaCache.set(sessionPath, {
+                    title: session.title,
+                    timeUpdated: session.time_updated,
+                });
+                results.set(sessionPath, session.title ? truncateTitle(session.title) : null);
+            }
+        }
+        for (const sessionPath of unresolved) {
+            if (results.has(sessionPath))
+                continue;
+            if (isDbSessionPath(sessionPath)) {
+                results.set(sessionPath, null);
+                continue;
+            }
+            try {
+                const session = JSON.parse(await fs.promises.readFile(sessionPath, 'utf8'));
+                results.set(sessionPath, session.title ? truncateTitle(session.title) : null);
+            }
+            catch {
+                results.set(sessionPath, null);
+            }
+            await new Promise((resolve) => setImmediate(resolve));
+        }
+        this.recordDatabaseStatus('extractSessionLabelsAsync', true);
+        return results;
+    }
+    extractSessionLabelFromFiles(sessionPath, sessionId) {
+        if (isDbSessionPath(sessionPath))
+            return null;
+        const session = readJsonSafe(sessionPath);
+        if (session?.title) {
+            return truncateTitle(session.title);
+        }
+        const messageDir = path.join(getStorageDir(), 'message', sessionId);
+        if (!fs.existsSync(messageDir))
+            return null;
+        try {
+            const files = fs
+                .readdirSync(messageDir)
+                .filter((f) => f.endsWith('.json'))
+                .slice(0, 5);
+            for (const file of files) {
+                const msg = readJsonSafe(path.join(messageDir, file));
+                if (msg?.role === 'user') {
+                    const partDir = path.join(getStorageDir(), 'part', msg.id);
+                    if (fs.existsSync(partDir)) {
+                        const partFiles = fs.readdirSync(partDir).filter((f) => f.endsWith('.json'));
+                        for (const pf of partFiles) {
+                            const part = readJsonSafe(path.join(partDir, pf));
+                            if (part?.type === 'text' && part.text.trim().length > 0) {
+                                let text = part.text.trim().replace(/\s+/g, ' ');
+                                if (text.length > 60) {
+                                    text = text.substring(0, 57) + '...';
+                                }
+                                return text;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Skip
+        }
+        return null;
+    }
+    // --- Data reading ---
+    createReader(sessionPath) {
+        const db = this.ensureDb();
+        const sessionId = this.getSessionId(sessionPath);
+        // Use DB reader if available and session exists in DB
+        if (db) {
+            const session = db.getSession(sessionId);
+            if (session) {
+                return new OpenCodeDbReader(sessionId, db);
+            }
+        }
+        // File fallback
+        return new OpenCodeFileReader(sessionId);
+    }
+    // --- Subagent support ---
+    scanSubagents(_sessionDir, sessionId) {
+        const db = this.ensureDb();
+        if (!db)
+            return [];
+        try {
+            // Get subtask parts from the parent session for metadata
+            const parts = db.getPartsForSession(sessionId);
+            const subtaskParts = [];
+            for (const partRow of parts) {
+                try {
+                    const data = JSON.parse(partRow.data);
+                    if (data.type !== 'subtask')
+                        continue;
+                    subtaskParts.push({
+                        id: partRow.id,
+                        agent: data.agent || undefined,
+                        description: data.description || undefined,
+                        timeCreated: partRow.time_created,
+                    });
+                }
+                catch {
+                    // Skip malformed part data
+                }
+            }
+            // Query child sessions for real metrics
+            const childSessions = db.getChildSessions(sessionId);
+            // Build a lookup from child session index to subtask part metadata.
+            // Child sessions are ordered by time_created; subtask parts likewise.
+            // Match them positionally when counts align, otherwise fall back to
+            // child session data only.
+            const results = [];
+            if (childSessions.length > 0) {
+                for (let i = 0; i < childSessions.length; i++) {
+                    const child = childSessions[i];
+                    const subtask = i < subtaskParts.length ? subtaskParts[i] : undefined;
+                    // Aggregate tokens from child session messages
+                    const childMessages = db.getMessagesForSession(child.id);
+                    const tokenTotals = {
+                        agentId: '',
+                        toolCalls: [],
+                        inputTokens: 0,
+                        outputTokens: 0,
+                    };
+                    for (const msgRow of childMessages) {
+                        try {
+                            const msgData = JSON.parse(msgRow.data);
+                            const tokens = msgData.tokens;
+                            if (tokens) {
+                                // Same semantics as the main-session parser (openCodeParser).
+                                const cache = tokens.cache;
+                                const providerID = msgData.providerID;
+                                addUsageToSubagent(tokenTotals, normalizeProviderUsage({
+                                    semantics: providerID === 'openai'
+                                        ? 'openai'
+                                        : providerID === 'anthropic'
+                                            ? 'anthropic'
+                                            : 'sidekick',
+                                    provider: providerID ?? 'opencode',
+                                    inputTokens: tokens.input,
+                                    outputTokens: tokens.output,
+                                    cacheReadTokens: cache?.read,
+                                    cacheWriteTokens: cache?.write,
+                                    reasoningTokens: tokens.reasoning,
+                                    reasoningIncludedInOutput: providerID === 'openai',
+                                }));
+                            }
+                        }
+                        catch {
+                            // Skip malformed messages
+                        }
+                    }
+                    const { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, reasoningTokens, totalTokens, } = tokenTotals;
+                    // Extract tool calls from child session parts
+                    const childParts = db.getPartsForSession(child.id);
+                    const toolCalls = [];
+                    for (const childPart of childParts) {
+                        try {
+                            const partData = JSON.parse(childPart.data);
+                            if (partData.type !== 'tool' && partData.type !== 'tool-invocation')
+                                continue;
+                            const state = partData.state;
+                            let duration;
+                            const timeInfo = state?.time;
+                            if (timeInfo?.start && timeInfo?.end) {
+                                const startMs = typeof timeInfo.start === 'number'
+                                    ? timeInfo.start
+                                    : new Date(timeInfo.start).getTime();
+                                const endMs = typeof timeInfo.end === 'number'
+                                    ? timeInfo.end
+                                    : new Date(timeInfo.end).getTime();
+                                if (endMs > startMs)
+                                    duration = endMs - startMs;
+                            }
+                            toolCalls.push({
+                                name: normalizeToolName(partData.tool || ''),
+                                input: normalizeToolInput(state?.input || {}),
+                                timestamp: new Date(childPart.time_created),
+                                duration,
+                                isError: state?.status === 'error',
+                            });
+                        }
+                        catch {
+                            // Skip malformed parts
+                        }
+                    }
+                    // Calculate duration from first/last message timestamps
+                    let startTime;
+                    let endTime;
+                    let durationMs;
+                    if (childMessages.length > 0) {
+                        startTime = new Date(childMessages[0].time_created);
+                        endTime = new Date(childMessages[childMessages.length - 1].time_created);
+                        durationMs = endTime.getTime() - startTime.getTime();
+                    }
+                    else {
+                        startTime = new Date(child.time_created);
+                    }
+                    const rawAgentType = subtask?.agent || child.title || undefined;
+                    const description = subtask?.description || child.title || undefined;
+                    results.push({
+                        agentId: subtask?.id || child.id,
+                        agentType: normalizeAgentType(rawAgentType, description),
+                        description,
+                        toolCalls,
+                        inputTokens,
+                        outputTokens,
+                        cacheReadTokens,
+                        cacheWriteTokens,
+                        reasoningTokens,
+                        totalTokens,
+                        startTime,
+                        endTime,
+                        durationMs,
+                    });
+                }
+            }
+            else {
+                // Fallback: no child sessions found, return stubs from subtask parts
+                for (const sp of subtaskParts) {
+                    results.push({
+                        agentId: sp.id,
+                        agentType: normalizeAgentType(sp.agent, sp.description),
+                        description: sp.description,
+                        toolCalls: [],
+                        inputTokens: 0,
+                        outputTokens: 0,
+                        startTime: new Date(sp.timeCreated),
+                    });
+                }
+            }
+            return results;
+        }
+        catch {
+            return [];
+        }
+    }
+    // --- Cross-session search ---
+    searchInSession(sessionPath, query, maxResults) {
+        const db = this.ensureDb();
+        const sessionId = this.getSessionId(sessionPath);
+        const queryLower = query.toLowerCase();
+        // DB primary
+        if (db) {
+            const dbSession = db.getSession(sessionId);
+            if (dbSession) {
+                return this.searchInSessionFromDb(db, sessionId, sessionPath, dbSession.project_id, queryLower, query, maxResults);
+            }
+        }
+        // File fallback
+        return this.searchInSessionFromFiles(sessionPath, sessionId, queryLower, query, maxResults);
+    }
+    searchInSessionFromDb(db, sessionId, sessionPath, projectId, queryLower, query, maxResults) {
+        const results = [];
+        try {
+            const parts = db.getPartsForSession(sessionId);
+            const messages = db.getMessagesForSession(sessionId);
+            const messageMap = new Map(messages.map((m) => [m.id, m]));
+            for (const partRow of parts) {
+                if (results.length >= maxResults)
+                    break;
+                const dataStr = partRow.data;
+                const dataLower = dataStr.toLowerCase();
+                const matchIdx = dataLower.indexOf(queryLower);
+                if (matchIdx < 0)
+                    continue;
+                // Extract a snippet from the raw data
+                const start = Math.max(0, matchIdx - 40);
+                const end = Math.min(dataStr.length, matchIdx + query.length + 40);
+                const snippet = (start > 0 ? '...' : '') +
+                    dataStr.substring(start, end) +
+                    (end < dataStr.length ? '...' : '');
+                const msgRow = messageMap.get(partRow.message_id);
+                const msgData = msgRow ? JSON.parse(msgRow.data) : {};
+                results.push({
+                    sessionPath,
+                    line: snippet.replace(/\n/g, ' '),
+                    eventType: msgData.role || 'unknown',
+                    timestamp: String(partRow.time_created),
+                    projectPath: projectId,
+                });
+            }
+        }
+        catch {
+            // Skip
+        }
+        return results;
+    }
+    searchInSessionFromFiles(sessionPath, sessionId, queryLower, query, maxResults) {
+        const results = [];
+        const messageDir = path.join(getStorageDir(), 'message', sessionId);
+        if (!fs.existsSync(messageDir))
+            return results;
+        try {
+            const session = readJsonSafe(sessionPath);
+            const projectPath = session?.projectID || sessionId;
+            const messageFiles = fs.readdirSync(messageDir).filter((f) => f.endsWith('.json'));
+            for (const file of messageFiles) {
+                if (results.length >= maxResults)
+                    break;
+                const msg = readJsonSafe(path.join(messageDir, file));
+                if (!msg)
+                    continue;
+                const partDir = path.join(getStorageDir(), 'part', msg.id);
+                if (!fs.existsSync(partDir))
+                    continue;
+                try {
+                    const partFiles = fs.readdirSync(partDir).filter((f) => f.endsWith('.json'));
+                    for (const pf of partFiles) {
+                        if (results.length >= maxResults)
+                            break;
+                        const part = readJsonSafe(path.join(partDir, pf));
+                        if (!part)
+                            continue;
+                        let text = '';
+                        if (part.type === 'text')
+                            text = part.text;
+                        else if (part.type === 'reasoning')
+                            text = part.text;
+                        else if (part.type === 'tool-invocation' && part.state.output)
+                            text = part.state.output;
+                        else if (part.type === 'tool' && part.state.output)
+                            text = part.state.output;
+                        if (!text)
+                            continue;
+                        const textLower = text.toLowerCase();
+                        const matchIdx = textLower.indexOf(queryLower);
+                        if (matchIdx < 0)
+                            continue;
+                        const start = Math.max(0, matchIdx - 40);
+                        const end = Math.min(text.length, matchIdx + query.length + 40);
+                        const snippet = (start > 0 ? '...' : '') +
+                            text.substring(start, end) +
+                            (end < text.length ? '...' : '');
+                        results.push({
+                            sessionPath,
+                            line: snippet.replace(/\n/g, ' '),
+                            eventType: msg.role,
+                            timestamp: String(msg.time.created),
+                            projectPath,
+                        });
+                    }
+                }
+                catch {
+                    // Skip
+                }
+            }
+        }
+        catch {
+            // Skip
+        }
+        return results;
+    }
+    getProjectsBaseDir() {
+        return path.join(getStorageDir(), 'session');
+    }
+    getWatchRoots() {
+        return [getOpenCodeDataDir(), this.getProjectsBaseDir()];
+    }
+    // --- Stats ---
+    readSessionStats(sessionPath) {
+        // One reader pass (database-backed or file-backed) feeds the shared
+        // aggregator, so compaction and truncation counts are real instead of the
+        // hardcoded zeros the direct SQLite read returned, and a session that
+        // cannot be read reports `availability: 'unavailable'` instead of zeros.
+        return readSessionFileStats(this, sessionPath, {
+            resolveLabel: () => this.extractSessionLabelFromMetadata(sessionPath),
+        });
+    }
+    readSessionContextSnapshot(sessionPath, options = {}) {
+        return readSessionContextSnapshot(this, sessionPath, options);
+    }
+    // --- Optional methods ---
+    getSessionMetadata(sessionPath) {
+        // Check cache first
+        const cached = this.sessionMetaCache.get(sessionPath);
+        if (cached) {
+            return { mtime: new Date(cached.timeUpdated) };
+        }
+        // DB lookup
+        const db = this.ensureDb();
+        if (db) {
+            const sessionId = this.getSessionId(sessionPath);
+            const session = db.getSession(sessionId);
+            if (session) {
+                this.sessionMetaCache.set(sessionPath, {
+                    title: session.title,
+                    timeUpdated: session.time_updated,
+                });
+                return { mtime: new Date(session.time_updated) };
+            }
+        }
+        // Try filesystem for non-DB paths
+        if (!isDbSessionPath(sessionPath)) {
+            try {
+                const stats = fs.statSync(sessionPath);
+                return { mtime: stats.mtime };
+            }
+            catch {
+                // File doesn't exist
+            }
+        }
+        return null;
+    }
+    async getSessionMetadataAsync(sessionPath) {
+        if (!isDbSessionPath(sessionPath)) {
+            try {
+                return { mtime: (await fs.promises.stat(sessionPath)).mtime };
+            }
+            catch {
+                return null;
+            }
+        }
+        const cached = this.sessionMetaCache.get(sessionPath);
+        try {
+            const db = await this.ensureDbAsync();
+            const sessionId = this.getSessionId(sessionPath);
+            const session = (await db.getSessionsByIdsAsync([sessionId]))[0];
+            this.dbStatus = db.getRuntimeStatus();
+            this.adoptDbIfAvailable(db);
+            if (session) {
+                this.sessionMetaCache.set(sessionPath, {
+                    title: session.title,
+                    timeUpdated: session.time_updated,
+                });
+                this.recordDatabaseStatus('getSessionMetadataAsync', true);
+                return { mtime: new Date(session.time_updated) };
+            }
+            this.recordDatabaseStatus('getSessionMetadataAsync', cached !== undefined);
+        }
+        catch {
+            this.recordDatabaseStatus('getSessionMetadataAsync', cached !== undefined);
+        }
+        return cached ? { mtime: new Date(cached.timeUpdated) } : null;
+    }
+    /**
+     * Returns the latest assistant message's token snapshot for context window sizing.
+     * Cumulative session totals are derived from readNew() events processed by SessionMonitor.
+     */
+    getCurrentUsageSnapshot(sessionPath) {
+        const db = this.ensureDb();
+        if (!db)
+            return null;
+        const sessionId = this.getSessionId(sessionPath);
+        const snapshot = db.getLatestAssistantContextUsage(sessionId);
+        if (!snapshot)
+            return null;
+        return {
+            inputTokens: Number(snapshot.inputTokens) || 0,
+            outputTokens: Number(snapshot.outputTokens) || 0,
+            cacheWriteTokens: Number(snapshot.cacheWriteTokens) || 0,
+            cacheReadTokens: Number(snapshot.cacheReadTokens) || 0,
+            reasoningTokens: Number(snapshot.reasoningTokens) || 0,
+            model: snapshot.modelId || 'unknown',
+            timestamp: new Date(Number(snapshot.timeCreated) || Date.now()),
+        };
+    }
+    computeContextSize(usage) {
+        // Context = input tokens + cache tokens. Output and reasoning tokens
+        // are the model's response, not part of the context window.
+        return usage.inputTokens + usage.cacheWriteTokens + usage.cacheReadTokens;
+    }
+    getContextAttribution(sessionPath) {
+        const db = this.ensureDb();
+        if (!db)
+            return null;
+        const sessionId = this.getSessionId(sessionPath);
+        try {
+            const messages = db.getMessagesForSession(sessionId);
+            if (messages.length === 0)
+                return null;
+            const attribution = {
+                systemPrompt: 0,
+                userMessages: 0,
+                assistantResponses: 0,
+                toolInputs: 0,
+                toolOutputs: 0,
+                thinking: 0,
+                other: 0,
+            };
+            // Accumulate input tokens by role. OpenCode messages store actual
+            // token counts from the provider, so this is more accurate than
+            // heuristic content estimation.
+            for (const row of messages) {
+                try {
+                    const data = JSON.parse(row.data);
+                    const role = data.role;
+                    const msgTokens = data.tokens;
+                    const cache = msgTokens?.cache;
+                    // Context contribution = input + cacheWrite + cacheRead
+                    const input = msgTokens?.input || 0;
+                    const cacheRead = cache?.read || 0;
+                    const cacheWrite = cache?.write || 0;
+                    const reasoning = msgTokens?.reasoning || 0;
+                    const contextTokens = input + cacheRead + cacheWrite;
+                    if (contextTokens === 0)
+                        continue;
+                    if (role === 'user') {
+                        // User messages include prompts and tool results;
+                        // we can't distinguish without parsing parts, so attribute
+                        // to userMessages (tool outputs arrive as separate assistant
+                        // messages in OpenCode's model)
+                        attribution.userMessages += contextTokens;
+                    }
+                    else if (role === 'assistant') {
+                        // Attribute reasoning separately when available
+                        if (reasoning > 0) {
+                            attribution.thinking += reasoning;
+                            attribution.assistantResponses += contextTokens - reasoning;
+                        }
+                        else {
+                            attribution.assistantResponses += contextTokens;
+                        }
+                    }
+                    else if (role === 'system') {
+                        attribution.systemPrompt += contextTokens;
+                    }
+                    else {
+                        attribution.other += contextTokens;
+                    }
+                }
+                catch {
+                    // Skip malformed message data
+                }
+            }
+            // Refine user attribution: scan parts to separate tool outputs
+            // from user prompts for more accurate breakdown
+            const parts = db.getPartsForSession(sessionId);
+            let toolPartCount = 0;
+            let userTextPartCount = 0;
+            for (const partRow of parts) {
+                try {
+                    const partData = JSON.parse(partRow.data);
+                    const partType = partData.type;
+                    if (partType === 'tool' || partType === 'tool-invocation') {
+                        toolPartCount++;
+                    }
+                    else if (partType === 'text') {
+                        userTextPartCount++;
+                    }
+                }
+                catch {
+                    // Skip
+                }
+            }
+            // If there are tool parts, redistribute user token attribution
+            // between userMessages and toolOutputs proportionally
+            const totalParts = toolPartCount + userTextPartCount;
+            if (totalParts > 0 && toolPartCount > 0 && attribution.userMessages > 0) {
+                const toolProportion = toolPartCount / totalParts;
+                const toolTokens = Math.round(attribution.userMessages * toolProportion);
+                attribution.toolOutputs += toolTokens;
+                attribution.userMessages -= toolTokens;
+            }
+            const total = attribution.systemPrompt +
+                attribution.userMessages +
+                attribution.assistantResponses +
+                attribution.toolInputs +
+                attribution.toolOutputs +
+                attribution.thinking +
+                attribution.other;
+            return total > 0 ? attribution : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    getContextWindowLimit(modelId) {
+        if (this.dynamicContextWindowLimit)
+            return this.dynamicContextWindowLimit;
+        return getModelContextWindowSize(modelId);
+    }
+    /** Set a runtime-reported context window limit (overrides static map). */
+    setDynamicContextWindowLimit(limit) {
+        this.dynamicContextWindowLimit = limit;
+    }
+    // --- Lifecycle ---
+    dispose() {
+        this.db?.close();
+        this.db = null;
+        this.dbInitialized = false;
+        this.dbStatus = { available: false, kind: 'db_missing' };
+        this.sessionMetaCache.clear();
+        this.dynamicContextWindowLimit = null;
+    }
+    recordDatabaseStatus(operation, usable) {
+        const status = this.db?.getRuntimeStatus() ?? this.dbStatus;
+        const diagnostic = diagnosticFromRuntimeStatus(this.id, 'query', status);
+        if (!diagnostic || status.kind === 'db_missing') {
+            // A genuinely absent OpenCode DB is expected for legacy file storage.
+            this.diagnostics.available(operation);
+            return;
+        }
+        this.diagnostics.degraded(operation, status, {
+            kind: diagnostic.kind,
+            severity: diagnostic.severity,
+            phase: diagnostic.phase,
+            message: diagnostic.message,
+        }, usable);
+    }
+    // --- z.ai (GLM Coding Plan) compatibility quota derivation ---
+    /**
+     * Derives a z.ai coding-plan `QuotaState` from OpenCode assistant turns
+     * tagged with `providerID ∈ {zai, zai-coding-plan}`.
+     *
+     * This compatibility estimator predates the authoritative z.ai quota API.
+     * New product code should use `zaiQuotaApi.ts`; this method remains for
+     * consumers that still want a local OpenCode DB-derived estimate. Returns
+     * null when no z.ai routing is detected.
+     *
+     * @param tier  Plan tier; `'auto'` infers from observed weekly volume.
+     *              When the caller has no opinion, the heuristic falls back to
+     *              `'max'` (conservative — small overcount rather than large).
+     */
+    getZaiQuotaState(tier = 'auto') {
+        const db = this.ensureDb();
+        if (!db)
+            return null;
+        const sinceMs = Date.now() - 7 * 86_400_000;
+        let rawRows = [];
+        try {
+            rawRows = db.getAssistantMessagesByProviderId([...ZAI_PROVIDER_IDS], sinceMs);
+        }
+        catch {
+            return null;
+        }
+        if (rawRows.length === 0)
+            return null;
+        const turns = rawRows.map((row) => ({
+            timestampMs: row.timeCreated,
+            model: row.modelId,
+            inputTokens: row.inputTokens || 0,
+            outputTokens: row.outputTokens || 0,
+            cacheReadTokens: row.cacheReadTokens || 0,
+            cacheWriteTokens: row.cacheWriteTokens || 0,
+            reasoningTokens: row.reasoningTokens || 0,
+        }));
+        const accumulated = accumulateZaiUsage(turns, Date.now());
+        // Default to 'max' on auto when usage is non-zero — overestimating the
+        // tier gives a lower (safer) utilization % until calibration runs.
+        const resolvedTier = tier === 'auto' ? (accumulated.weeklyTurns > 0 ? 'max' : 'lite') : tier;
+        // Walk rows again to trap any captured z.ai business errors.
+        let authoritativeFiveHourResetAt;
+        let authoritativeWeeklyResetAt;
+        for (const row of rawRows) {
+            if (row.errorCode == null && !row.errorMessage)
+                continue;
+            const parsed = parseZaiQuotaError({
+                code: row.errorCode ?? undefined,
+                message: row.errorMessage ?? undefined,
+            });
+            if (!parsed?.resetsAt)
+                continue;
+            if (parsed.kind === 'exhausted') {
+                authoritativeFiveHourResetAt = parsed.resetsAt;
+                if (String(parsed.code) === '1310')
+                    authoritativeWeeklyResetAt = parsed.resetsAt;
+            }
+        }
+        return inferZaiQuotaState(accumulated, resolvedTier, {
+            authoritativeFiveHourResetAt,
+            authoritativeWeeklyResetAt,
+        });
+    }
+    /**
+     * Cheap boolean: does the local OpenCode install currently route at z.ai?
+     * Used by callers to decide whether to render a z.ai quota surface.
+     */
+    isZaiRoutingActive() {
+        const db = this.ensureDb();
+        if (!db)
+            return false;
+        try {
+            const rows = db.getAssistantMessagesByProviderId([...ZAI_PROVIDER_IDS], Date.now() - 7 * 86_400_000);
+            return rows.length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+}