sidekick-shared 0.24.4 → 0.24.5

package/dist/providers/codex.d.ts

@@ -9,9 +9,29 @@
  * Ported from sidekick-vscode/src/services/providers/CodexSessionProvider.ts
  */
 import type { ReadSessionContextSnapshotOptions, SessionContextSnapshot } from '../context/sessionContext';
-import type { SessionProviderBase, SessionReader, ProjectFolderInfo, SearchHit, SessionFileStats, ProviderId } from './types';
+import type { SessionProviderBase, SessionReader, ProjectFolderInfo, SearchHit, SessionFileInfo, SessionFileStats, ProviderId } from './types';
 import type { SubagentStats, TokenUsage } from '../types/sessionEvent';
 import type { CodexRateLimits } from '../types/codex';
+export interface FindCodexRolloutFileOptions {
+    /**
+     * Codex home whose `sessions/` subtree to search. Defaults to every
+     * monitored home: `$CODEX_HOME` if set, else `~/.codex`, plus managed
+     * profile homes that recorded sessions.
+     */
+    codexHome?: string;
+}
+/**
+ * Locates the rollout file for a Codex session id by walking
+ * `<home>/sessions/YYYY/MM/DD/rollout-<timestamp>-<id>.jsonl`.
+ *
+ * Filename-only match, case-insensitive on the id — no file contents are read
+ * and files are only stat'ed once their name matches, so the walk stays cheap
+ * even over a large history. When the same id exists in more than one home,
+ * the most recently modified copy wins. Returns `null` for an unknown, empty,
+ * or whitespace id. Consumers who want the database's answer instead can query
+ * the already-public `CodexDatabase` (requires the external `sqlite3` binary).
+ */
+export declare function findCodexRolloutFile(sessionId: string, options?: FindCodexRolloutFileOptions): string | null;
 /**
  * Session provider for Codex CLI.
  *
@@ -35,6 +55,7 @@ export declare class CodexProvider implements SessionProviderBase {
     /** Backward-compatible alias for findAllSessions. */
     findSessionFiles(workspacePath: string): string[];
     findSessionsInDirectory(dir: string): string[];
+    listAllSessionFiles(): SessionFileInfo[];
     getAllProjectFolders(workspacePath?: string): ProjectFolderInfo[];
     isSessionFile(filename: string): boolean;
     getSessionId(sessionPath: string): string;

package/dist/providers/codex.js

@@ -44,6 +44,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CodexProvider = void 0;
+exports.findCodexRolloutFile = findCodexRolloutFile;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const string_decoder_1 = require("string_decoder");
@@ -164,6 +165,60 @@ function findRolloutFilesInConfiguredHomes() {
     }
     return results;
 }
