sidekick-shared 0.26.1 → 0.26.2

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to sidekick-shared will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.26.2] - 2026-09-06
+
+### Added
+
+- `DoctorOptions.provider` selects the session provider to diagnose; `HealthReport.sessionProvider` records it.
+- Optional watcher `onBatchComplete` callback for persisting state after all events in a read have been delivered.
+- `SessionSearchOptions.projectPath` and `signal` for provider-aware workspace filtering and cancellation; legacy `projectSlug` remains supported.
+
+### Fixed
+
+- JSONL watcher and provider reader checkpoints end at complete lines, retaining partial UTF-8 characters across reads and restarts. Codex restores parser context when seeking.
+- Watcher failures retain polling fallback; OpenCode watchers share the canonical data-directory resolver.
+- Session search enumerates through providers, includes database-only sessions, and deduplicates paths.
+- Doctor checks the selected session provider, treats unrelated integrations as informational, and reads account status without changing account selection.
+
 ## [0.26.1] - 2026-09-05
 
 ### Fixed

package/README.md

@@ -9,6 +9,7 @@ Types, parsers, providers, readers, formatters, aggregation, search, reporting,
 
 ## Recent additions
 
+- **0.26.2: reliable monitoring and search** — complete-line JSONL cursors preserve Unicode and Codex parser context; watcher `onBatchComplete` signals a delivered batch. `searchSessions()` adds workspace-path filtering and cancellation, and Doctor accepts an explicit session provider.
 - **One token vocabulary and cost provenance (0.26.0)** — `summarizeTokens()` gives every surface the same `total` (input + output + cache writes + cache reads) and `context` (input + cache) figures; `AggregatedTokens.costUsd` carries `costProvenance` so reports can say whether a cost was provider-reported or estimated; `parseClaudeStatuslinePayload()` / `quotaFromStatuslinePayload()` turn Claude Code's status-line JSON into an official `statusline` quota source; `readQuotaSnapshot()` reports `ageMs` / `freshness` and keeps the sample's origin as `capturedSource`; `resolveQuota()` shares quota resolution across CLI, MCP, and dashboard startup, with default local-sample preferences and an API-first option used by one-shot Codex queries; `readSessionFileStats()` / `computeSessionFileStats()` give every provider one `readSessionStats()` over the shared aggregator, with `availability`, `costProvenance`, and `toolFailures` on `SessionFileStats`; `collectUsageEvents()` reads priced usage events from session logs with a per-session cache, `computeBillingBlocks()` groups them into five-hour billing blocks, and `bucketUsage()` turns them into day, week, month, or session rows; `applySessionSummary()` and `importSessionHistory()` let any host fold finished sessions into `historical-data.json` the way the extension does; observed sessions are read once per discovery, re-read only when their fingerprint changes, and classified from events by `classifySessionActivity()`; `readSessionReportInputs()` derives report metrics and transcript from one read; `writeStateFile()` / `readStateFile()` (also on the `statusline` subpath) maintain the public, versioned `state.json` for external tools, validated by `sidekickStateFileSchema`; `getScheduledPeakHoursState()` and `evaluateQuotaThresholds()` are shared by the CLI and extension dashboards.
 - **Host-safe APIs (0.25.0)** — `listSessionPreviewsAsync()` / `readSessionPreviewAsync()` read previews with bounded concurrency and cooperative yielding; `ObservedSessionCollector.subscribe()` and `SessionMonitor.subscribe()` replace host polling loops with debounced change batches; `createSessionProviders({ onDiagnostic })` constructs every usable provider with structured diagnostics instead of throwing; `findSessionById()` resolves one session without scanning; `exportResolvedModelCatalog()` / `importResolvedModelCatalog()` and `registerModelAlias()` transfer context/pricing resolutions across realms; `onAccountsChanged()` reports login/logout/switch events; provider constructors perform no environment I/O, and quota pollers stay dormant without an account.
 - **Native session-file helpers** — `encodeClaudeWorkspacePath()` / `getClaudeSessionDirectory()` locate Claude Code's `~/.claude/projects/` directories with the real on-disk encoding, `findCodexRolloutFile()` resolves a Codex session id to its rollout path, `readCodexHistory()` tail-reads `~/.codex/history.jsonl`, `listSessionPreviews()` / `readSessionPreview()` build a cheap stat-first recent-sessions index across providers, and `parseMcpToolName()` splits `mcp__<server>__<tool>` identifiers (browser-safe).
@@ -104,7 +105,7 @@ returns the platform default that both overrides bypass.
 | **Credentials**                 | Claude Max OAuth credential reading from `~/.claude/.credentials.json`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | **Quota**                       | Claude Max subscription quota fetching (5-hour and 7-day windows), Codex rate-limit extraction from event streams (plus Codex reset credits via `fetchCodexResetCreditsFromApi()`, attached to quota state by `fetchCodexQuotaFromApi()`), and authoritative z.ai Coding Plan quota fetching via `resolveZaiQuota()` / `fetchZaiQuotaFromApi()` (reads z.ai's `api/monitor/usage/quota/limit` endpoint with cached-snapshot fallback). The observed-traffic z.ai estimator was removed from the package root exports in 0.23.0 and every remaining export of it is `@deprecated` — `resolveZaiQuota()` is the single supported z.ai quota API                                                                                                                                                                                                                                                                                                                                    |
 | **Provider Status**             | API health checking via status.claude.com and status.openai.com (indicator, components, incidents)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| **Doctor**                      | Typed cross-provider health diagnostics — `runDoctor()` checks project identity, sessions, accounts, providers, and dependencies into a `HealthReport`; `formatHealthReport()` renders it and `getSessionDiagnostics()` exposes the per-provider session probe                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| **Doctor**                      | Typed cross-provider health diagnostics — `runDoctor()` checks project identity, sessions, accounts, providers, and dependencies into a `HealthReport`; `formatHealthReport()` renders it and `getSessionDiagnostics()` retains the legacy Claude Code path probe; `runDoctor({ provider })` diagnoses the selected session provider                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | **Schemas**                     | Zod schemas for runtime validation of data crossing process/IPC boundaries — JSONL session events (`sessionEventSchema`, `messageUsageSchema`, `sessionMessageSchema`), assistant turns, observed-session V1 records, quota, account status, account management, quota history, and the public `state.json` contract (`sidekickStateFileSchema`) — plus `extractSessionEvents()` to unwrap `progress`-wrapped events. Account and quota APIs guarantee results valid against the same-release schemas. Also published fs-free via the [`sidekick-shared/schemas`](#supported-import-paths) subpath                                                                                                                                                                                                                                                                                                                                                                               |
 | **Extractors**                  | Pure functions for single-event processing: `extractTokenUsage()`, `extractToolCall()` (top-level `tool_use`), `extractToolCalls()` (assistant content blocks), plus Node-only session asset extraction (`gatherAssetsForCwd()`, `readClaudeAssets()`, `readCodexAssets()`) for URLs, file paths, commands, and plans                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | **Model Info & Pricing**        | Model family parsing (Anthropic / OpenAI / Google, including legacy `claude-3-opus-…` and `claude-3-5-sonnet-…` IDs), context-window lookup (including Fable 5 / Opus 4.8 / Opus 4.7 / Sonnet 4.7 1M and GPT-5.x variants), pricing tables with optional LiteLLM hydration, normalized non-double-counting cost (`calculateNormalizedUsageCost()`, fed by `normalizeProviderUsage()` / `extractNormalizedUsage()`), legacy cost helpers retained but deprecated (`calculateCost()`, `calculateCostWithProvenance()`), `mergeCostSources()`, display helpers (`shortModelName()`, `getModelDisplayInfo()`, `compareModelIds()`, `sortModelIds()`, `formatCost()`), and cross-realm catalog transfer — `exportResolvedModelCatalog()` / `importResolvedModelCatalog()` move resolved context windows and pricing (with provenance, prefix inheritance explicit) between Node and browser realms, and `registerModelAlias()` resolves short or host-specific names to canonical ids |
@@ -670,6 +671,26 @@ const tail = createJsonlTail({
 tail.start();
 ```
 
+`SessionWatcherCallbacks.onBatchComplete` is also available through `createWatcher()`. Save aggregation state only after a complete event batch and only when the state includes the full history (a completed replay or a compatible restored checkpoint). Live-only state is incomplete and must not replace a full-history checkpoint. JSONL positions end at complete lines; Codex readers reconstruct parser context when seeking. OpenCode's SQLite timestamp cursor does not persist row-version deduplication, so the dashboards replay OpenCode history instead of restoring a snapshot.
+
+### Search a workspace and diagnose its provider
+
+```typescript
+import { CodexProvider, searchSessions, runDoctor } from 'sidekick-shared';
+
+const provider = new CodexProvider();
+const controller = new AbortController();
+const matches = await searchSessions(provider, 'authentication', {
+  projectPath: '/path/to/project',
+  signal: controller.signal,
+  maxResults: 20,
+});
+const report = await runDoctor({ cwd: '/path/to/project', provider: 'codex' });
+console.log(matches, report.sessionProvider, report.checks);
+```
+
+`projectPath` resolves the workspace canonically and takes precedence over the legacy `projectSlug`. Cancellation is checked between session reads; it does not interrupt an in-progress synchronous provider read. `HealthReport.sessionProvider` is optional for compatibility. `getSessionDiagnostics()` remains a Claude Code path diagnostic; use `runDoctor()` for provider-aware checks.
+
 ### Poll quota with backoff
 
 ```typescript

package/dist/doctor.d.ts

@@ -1,6 +1,7 @@
 import { type ActiveAccountStatus } from './accountStatus';
 import { type ProjectIdentity } from './paths';
 import { type ProviderStatusState } from './providerStatus';
+import type { ProviderId } from './providers/types';
 import { type OpenCodeDbRuntimeStatus } from './providers/openCodeDatabase';
 export type HealthCheckStatus = 'ok' | 'warning' | 'error' | 'info';
 export interface HealthCheck {
@@ -38,10 +39,14 @@ export interface HealthReport {
         claude: ProviderStatusState;
         openai: ProviderStatusState;
     };
+    /** Legacy Claude Code path diagnostics, retained for compatibility. */
     sessions: SessionDiagnostics;
+    sessionProvider?: ProviderId;
 }
 export interface DoctorOptions {
     cwd?: string;
+    /** Session provider to diagnose; defaults to auto-detection. */
+    provider?: ProviderId | 'auto';
     deprecatedSettings?: DeprecatedSetting[];
     openCodeStatus?: OpenCodeDbRuntimeStatus;
     fetchStatuses?: () => Promise<{

package/dist/doctor.js

@@ -44,6 +44,8 @@ const paths_1 = require("./paths");
 const sessionPathResolver_1 = require("./parsers/sessionPathResolver");
 const providerStatus_1 = require("./providerStatus");
 const openCode_1 = require("./providers/openCode");
+const factory_1 = require("./providers/factory");
+const detect_1 = require("./providers/detect");
 const openCodeDatabase_1 = require("./providers/openCodeDatabase");
 /** Collects the Claude Code path-resolution detail used by both host surfaces. */
 function getSessionDiagnostics(workspacePath) {
@@ -100,15 +102,66 @@ function statusUnavailable() {
         updatedAt: new Date().toISOString(),
     };
 }
+async function checkSessionProvider(providerId, workspacePath) {
+    const { providers } = (0, factory_1.createSessionProviders)({ providerIds: [providerId] });
+    const provider = providers[0];
+    const title = `Session discovery (${provider?.displayName ?? providerId})`;
+    try {
+        if (!provider)
+            throw new Error(`${providerId} could not be initialized.`);
+        const sessions = provider.listSessionFilesAsync
+            ? await provider.listSessionFilesAsync(workspacePath)
+            : provider.findAllSessions(workspacePath);
+        if (sessions.length > 0) {
+            return {
+                id: 'session_discovery',
+                status: 'ok',
+                title,
+                message: `Found ${sessions.length} ${provider.displayName} session${sessions.length === 1 ? '' : 's'} for ${workspacePath}.`,
+            };
+        }
+        const operation = provider.getLastOperationStatus?.();
+        const runtime = provider.getRuntimeStatus?.();
+        const issue = operation && !operation.usable
+            ? operation.runtimeStatus
+            : runtime && !runtime.available
+                ? runtime
+                : undefined;
+        return {
+            id: 'session_discovery',
+            status: 'warning',
+            title,
+            message: issue?.message ?? `No ${provider.displayName} sessions found for ${workspacePath}.`,
+            repair: issue?.kind === 'sqlite_missing'
+                ? 'Install sqlite3 and ensure it is on PATH, then rerun sidekick doctor.'
+                : `Start ${provider.displayName} in this project, or inspect ${provider.getSessionDirectory(workspacePath)}.`,
+        };
+    }
+    catch (error) {
+        return {
+            id: 'session_discovery',
+            status: 'warning',
+            title,
+            message: error instanceof Error ? error.message : String(error),
+            repair: `Check ${providerId} session storage permissions and rerun sidekick doctor.`,
+        };
+    }
+    finally {
+        for (const candidate of providers)
+            candidate.dispose();
+    }
+}
 async function runDoctor(options = {}) {
     const project = (0, paths_1.resolveProjectIdentity)(options.cwd);
     const sessions = getSessionDiagnostics(project.cwd);
-    const accounts = (0, accountStatus_1.getActiveAccountStatus)();
+    const accounts = (0, accountStatus_1.getActiveAccountStatus)(undefined, { selfHeal: false });
+    const sessionProvider = options.provider && options.provider !== 'auto' ? options.provider : (0, detect_1.detectProvider)();
     let openCode = options.openCodeStatus;
     if (!openCode) {
         const database = new openCodeDatabase_1.OpenCodeDatabase((0, openCode_1.getOpenCodeDataDir)());
         database.open();
         openCode = database.getRuntimeStatus();
+        database.close();
     }
     const providerStatus = await (options.fetchStatuses ??
         (async () => {
@@ -130,20 +183,7 @@ async function runDoctor(options = {}) {
             title: 'Project identity',
             message: `Canonical slug: ${project.canonicalSlug}`,
         });
-    checks.push(sessions.discoveredSessionDir
-        ? {
-            id: 'session_discovery',
-            status: 'ok',
-            title: 'Session discovery',
-            message: `Found Claude Code sessions at ${sessions.discoveredSessionDir}.`,
-        }
-        : {
-            id: 'session_discovery',
-            status: 'warning',
-            title: 'Session discovery',
-            message: `No Claude Code session directory found for ${project.cwd}.`,
-            repair: `Start Claude Code in this project, or inspect ${sessions.expectedSessionDir}.`,
-        });
+    checks.push(await checkSessionProvider(sessionProvider, project.resolvedCwd));
     const openCodeCheck = openCode.available
         ? {
             id: 'opencode_sqlite',
@@ -167,16 +207,22 @@ async function runDoctor(options = {}) {
                     ? 'Install sqlite3 and ensure the sqlite3 executable is on PATH, then rerun sidekick doctor.'
                     : 'Make sqlite3 executable and verify the OpenCode database is readable.',
             };
+    if (sessionProvider !== 'opencode' && openCodeCheck.status === 'warning') {
+        openCodeCheck.status = 'info';
+        openCodeCheck.message += ' This does not affect the selected session provider.';
+    }
     checks.push(openCodeCheck);
     checks.push({
         id: 'accounts',
-        status: accounts.ok ? 'ok' : 'warning',
+        status: accounts.ok ? 'ok' : 'info',
         title: 'Accounts and credentials',
         message: accounts.ok
             ? `Detected ${[accounts.claude.present && 'Claude', accounts.codex.present && 'Codex'].filter(Boolean).join(' and ')} credentials.`
             : (accounts.error ?? 'No Claude or Codex credentials were detected.'),
         ...(!accounts.ok
-            ? { repair: 'Sign in with claude or codex, then rerun sidekick doctor.' }
+            ? {
+                repair: 'Sign in with claude or codex to refresh account quota. Existing sessions can be monitored without saved credentials.',
+            }
             : {}),
     });
     const unavailableProviders = Object.entries(providerStatus)
@@ -187,7 +233,11 @@ async function runDoctor(options = {}) {
         .map(([name]) => name);
     checks.push({
         id: 'provider_api',
-        status: degradedProviders.length > 0 ? 'warning' : unavailableProviders.length > 0 ? 'info' : 'ok',
+        status: degradedProviders.includes(sessionProvider === 'codex' ? 'openai' : sessionProvider === 'claude-code' ? 'claude' : '')
+            ? 'warning'
+            : degradedProviders.length > 0 || unavailableProviders.length > 0
+                ? 'info'
+                : 'ok',
         title: 'Provider API status',
         message: degradedProviders.length > 0
             ? `Provider incidents reported for: ${degradedProviders.join(', ')}.`
@@ -226,6 +276,7 @@ async function runDoctor(options = {}) {
         openCode,
         providerStatus,
         sessions,
+        sessionProvider,
     };
 }
 function formatHealthReport(report) {

package/dist/index.d.ts

@@ -97,7 +97,7 @@ export type { DebugLogEntry, DebugLogFile, DebugLogLevel } from './parsers/debug
 export { OpenCodeDatabase } from './providers/openCodeDatabase';
 export { CodexDatabase } from './providers/codexDatabase';
 export { searchSessions } from './search/sessionSearch';
-export type { SearchResult } from './search/sessionSearch';
+export type { SearchResult, SessionSearchOptions } from './search/sessionSearch';
 export { FilterEngine } from './search/advancedFilter';
 export type { FilterMode, FilterState, HighlightFormat as FilterHighlightFormat, } from './search/advancedFilter';
 export { composeContext } from './context/composer';

package/dist/providers/claudeCode.js

@@ -136,6 +136,8 @@ class ClaudeCodeReader {
     sessionPath;
     parser;
     filePosition = 0;
+    /** Cursor after the last complete line, safe to persist across restarts. */
+    committedPosition = 0;
     events = [];
     _wasTruncated = false;
     decoder = new string_decoder_1.StringDecoder('utf8');
@@ -165,6 +167,7 @@ class ClaudeCodeReader {
             if (currentSize < this.filePosition) {
                 this._wasTruncated = true;
                 this.filePosition = 0;
+                this.committedPosition = 0;
                 this.parser.reset();
                 this.decoder = new string_decoder_1.StringDecoder('utf8');
             }
@@ -183,7 +186,11 @@ class ClaudeCodeReader {
             finally {
                 fs.closeSync(fd);
             }
-            const chunk = this.decoder.write(buffer.subarray(0, bytesRead));
+            const bytes = buffer.subarray(0, bytesRead);
+            const newline = bytes.lastIndexOf(0x0a);
+            if (newline >= 0)
+                this.committedPosition = this.filePosition + newline + 1;
+            const chunk = this.decoder.write(bytes);
             this.parser.processChunk(chunk);
             this.filePosition += bytesRead;
         }
@@ -198,6 +205,7 @@ class ClaudeCodeReader {
     }
     reset() {
         this.filePosition = 0;
+        this.committedPosition = 0;
         this.parser.reset();
         this.decoder = new string_decoder_1.StringDecoder('utf8');
         this._wasTruncated = false;
@@ -213,10 +221,11 @@ class ClaudeCodeReader {
         this.decoder = new string_decoder_1.StringDecoder('utf8');
     }
     getPosition() {
-        return this.filePosition;
+        return this.committedPosition;
     }
     seekTo(position) {
         this.filePosition = position;
+        this.committedPosition = position;
         this.parser.reset();
         this.decoder = new string_decoder_1.StringDecoder('utf8');
     }

package/dist/providers/codex.js

@@ -473,6 +473,8 @@ class CodexReader {
     onTokenUsage;
     parser;
     filePosition = 0;
+    /** Cursor after the last complete line, safe to persist across restarts. */
+    committedPosition = 0;
     lineBuffer = '';
     _wasTruncated = false;
     decoder = new string_decoder_1.StringDecoder('utf8');
@@ -487,18 +489,19 @@ class CodexReader {
     getSessionMeta() {
         return this.parser.getSessionMeta();
     }
-    readNew() {
+    readNew(endPosition) {
         this._wasTruncated = false;
         const events = [];
         try {
             if (!fs.existsSync(this.rolloutPath))
                 return [];
             const stats = fs.statSync(this.rolloutPath);
-            const currentSize = stats.size;
+            const currentSize = Math.min(stats.size, endPosition ?? stats.size);
             // Handle truncation
             if (currentSize < this.filePosition) {
                 this._wasTruncated = true;
                 this.filePosition = 0;
+                this.committedPosition = 0;
                 this.lineBuffer = '';
                 this.parser.reset();
                 this.decoder = new string_decoder_1.StringDecoder('utf8');
@@ -517,7 +520,11 @@ class CodexReader {
             finally {
                 fs.closeSync(fd);
             }
-            const chunk = this.decoder.write(buffer.subarray(0, bytesRead));
+            const bytes = buffer.subarray(0, bytesRead);
+            const newline = bytes.lastIndexOf(0x0a);
+            if (newline >= 0)
+                this.committedPosition = this.filePosition + newline + 1;
+            const chunk = this.decoder.write(bytes);
             this.filePosition += bytesRead;
             // Process lines
             const text = this.lineBuffer + chunk;
@@ -583,6 +590,7 @@ class CodexReader {
     }
     reset() {
         this.filePosition = 0;
+        this.committedPosition = 0;
         this.lineBuffer = '';
         this.parser.reset();
         this.decoder = new string_decoder_1.StringDecoder('utf8');
@@ -606,12 +614,14 @@ class CodexReader {
         this.decoder = new string_decoder_1.StringDecoder('utf8');
     }
     getPosition() {
-        return this.filePosition;
+        return this.committedPosition;
     }
     seekTo(position) {
-        this.filePosition = position;
-        this.lineBuffer = '';
-        this.decoder = new string_decoder_1.StringDecoder('utf8');
+        // Rebuild model, turn, and cumulative-token context before resuming.
+        // The prefix is parsed only; its events are already in the consumer snapshot.
+        this.reset();
+        if (position > 0)
+            this.readNew(position);
     }
     wasTruncated() {
         return this._wasTruncated;

package/dist/search/sessionSearch.d.ts

@@ -1,6 +1,4 @@
-/**
- * Provider-aware cross-session search.
- */
+/** Provider-aware cross-session search. */
 import type { SessionProviderBase, ProviderId } from '../providers/types';
 export interface SearchResult {
     providerId: ProviderId;
@@ -10,7 +8,13 @@ export interface SearchResult {
     eventType: string;
     timestamp: string;
 }
-export declare function searchSessions(provider: SessionProviderBase, query: string, opts?: {
+export interface SessionSearchOptions {
+    /** Workspace path, resolved canonically. Takes precedence over projectSlug. */
+    projectPath?: string;
+    /** Legacy provider-encoded project identifier. */
     projectSlug?: string;
     maxResults?: number;
-}): Promise<SearchResult[]>;
+    /** Stop obsolete interactive searches between session reads. */
+    signal?: AbortSignal;
+}
+export declare function searchSessions(provider: SessionProviderBase, query: string, options?: SessionSearchOptions): Promise<SearchResult[]>;

package/dist/search/sessionSearch.js

@@ -1,98 +1,69 @@
 "use strict";
-/**
- * Provider-aware cross-session search.
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
+/** Provider-aware cross-session search. */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.searchSessions = searchSessions;
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
-async function searchSessions(provider, query, opts) {
-    const maxResults = opts?.maxResults ?? 50;
+const paths_1 = require("../paths");
+async function enumerateSessions(provider, options) {
+    const workspace = options.projectPath
+        ? (0, paths_1.resolveProjectIdentity)(options.projectPath).resolvedCwd
+        : undefined;
+    if (!options.projectSlug || workspace) {
+        if (provider.listSessionFilesAsync)
+            return provider.listSessionFilesAsync(workspace);
+        if (workspace) {
+            return provider
+                .findAllSessions(workspace)
+                .map((path) => ({ path, mtime: new Date(0), workspacePath: workspace }));
+        }
+        if (provider.listAllSessionFiles)
+            return provider.listAllSessionFiles();
+    }
+    // Older/custom providers can expose virtual project directories. Let the
+    // provider enumerate them instead of assuming a particular on-disk layout.
+    const files = [];
+    for (const folder of provider.getAllProjectFolders()) {
+        if (options.signal?.aborted)
+            break;
+        if (options.projectSlug && folder.encodedName !== options.projectSlug)
+            continue;
+        const paths = provider.id === 'codex'
+            ? provider.findAllSessions(folder.name)
+            : provider.findSessionsInDirectory(folder.dir);
+        files.push(...paths.map((path) => ({ path, mtime: folder.lastModified, workspacePath: folder.name })));
+    }
+    return files;
+}
+async function searchSessions(provider, query, options = {}) {
+    const maxResults = options.maxResults ?? 50;
     const results = [];
-    const baseDir = provider.getProjectsBaseDir();
-    try {
-        if (!fs.existsSync(baseDir))
-            return results;
-        // Get all project folders
-        const folders = provider.getAllProjectFolders();
-        for (const folder of folders) {
-            if (results.length >= maxResults)
-                break;
-            // If projectSlug specified, filter by encoded name
-            if (opts?.projectSlug && folder.encodedName !== opts.projectSlug)
-                continue;
-            // Get session files in this folder
-            let sessionFiles = [];
-            try {
-                const dir = folder.dir;
-                if (fs.existsSync(dir)) {
-                    const entries = fs
-                        .readdirSync(dir)
-                        .filter((f) => f.endsWith('.jsonl') || f.endsWith('.json'));
-                    sessionFiles = entries.map((f) => path.join(dir, f));
-                }
-            }
-            catch {
-                /* skip */
-            }
-            // If no files found from dir scan, try findAllSessions with the folder name
-            if (sessionFiles.length === 0) {
-                // Let canonical directory discovery handle synthetic DB-backed paths.
-                sessionFiles = provider.findSessionsInDirectory(folder.dir);
-            }
-            for (const sessionPath of sessionFiles) {
-                if (results.length >= maxResults)
-                    break;
-                const remaining = maxResults - results.length;
-                const hits = provider.searchInSession(sessionPath, query, remaining);
-                for (const hit of hits) {
-                    results.push({
-                        providerId: provider.id,
-                        projectPath: hit.projectPath || folder.name,
-                        sessionPath: hit.sessionPath,
-                        snippet: hit.line,
-                        eventType: hit.eventType,
-                        timestamp: hit.timestamp,
-                    });
-                }
+    if (maxResults <= 0 || !query.trim() || options.signal?.aborted)
+        return results;
+    const files = await enumerateSessions(provider, options);
+    const seen = new Set();
+    files.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+    for (const file of files) {
+        if (results.length >= maxResults || options.signal?.aborted)
+            break;
+        if (seen.has(file.path))
+            continue;
+        seen.add(file.path);
+        try {
+            const hits = provider.searchInSession(file.path, query, maxResults - results.length);
+            for (const hit of hits.slice(0, maxResults - results.length)) {
+                results.push({
+                    providerId: provider.id,
+                    projectPath: hit.projectPath || file.workspacePath || '',
+                    sessionPath: hit.sessionPath,
+                    snippet: hit.line,
+                    eventType: hit.eventType,
+                    timestamp: hit.timestamp,
+                });
             }
         }
+        catch {
+            // An unreadable session must not hide matches in the remaining sessions.
+        }
+        await new Promise((resolve) => setImmediate(resolve));
     }
-    catch {
-        /* skip */
-    }
-    return results.slice(0, maxResults);
+    return results;
 }

package/dist/watchers/factory.js

@@ -38,17 +38,11 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveSessionPath = resolveSessionPath;
 exports.createWatcher = createWatcher;
-const os = __importStar(require("os"));
 const path = __importStar(require("path"));
+const openCode_1 = require("../providers/openCode");
 const jsonlWatcher_1 = require("./jsonlWatcher");
 const providerReaderWatcher_1 = require("./providerReaderWatcher");
 const sqliteWatcher_1 = require("./sqliteWatcher");
-function getOpenCodeDataDir() {
-    const xdg = process.env.XDG_DATA_HOME;
-    if (xdg)
-        return path.join(xdg, 'opencode');
-    return path.join(os.homedir(), '.local', 'share', 'opencode');
-}
 /**
  * Resolve the session a command should act on: an exact or unique-prefix
  * match of `sessionId` among the workspace's sessions, or the most recent
@@ -94,7 +88,7 @@ function createWatcherForProvider(provider, sessionPath, callbacks) {
         case 'codex':
             return new providerReaderWatcher_1.ProviderReaderSessionWatcher(provider, sessionPath, callbacks);
         case 'opencode': {
-            const dataDir = getOpenCodeDataDir();
+            const dataDir = (0, openCode_1.getOpenCodeDataDir)();
             const dbPath = path.join(dataDir, 'opencode.db');
             // Session ID is the basename without extension
             const sid = path.basename(sessionPath, '.json');

package/dist/watchers/jsonlTail.js

@@ -42,6 +42,26 @@ const fs = __importStar(require("fs"));
 const jsonl_1 = require("../parsers/jsonl");
 const DEFAULT_DEBOUNCE_MS = 100;
 const DEFAULT_CATCHUP_INTERVAL_MS = 30_000;
+/** Skip old complete events while retaining an in-progress final line. */
+function lastCompleteLineOffset(filePath) {
+    const fd = fs.openSync(filePath, 'r');
+    try {
+        let end = fs.fstatSync(fd).size;
+        const buffer = Buffer.alloc(64 * 1024);
+        while (end > 0) {
+            const start = Math.max(0, end - buffer.length);
+            const count = fs.readSync(fd, buffer, 0, end - start, start);
+            const newline = buffer.subarray(0, count).lastIndexOf(0x0a);
+            if (newline >= 0)
+                return start + newline + 1;
+            end = start;
+        }
+        return 0;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 function createJsonlTail(options) {
     return new JsonlTailReader(options);
 }
@@ -79,7 +99,7 @@ class JsonlTailReader {
         this.active = true;
         if (this.options.startAtEnd && this.options.startOffset === undefined) {
             try {
-                this.readOffset = fs.statSync(this.options.path).size;
+                this.readOffset = lastCompleteLineOffset(this.options.path);
             }
             catch {
                 this.readOffset = 0;
@@ -179,7 +199,11 @@ class JsonlTailReader {
             this.fsWatcher = fs.watch(this.options.path, { persistent: false }, () => {
                 this.debouncedRead();
             });
-            this.fsWatcher.on('error', (error) => this.options.onError?.(error));
+            this.fsWatcher.on('error', (error) => {
+                this.fsWatcher?.close();
+                this.fsWatcher = null;
+                this.options.onError?.(error);
+            });
         }
         catch {
             // Polling still covers filesystems where fs.watch is unavailable.

package/dist/watchers/jsonlWatcher.d.ts

@@ -5,26 +5,20 @@
 import type { ProviderId } from '../providers/types';
 import type { SessionWatcher, SessionWatcherCallbacks } from './types';
 export declare class JsonlSessionWatcher implements SessionWatcher {
-    private _isActive;
-    private filePosition;
-    private fsWatcher;
-    private catchupTimer;
-    private debounceTimer;
-    private codexInPlanMode;
-    private readonly parser;
     private readonly providerId;
     private readonly sessionPath;
     private readonly callbacks;
+    private tail;
+    private startOffset;
+    private codexInPlanMode;
     constructor(providerId: ProviderId, sessionPath: string, callbacks: SessionWatcherCallbacks);
     get isActive(): boolean;
-    /** Seek to a byte offset. Must be called before start(). */
+    /** Seek to a committed byte offset before starting replay. */
     seekTo(position: number): void;
-    /** Get the current byte position. */
+    /** Position after the last complete JSONL line. */
     getPosition(): number;
     start(replay: boolean): void;
     stop(): void;
-    private debouncedRead;
-    private readNewBytes;
     private handleRawEvent;
     private normalizeCodexEvent;
 }

package/dist/watchers/jsonlWatcher.js

@@ -3,47 +3,11 @@
  * JSONL session watcher for Claude Code and Codex.
  * Uses byte-offset tracking + fs.watch with debounce + catch-up polling.
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JsonlSessionWatcher = void 0;
-const fs = __importStar(require("fs"));
-const jsonl_1 = require("../parsers/jsonl");
+const jsonlTail_1 = require("./jsonlTail");
 const codexParser_1 = require("../parsers/codexParser");
 const toolSummary_1 = require("../formatters/toolSummary");
-const DEBOUNCE_MS = 100;
-const CATCHUP_INTERVAL_MS = 30_000;
 // ── Normalizers ──
 function normalizeClaudeCodeEvent(raw) {
     const events = [];
@@ -220,139 +184,46 @@ function truncate(text, maxLen) {
 }
 // ── Watcher ──
 class JsonlSessionWatcher {
-    _isActive = false;
-    filePosition = 0;
-    fsWatcher = null;
-    catchupTimer = null;
-    debounceTimer = null;
-    codexInPlanMode = false;
-    parser;
     providerId;
     sessionPath;
     callbacks;
+    tail;
+    startOffset;
+    codexInPlanMode = false;
     constructor(providerId, sessionPath, callbacks) {
         this.providerId = providerId;
         this.sessionPath = sessionPath;
         this.callbacks = callbacks;
-        this.parser = new jsonl_1.JsonlParser({
-            onEvent: (event) => this.handleRawEvent(event),
-            onError: (err) => callbacks.onError?.(err),
-        });
     }
     get isActive() {
-        return this._isActive;
+        return this.tail?.isActive ?? false;
     }
-    /** Seek to a byte offset. Must be called before start(). */
+    /** Seek to a committed byte offset before starting replay. */
     seekTo(position) {
-        this.filePosition = position;
-        this.parser.reset();
+        this.startOffset = Math.max(0, position);
+        this.tail?.seekTo(this.startOffset);
     }
-    /** Get the current byte position. */
+    /** Position after the last complete JSONL line. */
     getPosition() {
-        return this.filePosition;
+        return this.tail?.getOffset() ?? this.startOffset ?? 0;
     }
     start(replay) {
-        if (this._isActive)
+        if (this.isActive)
             return;
-        this._isActive = true;
-        if (replay) {
-            // Read entire file from offset 0
-            this.readNewBytes();
-        }
-        else {
-            // Skip to end of file
-            try {
-                const stat = fs.statSync(this.sessionPath);
-                this.filePosition = stat.size;
-            }
-            catch {
-                this.filePosition = 0;
-            }
-        }
-        // Watch for changes
-        try {
-            this.fsWatcher = fs.watch(this.sessionPath, { persistent: false }, () => {
-                this.debouncedRead();
-            });
-            this.fsWatcher.on('error', (error) => {
-                // Degrade to catch-up polling without killing the live session.
-                this.fsWatcher?.close();
-                this.fsWatcher = null;
-                this.callbacks.onError?.(error);
-            });
-        }
-        catch {
-            // fs.watch not available, rely on polling only
-        }
-        // Catch-up polling
-        this.catchupTimer = setInterval(() => {
-            if (this._isActive)
-                this.readNewBytes();
-        }, CATCHUP_INTERVAL_MS);
+        this.tail = (0, jsonlTail_1.createJsonlTail)({
+            path: this.sessionPath,
+            startOffset: replay ? this.getPosition() : undefined,
+            startAtEnd: !replay,
+            onEvent: (event) => this.handleRawEvent(event),
+            onBatchComplete: () => this.callbacks.onBatchComplete?.(),
+            onError: (error) => this.callbacks.onError?.(error),
+        });
+        this.tail.start();
     }
     stop() {
-        if (!this._isActive)
-            return;
-        this._isActive = false;
-        if (this.debounceTimer) {
-            clearTimeout(this.debounceTimer);
-            this.debounceTimer = null;
-        }
-        if (this.fsWatcher) {
-            this.fsWatcher.close();
-            this.fsWatcher = null;
-        }
-        if (this.catchupTimer) {
-            clearInterval(this.catchupTimer);
-            this.catchupTimer = null;
-        }
-        this.parser.flush();
+        this.tail?.stop();
         this.codexInPlanMode = false;
     }
-    debouncedRead() {
-        if (this.debounceTimer)
-            clearTimeout(this.debounceTimer);
-        this.debounceTimer = setTimeout(() => {
-            this.readNewBytes();
-        }, DEBOUNCE_MS);
-    }
-    readNewBytes() {
-        if (!this._isActive)
-            return;
-        let fd = null;
-        try {
-            const stat = fs.statSync(this.sessionPath);
-            // Handle file truncation (shouldn't happen with append-only, but be safe)
-            if (stat.size < this.filePosition) {
-                this.filePosition = 0;
-                this.parser.reset();
-            }
-            if (stat.size <= this.filePosition)
-                return;
-            fd = fs.openSync(this.sessionPath, 'r');
-            const bytesToRead = stat.size - this.filePosition;
-            const buffer = Buffer.alloc(bytesToRead);
-            const bytesRead = fs.readSync(fd, buffer, 0, bytesToRead, this.filePosition);
-            fs.closeSync(fd);
-            fd = null;
-            if (bytesRead > 0) {
-                this.filePosition += bytesRead;
-                const chunk = buffer.toString('utf-8', 0, bytesRead);
-                this.parser.processChunk(chunk);
-            }
-        }
-        catch (err) {
-            if (fd !== null) {
-                try {
-                    fs.closeSync(fd);
-                }
-                catch {
-                    /* ignore */
-                }
-            }
-            this.callbacks.onError?.(err instanceof Error ? err : new Error(String(err)));
-        }
-    }
     handleRawEvent(event) {
         // For codex, raw events don't match RawSessionEvent shape exactly, but
         // JsonlParser parses any JSON object. Cast to Record for codex normalizer.

package/dist/watchers/providerReaderWatcher.js

@@ -112,12 +112,13 @@ class ProviderReaderSessionWatcher {
             clearInterval(this.catchupTimer);
             this.catchupTimer = null;
         }
-        this.reader.flush();
+        // Keep unfinished input buffered so a later start can resume losslessly.
     }
     seekToEnd() {
         try {
-            const stat = fs.statSync(this.sessionPath);
-            this.reader.seekTo(stat.size);
+            // Consume existing complete records to retain parser context and any
+            // unfinished line, without emitting historical events.
+            this.reader.readNew();
         }
         catch {
             this.reader.reset();
@@ -143,6 +144,7 @@ class ProviderReaderSessionWatcher {
                     this.callbacks.onEvent(followEvent);
                 }
             }
+            this.callbacks.onBatchComplete?.();
         }
         catch (err) {
             this.callbacks.onError?.(err instanceof Error ? err : new Error(String(err)));

package/dist/watchers/sqliteWatcher.js

@@ -312,6 +312,7 @@ class SqliteSessionWatcher {
                 if (part.time_updated > this.lastPartTime)
                     this.lastPartTime = part.time_updated;
             }
+            this.callbacks.onBatchComplete?.();
         }
         catch (err) {
             this.callbacks.onError?.(err instanceof Error ? err : new Error(String(err)));

package/dist/watchers/types.d.ts

@@ -46,6 +46,8 @@ export interface FollowEvent {
 }
 export interface SessionWatcherCallbacks {
     onEvent: (event: FollowEvent) => void;
+    /** All events in this read have been delivered; the cursor can now be checkpointed. */
+    onBatchComplete?: () => void;
     onError?: (error: Error) => void;
 }
 export interface SessionWatcher {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidekick-shared",
-  "version": "0.26.1",
+  "version": "0.26.2",
   "description": "Shared data access layer for Sidekick — readers, types, providers, credentials, quota",
   "keywords": [
     "claude-code",