+/**
+ * Locates the rollout file for a Codex session id by walking
+ * `<home>/sessions/YYYY/MM/DD/rollout-<timestamp>-<id>.jsonl`.
+ *
+ * Filename-only match, case-insensitive on the id — no file contents are read
+ * and files are only stat'ed once their name matches, so the walk stays cheap
+ * even over a large history. When the same id exists in more than one home,
+ * the most recently modified copy wins. Returns `null` for an unknown, empty,
+ * or whitespace id. Consumers who want the database's answer instead can query
+ * the already-public `CodexDatabase` (requires the external `sqlite3` binary).
+ */
+function findCodexRolloutFile(sessionId, options = {}) {
+    const normalizedId = sessionId.trim().toLowerCase();
+    if (!normalizedId)
+        return null;
+    const sessionsDirs = options.codexHome
+        ? [path.join(options.codexHome, 'sessions')]
+        : getSessionsDirs();
+    let best = null;
+    for (const dir of sessionsDirs) {
+        for (const candidate of findRolloutFilesById(dir, normalizedId)) {
+            if (!best || candidate.mtimeMs > best.mtimeMs)
+                best = candidate;
+        }
+    }
+    return best?.path ?? null;
+}
+function findRolloutFilesById(dir, normalizedId) {
+    const results = [];
+    try {
+        if (!fs.existsSync(dir))
+            return results;
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                results.push(...findRolloutFilesById(fullPath, normalizedId));
+            }
+            else if (entry.isFile() &&
+                isRolloutFile(entry.name) &&
+                extractSessionId(entry.name).toLowerCase() === normalizedId) {
+                try {
+                    results.push({ path: fullPath, mtimeMs: fs.statSync(fullPath).mtimeMs });
+                }
+                catch {
+                    // Skip files that vanish between readdir and stat.
+                }
+            }
+        }
+    }
+    catch {
+        // Skip inaccessible directories.
+    }
+    return results;
+}
 /** Pick the best sessions directory for UI/search entrypoints. */
 function getSessionsDir() {
     const dirs = getSessionsDirs();
@@ -711,6 +766,9 @@ class CodexProvider {
         files.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
         return files.map((f) => f.path);
     }
+    listAllSessionFiles() {
+        return findRolloutFilesInConfiguredHomes();
+    }
     getAllProjectFolders(workspacePath) {
         const folders = [];
         const seenCwds = new Map();

package/dist/providers/types.d.ts

@@ -143,6 +143,11 @@ export interface SessionProviderBase {
     readSessionContextSnapshot?(sessionPath: string, options?: ReadSessionContextSnapshotOptions): SessionContextSnapshot;
     /** Reports provider runtime readiness for DB-backed providers. */
     getRuntimeStatus?(): ProviderRuntimeStatus;
+    /**
+     * Lists every session file this provider knows about, across all workspaces.
+     * Stat-only — implementations must not read file contents.
+     */
+    listAllSessionFiles?(): SessionFileInfo[];
     /** Tests whether a provider can monitor a directory path, including synthetic DB-backed paths. */
     canMonitorDirectory?(dir: string): boolean;
     /** Release resources. */

package/dist/quotaHistory.d.ts

@@ -3,7 +3,7 @@
  *
  * Sibling to `quotaSnapshots.ts`. Where snapshots persist a single most-recent sample per
  * (provider, account), this module accumulates time-series samples so consumers (the VS Code
- * dashboard, the `sidekick quota history` CLI, contextful_desktop) can render heatmaps and
+ * dashboard, the `sidekick quota history` CLI, external consumers) can render heatmaps and
  * trend visualisations over a 13-week window.
  */
 export type QuotaHistoryRuntimeProvider = 'claude' | 'codex' | 'zai';

package/dist/quotaHistory.js

@@ -4,7 +4,7 @@
  *
  * Sibling to `quotaSnapshots.ts`. Where snapshots persist a single most-recent sample per
  * (provider, account), this module accumulates time-series samples so consumers (the VS Code
- * dashboard, the `sidekick quota history` CLI, contextful_desktop) can render heatmaps and
+ * dashboard, the `sidekick quota history` CLI, external consumers) can render heatmaps and
  * trend visualisations over a 13-week window.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -258,7 +258,7 @@ async function runAppend(sample, filePath, options) {
         // ignore
     }
     // Backwards-compat: keep the latest-snapshot store hot so existing callers (DashboardViewProvider,
-    // codex session provider, contextful_desktop) don't have to query history for "latest".
+    // codex session provider, external consumers) don't have to query history for "latest".
     try {
         const providerId = runtimeProviderToSnapshotProvider(sample.runtimeProvider);
         (0, quotaSnapshots_1.writeQuotaSnapshot)(providerId, sample.providerId, sampleToQuotaState(sample));

package/dist/quotaSnapshots.js

@@ -35,40 +35,17 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.writeQuotaSnapshot = writeQuotaSnapshot;
 exports.readQuotaSnapshot = readQuotaSnapshot;
-const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const paths_1 = require("./paths");
+const atomic_1 = require("./writers/atomic");
 const codex_1 = require("./types/codex");
-const LOCK_WAIT_MS = 15;
-const LOCK_STALE_MS = 10_000;
-const LOCK_TIMEOUT_MS = 15_000;
-const lockSleepView = new Int32Array(new SharedArrayBuffer(4));
 function getQuotaSnapshotPath() {
     return path.join((0, paths_1.getConfigDir)(), 'quota-snapshots.json');
 }
 function ensureConfigDir() {
     fs.mkdirSync((0, paths_1.getConfigDir)(), { recursive: true, mode: 0o700 });
 }
-function atomicWriteJson(filePath, data, mode = 0o600) {
-    const tmp = `${filePath}.${process.pid}.${Date.now()}.${crypto.randomBytes(8).toString('hex')}.tmp`;
-    const json = JSON.stringify(data, null, 2);
-    // Throws if `data` was undefined or a top-level non-serializable value — prevents writing the literal string "undefined" to disk.
-    JSON.parse(json);
-    try {
-        fs.writeFileSync(tmp, json, { encoding: 'utf8', mode });
-        fs.renameSync(tmp, filePath);
-    }
-    catch (error) {
-        try {
-            fs.rmSync(tmp, { force: true });
-        }
-        catch {
-            // Best effort cleanup only.
-        }
-        throw error;
-    }
-}
 function readStore() {
     try {
         const parsed = JSON.parse(fs.readFileSync(getQuotaSnapshotPath(), 'utf8'));
@@ -86,62 +63,16 @@ function readStore() {
 }
 function writeStore(store) {
     ensureConfigDir();
-    atomicWriteJson(getQuotaSnapshotPath(), store);
+    (0, atomic_1.atomicWriteJsonSync)(getQuotaSnapshotPath(), store);
 }
+/**
+ * Serializes snapshot read-modify-write cycles across processes on the shared
+ * store lock. The lock file path is unchanged from the previous local
+ * implementation, so processes running older versions still exclude correctly.
+ */
 function withSnapshotStoreLock(operation) {
     ensureConfigDir();
-    const lockPath = `${getQuotaSnapshotPath()}.lock`;
-    const token = `${process.pid}:${crypto.randomBytes(16).toString('hex')}`;
-    const deadline = Date.now() + LOCK_TIMEOUT_MS;
-    while (true) {
-        try {
-            const descriptor = fs.openSync(lockPath, 'wx', 0o600);
-            fs.writeFileSync(descriptor, token, 'utf8');
-            fs.fsyncSync(descriptor);
-            fs.closeSync(descriptor);
-            break;
-        }
-        catch (error) {
-            if (error.code !== 'EEXIST')
-                throw error;
-            try {
-                const stat = fs.statSync(lockPath);
-                if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
-                    const owner = fs.readFileSync(lockPath, 'utf8');
-                    const ownerPid = Number.parseInt(owner.split(':', 1)[0], 10);
-                    let ownerAlive = Number.isInteger(ownerPid) && ownerPid > 0;
-                    if (ownerAlive) {
-                        try {
-                            process.kill(ownerPid, 0);
-                        }
-                        catch (ownerError) {
-                            ownerAlive = ownerError.code === 'EPERM';
-                        }
-                    }
-                    if (!ownerAlive)
-                        fs.rmSync(lockPath, { force: true });
-                }
-            }
-            catch {
-                // The owner may have released the lock between checks.
-            }
-            if (Date.now() >= deadline)
-                throw new Error(`Timed out waiting for quota lock: ${lockPath}`);
-            Atomics.wait(lockSleepView, 0, 0, LOCK_WAIT_MS);
-        }
-    }
-    try {
-        return operation();
-    }
-    finally {
-        try {
-            if (fs.readFileSync(lockPath, 'utf8') === token)
-                fs.rmSync(lockPath, { force: true });
-        }
-        catch {
-            // Never remove a lock that has already been released or replaced.
-        }
-    }
+    return (0, atomic_1.withFileLockSync)(`${getQuotaSnapshotPath()}.lock`, operation);
 }
 function snapshotTimeMs(quota) {
     const capturedAt = quota.capturedAt ? Date.parse(quota.capturedAt) : NaN;

package/dist/sessionPreviews.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Cheap, bounded previews of provider-native session files (Node-only).
+ *
+ * `listRecentSessions` answers "what happened in this workspace" but labels
+ * every discovered session before applying its limit, so its cost scales with
+ * total session count. This module inverts the order of operations: enumerate
+ * with stats only, sort by mtime, apply `since`/`limit`, and only then do
+ * bounded content reads for the survivors. That keeps a "recent sessions"
+ * surface cheap even against a machine with thousands of accumulated sessions.
+ *
+ * Prompt extraction delegates to each provider's `extractSessionLabel` (Claude
+ * Code reads only the first 8 KiB; Codex prefers the sqlite thread title, else
+ * a bounded first-user-message scan that skips injected context). The first
+ * timestamp and workspace path come from one generic prefix parse in this
+ * module. A session whose opening events are larger than the prefix budget
+ * yields `null` fields rather than an error.
+ *
+ * @module sessionPreviews
+ */
+import type { ProviderId, SessionProviderBase } from './providers/types';
+export interface SessionPreview {
+    provider: ProviderId;
+    sessionId: string;
+    filePath: string;
+    /** ISO mtime of the session file. */
+    modifiedAt: string;
+    sizeBytes: number;
+    /**
+     * First real user prompt, as truncated by the provider (~60 chars). Codex
+     * may substitute the sqlite thread title when the database is reachable.
+     */
+    firstUserPrompt: string | null;
+    /** ISO timestamp of the first event found in the bounded prefix, if any. */
+    firstTimestamp: string | null;
+    /** Workspace/cwd recorded in the prefix (Claude `cwd`, Codex `session_meta.payload.cwd`), if any. */
+    workspacePath: string | null;
+}
+export interface ReadSessionPreviewOptions {
+    /** Byte budget for the generic prefix scan (default 16 KiB). */
+    maxPrefixBytes?: number;
+}
+export interface ListSessionPreviewsOptions extends ReadSessionPreviewOptions {
+    /** Maximum previews returned (default 50). Content reads happen only for the returned slice. */
+    limit?: number;
+    /** Restrict to one workspace (via `provider.findAllSessions`); omit for all workspaces. */
+    workspacePath?: string;
+    /** Skip files whose mtime is not strictly newer than this — cheap incremental refresh. */
+    since?: Date | string;
+}
+/**
+ * Reads a bounded preview of one session file. Returns `null` when the file is
+ * missing or unreadable; malformed content degrades to `null` fields instead
+ * of throwing.
+ */
+export declare function readSessionPreview(provider: SessionProviderBase, sessionPath: string, options?: ReadSessionPreviewOptions): SessionPreview | null;
+/**
+ * Lists previews across providers, newest first. Enumeration is stat-only;
+ * content is read only for the post-`limit` survivors.
+ */
+export declare function listSessionPreviews(providers: SessionProviderBase[], options?: ListSessionPreviewsOptions): SessionPreview[];

package/dist/sessionPreviews.js

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * Cheap, bounded previews of provider-native session files (Node-only).
+ *
+ * `listRecentSessions` answers "what happened in this workspace" but labels
+ * every discovered session before applying its limit, so its cost scales with
+ * total session count. This module inverts the order of operations: enumerate
+ * with stats only, sort by mtime, apply `since`/`limit`, and only then do
+ * bounded content reads for the survivors. That keeps a "recent sessions"
+ * surface cheap even against a machine with thousands of accumulated sessions.
+ *
+ * Prompt extraction delegates to each provider's `extractSessionLabel` (Claude
+ * Code reads only the first 8 KiB; Codex prefers the sqlite thread title, else
+ * a bounded first-user-message scan that skips injected context). The first
+ * timestamp and workspace path come from one generic prefix parse in this
+ * module. A session whose opening events are larger than the prefix budget
+ * yields `null` fields rather than an error.
+ *
+ * @module sessionPreviews
+ */
+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.readSessionPreview = readSessionPreview;
+exports.listSessionPreviews = listSessionPreviews;
+const fs = __importStar(require("fs"));
+const DEFAULT_PREFIX_BYTES = 16 * 1024;
+const DEFAULT_LIMIT = 50;
+/**
+ * Reads a bounded preview of one session file. Returns `null` when the file is
+ * missing or unreadable; malformed content degrades to `null` fields instead
+ * of throwing.
+ */
+function readSessionPreview(provider, sessionPath, options = {}) {
+    let stats;
+    let modifiedAt;
+    try {
+        stats = fs.statSync(sessionPath);
+        // Inside the try: an out-of-range mtime RangeErrors on serialization,
+        // and this function's contract is to degrade, not throw.
+        modifiedAt = stats.mtime.toISOString();
+    }
+    catch {
+        return null;
+    }
+    let firstUserPrompt = null;
+    try {
+        firstUserPrompt = provider.extractSessionLabel(sessionPath);
+    }
+    catch {
+        // Label extraction is best-effort.
+    }
+    let sessionId = '';
+    try {
+        sessionId = provider.getSessionId(sessionPath);
+    }
+    catch {
+        // A provider that cannot identify the file still yields a usable preview.
+    }
+    const prefix = scanPrefix(sessionPath, options.maxPrefixBytes ?? DEFAULT_PREFIX_BYTES);
+    return {
+        provider: provider.id,
+        sessionId,
+        filePath: sessionPath,
+        modifiedAt,
+        sizeBytes: stats.size,
+        firstUserPrompt,
+        firstTimestamp: prefix.firstTimestamp,
+        workspacePath: prefix.workspacePath,
+    };
+}
+/**
+ * Lists previews across providers, newest first. Enumeration is stat-only;
+ * content is read only for the post-`limit` survivors.
+ */
+function listSessionPreviews(providers, options = {}) {
+    const limit = Math.max(0, options.limit ?? DEFAULT_LIMIT);
+    const sinceMs = resolveSinceMs(options.since);
+    const candidates = [];
+    for (const provider of providers) {
+        for (const file of enumerateSessionFiles(provider, options.workspacePath)) {
+            const mtimeMs = file.mtime.getTime();
+            if (sinceMs !== null && mtimeMs <= sinceMs)
+                continue;
+            candidates.push({ provider, path: file.path, mtimeMs });
+        }
+    }
+    candidates.sort((left, right) => right.mtimeMs - left.mtimeMs);
+    const previews = [];
+    for (const candidate of candidates.slice(0, limit)) {
+        const preview = readSessionPreview(candidate.provider, candidate.path, options);
+        if (preview)
+            previews.push(preview);
+    }
+    return previews;
+}
+function resolveSinceMs(since) {
+    if (since === undefined)
+        return null;
+    const ms = since instanceof Date ? since.getTime() : Date.parse(since);
+    return Number.isFinite(ms) ? ms : null;
+}
+function enumerateSessionFiles(provider, workspacePath) {
+    try {
+        if (workspacePath) {
+            return provider
+                .findAllSessions(workspacePath)
+                .map(statSessionFile)
+                .filter((info) => info !== null);
+        }
+        if (provider.listAllSessionFiles)
+            return provider.listAllSessionFiles();
+        // Best-effort global fallback for providers without listAllSessionFiles:
+        // correct for project-folder-shaped providers, empty otherwise.
+        const results = [];
+        const seen = new Set();
+        for (const folder of provider.getAllProjectFolders()) {
+            for (const sessionPath of provider.findSessionsInDirectory(folder.dir)) {
+                if (seen.has(sessionPath))
+                    continue;
+                seen.add(sessionPath);
+                const info = statSessionFile(sessionPath);
+                if (info)
+                    results.push(info);
+            }
+        }
+        return results;
+    }
+    catch {
+        return [];
+    }
+}
+function statSessionFile(sessionPath) {
+    try {
+        return { path: sessionPath, mtime: fs.statSync(sessionPath).mtime };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parses complete JSONL lines out of the first `maxPrefixBytes` of a file,
+ * taking the first top-level `timestamp` string and the first workspace path
+ * (top-level `cwd`, or `payload.cwd` on a Codex `session_meta` row). Partial
+ * trailing lines and malformed rows are skipped; never throws.
+ */
+function scanPrefix(sessionPath, maxPrefixBytes) {
+    const result = { firstTimestamp: null, workspacePath: null };
+    let content;
+    let sawWholeFile;
+    try {
+        const descriptor = fs.openSync(sessionPath, 'r');
+        try {
+            const size = fs.fstatSync(descriptor).size;
+            const readBytes = Math.min(size, Math.max(1, maxPrefixBytes));
+            const buffer = Buffer.alloc(readBytes);
+            fs.readSync(descriptor, buffer, 0, readBytes, 0);
+            content = buffer.toString('utf8');
+            sawWholeFile = readBytes >= size;
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+    }
+    catch {
+        return result;
+    }
+    const lines = content.split('\n');
+    // The final chunk after the last newline is a partial line unless the whole
+    // file fit in the prefix.
+    const completeLines = sawWholeFile ? lines : lines.slice(0, -1);
+    for (const line of completeLines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (parsed === null || typeof parsed !== 'object')
+            continue;
+        if (result.firstTimestamp === null && typeof parsed.timestamp === 'string') {
+            result.firstTimestamp = parsed.timestamp;
+        }
+        if (result.workspacePath === null) {
+            if (typeof parsed.cwd === 'string' && parsed.cwd) {
+                result.workspacePath = parsed.cwd;
+            }
+            else if (parsed.type === 'session_meta') {
+                const payload = parsed.payload;
+                if (payload && typeof payload.cwd === 'string' && payload.cwd) {
+                    result.workspacePath = payload.cwd;
+                }
+            }
+        }
+        if (result.firstTimestamp !== null && result.workspacePath !== null)
+            break;
+    }
+    return result;
+}

package/dist/sessionTranscripts.js

@@ -7,17 +7,23 @@ const transcript_1 = require("./transcript");
 /** List recent sessions using the provider's existing discovery and metadata APIs. */
 function listRecentSessions(provider, workspacePath, options = {}) {
     const limit = Math.max(0, options.limit ?? 20);
+    // Sort on mtime alone first so labels — the only per-file content read —
+    // are extracted just for the returned slice, not every discovered session.
     return provider
         .findAllSessions(workspacePath)
         .map((sessionPath) => ({
-        provider: provider.id,
-        sessionId: provider.getSessionId(sessionPath),
         sessionPath,
-        label: provider.extractSessionLabel(sessionPath),
         modifiedAt: sessionModifiedAt(provider, sessionPath).toISOString(),
     }))
         .sort((left, right) => right.modifiedAt.localeCompare(left.modifiedAt))
-        .slice(0, limit);
+        .slice(0, limit)
+        .map(({ sessionPath, modifiedAt }) => ({
+        provider: provider.id,
+        sessionId: provider.getSessionId(sessionPath),
+        sessionPath,
+        label: provider.extractSessionLabel(sessionPath),
+        modifiedAt,
+    }));
 }
 function sessionModifiedAt(provider, sessionPath) {
     const metadata = provider.getSessionMetadata?.(sessionPath);

package/dist/writers/atomic.d.ts

@@ -1,4 +1,24 @@
 export declare function atomicWriteJson(filePath: string, value: unknown): Promise<void>;
 export declare function atomicWriteJsonSync(filePath: string, value: unknown): void;
+/** Raw-string sibling of {@link atomicWriteJsonSync} for non-JSON payloads. */
+export declare function atomicWriteFileSync(filePath: string, content: string, mode?: number): void;
 /** Serializes read-modify-write cycles across Sidekick processes. */
 export declare function updateJsonStoreAtomic<T>(filePath: string, createEmpty: () => T, update: (latest: T) => T | Promise<T>): Promise<T>;
+/**
+ * Synchronous counterpart of {@link acquireLock}, sharing its lock-file
+ * protocol so sync and async waiters exclude each other across processes.
+ *
+ * Two timeout rules apply instead of one: the same progress-based budget as the
+ * async path (a token that never changes trips it in LOCK_NO_PROGRESS_MS), plus
+ * an absolute {@link SYNC_LOCK_MAX_WAIT_MS} ceiling, because a sync waiter
+ * blocks its event loop while queued. Sync holders take no heartbeat — their
+ * critical sections must stay well under LOCK_STALE_MS (in-repo users are
+ * local-filesystem read-modify-writes, plus keychain reads behind the
+ * auth-swap locks that can take a few seconds).
+ *
+ * The caller must ensure `dirname(lockPath)` exists — a missing parent
+ * surfaces as a raw ENOENT, not a timeout.
+ */
+export declare function withFileLockSync<T>(lockPath: string, operation: () => T): T;
+/** Synchronous mirror of {@link updateJsonStoreAtomic}. */
+export declare function updateJsonStoreAtomicSync<T>(filePath: string, createEmpty: () => T, update: (latest: T) => T): T;