@phnx-labs/agents-cli 1.14.7 → 1.16.0

package/dist/lib/secrets/index.d.ts

@@ -1,11 +1,14 @@
 /**
- * macOS Keychain integration for secure credential storage.
+ * Cross-platform secure credential storage.
  *
- * All reads/writes go through a signed Swift helper (keychain-helper.swift)
- * compiled into AgentsKeychain.app. The .app embeds a provisioning profile
- * that grants the application-identifier + keychain-access-groups entitlement
- * macOS requires for kSecAttrSynchronizable writes (iCloud Keychain).
- * For device-local writes the helper is invoked with the `nosync` arg.
+ * macOS: Uses Keychain via signed Swift helper (AgentsKeychain.app) or `security` CLI.
+ * Linux: Uses libsecret (GNOME Keyring) via `secret-tool` CLI.
+ * Windows: Not yet supported.
+ *
+ * The .app embeds a provisioning profile that grants the application-identifier
+ * + keychain-access-groups entitlement macOS requires for kSecAttrSynchronizable
+ * writes (iCloud Keychain). For device-local writes the helper is invoked with
+ * the `nosync` arg.
  */
 /** Supported secret resolution backends. */
 export type SecretProvider = 'keychain' | 'env' | 'file' | 'exec';
@@ -49,15 +52,15 @@ export interface KeychainBackend {
 }
 /** Install a custom keychain backend (test only). Returns the previous backend so callers can restore. */
 export declare function setKeychainBackendForTest(b: KeychainBackend | null): KeychainBackend | null;
-/** Check if a keychain item exists (macOS only). */
+/** Check if a keychain/keyring item exists. */
 export declare function hasKeychainToken(item: string, sync?: boolean): boolean;
-/** Retrieve a secret value from the macOS Keychain. Throws if not found. */
+/** Retrieve a secret value from the keychain/keyring. Throws if not found. */
 export declare function getKeychainToken(item: string, sync?: boolean): string;
-/** Store or update a secret value in the macOS Keychain. iCloud-synced when sync=true. */
+/** Store or update a secret value in the keychain/keyring. iCloud-synced when sync=true (macOS only). */
 export declare function setKeychainToken(item: string, value: string, sync?: boolean): void;
-/** Delete a keychain item. Returns true if it existed. */
+/** Delete a keychain/keyring item. Returns true if it existed. */
 export declare function deleteKeychainToken(item: string, sync?: boolean): boolean;
-/** Enumerate keychain item service names whose name starts with the given prefix. */
+/** Enumerate keychain/keyring item names starting with the given prefix. */
 export declare function listKeychainItems(prefix: string): string[];
 /** Options controlling how secret refs are resolved. */
 export interface ResolveOptions {

package/dist/lib/secrets/index.js

@@ -1,17 +1,21 @@
 /**
- * macOS Keychain integration for secure credential storage.
+ * Cross-platform secure credential storage.
  *
- * All reads/writes go through a signed Swift helper (keychain-helper.swift)
- * compiled into AgentsKeychain.app. The .app embeds a provisioning profile
- * that grants the application-identifier + keychain-access-groups entitlement
- * macOS requires for kSecAttrSynchronizable writes (iCloud Keychain).
- * For device-local writes the helper is invoked with the `nosync` arg.
+ * macOS: Uses Keychain via signed Swift helper (AgentsKeychain.app) or `security` CLI.
+ * Linux: Uses libsecret (GNOME Keyring) via `secret-tool` CLI.
+ * Windows: Not yet supported.
+ *
+ * The .app embeds a provisioning profile that grants the application-identifier
+ * + keychain-access-groups entitlement macOS requires for kSecAttrSynchronizable
+ * writes (iCloud Keychain). For device-local writes the helper is invoked with
+ * the `nosync` arg.
  */
 import { fileURLToPath } from 'url';
 import { execFileSync, spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { linuxBackend } from './linux.js';
 const SERVICE_PREFIX = 'agents-cli';
 const REF_PATTERN = /^(keychain|env|file|exec):(.+)$/s;
 /** Parse a bundle value into either a literal string or a typed secret ref. */
@@ -31,11 +35,18 @@ export function parseBundleValue(raw) {
 export function serializeRef(ref) {
     return `${ref.provider}:${ref.value}`;
 }
-function assertMacOS() {
-    if (process.platform !== 'darwin') {
-        throw new Error('Keychain-based secrets require macOS. On Linux, use environment variables or .env files instead. Native Linux credential store support is planned.');
+function assertSupportedPlatform() {
+    if (process.platform !== 'darwin' && process.platform !== 'linux') {
+        throw new Error('Secure credential storage requires macOS or Linux. ' +
+            'On Windows, use environment variables or .env files instead.');
     }
 }
+function isLinux() {
+    return process.platform === 'linux';
+}
+function isMacOS() {
+    return process.platform === 'darwin';
+}
 /** Build the keychain item name for a profile provider token. */
 export function profileKeychainItem(provider) {
     return `${SERVICE_PREFIX}.${provider}.token`;
@@ -73,12 +84,14 @@ export function setKeychainBackendForTest(b) {
 // holds the keychain-access-groups entitlement macOS requires for
 // kSecAttrSynchronizable. Enumeration also goes through the .app because the
 // security CLI doesn't expose listing by service prefix.
-/** Check if a keychain item exists (macOS only). */
+/** Check if a keychain/keyring item exists. */
 export function hasKeychainToken(item, sync = false) {
     if (backend)
         return backend.has(item, sync);
-    assertMacOS();
-    // Try security first (no prompts for local items), fall back to binary for synced items.
+    assertSupportedPlatform();
+    if (isLinux())
+        return linuxBackend.has(item, sync);
+    // macOS: Try security first (no prompts for local items), fall back to binary for synced items.
     if (spawnSync('security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0)
@@ -89,12 +102,14 @@ export function hasKeychainToken(item, sync = false) {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
 }
-/** Retrieve a secret value from the macOS Keychain. Throws if not found. */
+/** Retrieve a secret value from the keychain/keyring. Throws if not found. */
 export function getKeychainToken(item, sync = false) {
     if (backend)
         return backend.get(item, sync);
-    assertMacOS();
-    // Try security first (no prompts for local items)
+    assertSupportedPlatform();
+    if (isLinux())
+        return linuxBackend.get(item, sync);
+    // macOS: Try security first (no prompts for local items)
     const secResult = spawnSync('security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
         stdio: ['ignore', 'pipe', 'pipe'],
     });
@@ -119,17 +134,24 @@ export function getKeychainToken(item, sync = false) {
         throw new Error(`Keychain item '${item}' exists but is empty.`);
     return token;
 }
-/** Store or update a secret value in the macOS Keychain. iCloud-synced when sync=true. */
+/** Store or update a secret value in the keychain/keyring. iCloud-synced when sync=true (macOS only). */
 export function setKeychainToken(item, value, sync = false) {
     if (backend) {
         backend.set(item, value, sync);
         return;
     }
-    assertMacOS();
+    assertSupportedPlatform();
     if (!value || !value.trim())
         throw new Error('Secret value is empty.');
     if (/[\r\n]/.test(value))
         throw new Error('Secret value contains newlines, which are not supported.');
+    if (/[\x00=\r\n]/.test(item))
+        throw new Error('Secret item name contains invalid characters.');
+    if (isLinux()) {
+        linuxBackend.set(item, value, sync);
+        return;
+    }
+    // macOS path
     if (sync) {
         const bin = ensureKeychainHelper();
         const result = spawnSync(bin, ['set', item, os.userInfo().username], {
@@ -153,11 +175,14 @@ export function setKeychainToken(item, value, sync = false) {
         throw new Error(`Failed to write keychain item '${item}' (exit ${result.status}).`);
     }
 }
-/** Delete a keychain item. Returns true if it existed. */
+/** Delete a keychain/keyring item. Returns true if it existed. */
 export function deleteKeychainToken(item, sync = false) {
     if (backend)
         return backend.delete(item, sync);
-    assertMacOS();
+    assertSupportedPlatform();
+    if (isLinux())
+        return linuxBackend.delete(item, sync);
+    // macOS path
     if (sync) {
         const bin = ensureKeychainHelper();
         return spawnSync(bin, ['delete', item, os.userInfo().username], {
@@ -171,11 +196,14 @@ export function deleteKeychainToken(item, sync = false) {
 function quoteForSecurityCli(s) {
     return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
 }
-/** Enumerate keychain item service names whose name starts with the given prefix. */
+/** Enumerate keychain/keyring item names starting with the given prefix. */
 export function listKeychainItems(prefix) {
     if (backend)
         return backend.list(prefix);
-    assertMacOS();
+    assertSupportedPlatform();
+    if (isLinux())
+        return linuxBackend.list(prefix);
+    // macOS path
     const bin = ensureKeychainHelper();
     const result = spawnSync(bin, ['list', prefix], {
         stdio: ['ignore', 'pipe', 'pipe'],

package/dist/lib/secrets/linux.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Linux secret storage via libsecret (GNOME Keyring / Secret Service API).
+ *
+ * Uses `secret-tool` CLI which is part of libsecret-tools package.
+ * On Ubuntu: apt install libsecret-tools
+ *
+ * Secrets are stored with:
+ *   service = "agents-cli"
+ *   account = username
+ *   item = the secret identifier
+ */
+import type { KeychainBackend } from './index.js';
+/**
+ * secret-tool lookup attributes:
+ *   service=agents-cli account=<user> item=<itemName>
+ */
+export declare function hasSecretToolToken(item: string): boolean;
+export declare function getSecretToolToken(item: string): string;
+export declare function setSecretToolToken(item: string, value: string): void;
+export declare function deleteSecretToolToken(item: string): boolean;
+/**
+ * List secrets by prefix. secret-tool doesn't have a list command,
+ * so we use secret-tool search which outputs in a specific format.
+ */
+export declare function listSecretToolItems(prefix: string): string[];
+/** KeychainBackend implementation for Linux using secret-tool */
+export declare const linuxBackend: KeychainBackend;

package/dist/lib/secrets/linux.js

@@ -0,0 +1,161 @@
+/**
+ * Linux secret storage via libsecret (GNOME Keyring / Secret Service API).
+ *
+ * Uses `secret-tool` CLI which is part of libsecret-tools package.
+ * On Ubuntu: apt install libsecret-tools
+ *
+ * Secrets are stored with:
+ *   service = "agents-cli"
+ *   account = username
+ *   item = the secret identifier
+ */
+import { spawnSync } from 'child_process';
+import * as os from 'os';
+const SERVICE = 'agents-cli';
+function secretToolAvailable() {
+    const result = spawnSync('which', ['secret-tool'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return result.status === 0;
+}
+let checkedAvailability = false;
+let isAvailable = false;
+function ensureSecretTool() {
+    if (!checkedAvailability) {
+        isAvailable = secretToolAvailable();
+        checkedAvailability = true;
+    }
+    if (!isAvailable) {
+        throw new Error('secret-tool not found. Install libsecret-tools:\n' +
+            '  Ubuntu/Debian: sudo apt install libsecret-tools\n' +
+            '  Fedora: sudo dnf install libsecret\n' +
+            '  Arch: sudo pacman -S libsecret');
+    }
+}
+/**
+ * secret-tool lookup attributes:
+ *   service=agents-cli account=<user> item=<itemName>
+ */
+export function hasSecretToolToken(item) {
+    ensureSecretTool();
+    const user = os.userInfo().username;
+    const result = spawnSync('secret-tool', [
+        'lookup',
+        'service', SERVICE,
+        'account', user,
+        'item', item,
+    ], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return result.status === 0 && result.stdout?.toString().trim().length > 0;
+}
+export function getSecretToolToken(item) {
+    ensureSecretTool();
+    const user = os.userInfo().username;
+    const result = spawnSync('secret-tool', [
+        'lookup',
+        'service', SERVICE,
+        'account', user,
+        'item', item,
+    ], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0) {
+        throw new Error(`Secret '${item}' not found in keyring.`);
+    }
+    const token = result.stdout?.toString().trim();
+    if (!token) {
+        throw new Error(`Secret '${item}' exists but is empty.`);
+    }
+    return token;
+}
+export function setSecretToolToken(item, value) {
+    ensureSecretTool();
+    if (!value || !value.trim())
+        throw new Error('Secret value is empty.');
+    const user = os.userInfo().username;
+    const label = `agents-cli: ${item}`;
+    // secret-tool store reads value from stdin
+    const result = spawnSync('secret-tool', [
+        'store',
+        '--label', label,
+        'service', SERVICE,
+        'account', user,
+        'item', item,
+    ], {
+        input: value,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0) {
+        const stderr = result.stderr?.toString().trim();
+        throw new Error(`Failed to store secret '${item}': ${stderr || 'unknown error'}\n` +
+            'Make sure GNOME Keyring or another Secret Service provider is running.');
+    }
+}
+export function deleteSecretToolToken(item) {
+    ensureSecretTool();
+    const user = os.userInfo().username;
+    const result = spawnSync('secret-tool', [
+        'clear',
+        'service', SERVICE,
+        'account', user,
+        'item', item,
+    ], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    // secret-tool clear returns 0 whether the item existed or not.
+    // This matches the macOS behavior where delete is idempotent.
+    return result.status === 0;
+}
+/**
+ * List secrets by prefix. secret-tool doesn't have a list command,
+ * so we use secret-tool search which outputs in a specific format.
+ */
+export function listSecretToolItems(prefix) {
+    ensureSecretTool();
+    // secret-tool search outputs attributes, one item per block
+    const result = spawnSync('secret-tool', [
+        'search',
+        '--all',
+        'service', SERVICE,
+    ], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0) {
+        return [];
+    }
+    const output = result.stdout?.toString() || '';
+    const items = [];
+    // Parse output format:
+    // [/org/freedesktop/secrets/collection/login/1]
+    // label = agents-cli: myitem
+    // ...
+    // attribute.item = myitem
+    const itemRegex = /attribute\.item\s*=\s*(.+)/g;
+    let match;
+    while ((match = itemRegex.exec(output)) !== null) {
+        const itemName = match[1].trim();
+        if (itemName.startsWith(prefix)) {
+            items.push(itemName);
+        }
+    }
+    return [...new Set(items)]; // dedupe
+}
+/** KeychainBackend implementation for Linux using secret-tool */
+export const linuxBackend = {
+    has(item, _sync) {
+        return hasSecretToolToken(item);
+    },
+    get(item, _sync) {
+        return getSecretToolToken(item);
+    },
+    set(item, value, _sync) {
+        setSecretToolToken(item, value);
+    },
+    delete(item, _sync) {
+        return deleteSecretToolToken(item);
+    },
+    list(prefix) {
+        return listSecretToolItems(prefix);
+    },
+};

package/dist/lib/session/active.d.ts

@@ -8,7 +8,10 @@ export interface ActiveSession {
     pid?: number;
     sessionId?: string;
     cwd?: string;
+    /** User-given name from /rename command. */
     label?: string;
+    /** First meaningful line of the initial prompt (extracted topic). */
+    topic?: string;
     sessionFile?: string;
     startedAtMs?: number;
     status: ActiveStatus;

package/dist/lib/session/active.js

@@ -2,7 +2,7 @@
  * Active-session detection across every context an agent can run in:
  *
  *   - `terminal` — agents launched from VS Code / Cursor / Codium via the
- *     agents-cli extension. Published to `~/.agents/runtime/live-terminals.json`
+ *     agents-cli extension. Published to `~/.agents/.cache/terminals/live-terminals.json`
  *     with PID + session UUID per entry.
  *   - `teams`    — agents spawned by `agents teams add`, tracked in
  *     `~/.agents/teams/agents/<id>/meta.json` with a PID the manager polls.
@@ -23,10 +23,12 @@ import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { listActiveTasks } from '../cloud/store.js';
 import { AgentManager } from '../teams/agents.js';
-import { getUserAgentsDir } from '../state.js';
+import { getTerminalsDir } from '../state.js';
+import { buildClaudeLabelMap } from './discover.js';
+import { extractSessionTopic } from './prompt.js';
 const execFileAsync = promisify(execFile);
 const HOME = os.homedir();
-const LIVE_TERMINALS_FILE = path.join(getUserAgentsDir(), 'runtime', 'live-terminals.json');
+const LIVE_TERMINALS_FILE = path.join(getTerminalsDir(), 'live-terminals.json');
 /**
  * A process is classified `running` if its session file was touched in the
  * last 2 minutes. Every Claude/Codex tool-call appends an event, so a
@@ -80,9 +82,9 @@ function readLiveTerminals() {
     }
     return Array.from(merged.values());
 }
-/** Convert an absolute cwd to the Claude-project folder name (slashes → dashes). */
+/** Convert an absolute cwd to the Claude-project folder name (slashes and dots → dashes). */
 function claudeProjectDirName(cwd) {
-    return cwd.replace(/\//g, '-');
+    return cwd.replace(/[/.]/g, '-');
 }
 /**
  * Locate the active Claude session file for a process. If we know the session
@@ -126,6 +128,79 @@ function classifyActivity(sessionFile) {
         return 'running';
     }
 }
+/**
+ * Extract the first user message's content from a Claude JSONL file.
+ * Reads only the first ~50 lines for speed, since the user message is
+ * typically near the top (after system/queue events).
+ */
+function extractClaudeUserText(parsed) {
+    const msg = parsed.message;
+    if (!msg?.content)
+        return undefined;
+    const content = Array.isArray(msg.content) ? msg.content : [msg.content];
+    const texts = [];
+    for (const block of content) {
+        if (typeof block === 'string')
+            texts.push(block);
+        else if (block?.type === 'text' && typeof block.text === 'string')
+            texts.push(block.text);
+    }
+    return texts.join('\n').trim() || undefined;
+}
+function quickExtractTopic(sessionFile) {
+    let fd;
+    try {
+        fd = fs.openSync(sessionFile, 'r');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const chunkSize = 256 * 1024;
+        const maxBytes = 2 * 1024 * 1024;
+        let buffer = '';
+        let totalRead = 0;
+        let linesChecked = 0;
+        const maxLines = 30;
+        while (totalRead < maxBytes && linesChecked < maxLines) {
+            const chunk = Buffer.alloc(chunkSize);
+            const bytesRead = fs.readSync(fd, chunk, 0, chunkSize, totalRead);
+            if (bytesRead === 0)
+                break;
+            totalRead += bytesRead;
+            buffer += chunk.toString('utf8', 0, bytesRead);
+            let lineStart = 0;
+            let lineEnd;
+            while ((lineEnd = buffer.indexOf('\n', lineStart)) !== -1 && linesChecked < maxLines) {
+                const line = buffer.slice(lineStart, lineEnd);
+                lineStart = lineEnd + 1;
+                linesChecked++;
+                if (!line.trim())
+                    continue;
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (parsed.type === 'user') {
+                    const text = extractClaudeUserText(parsed);
+                    if (text) {
+                        const topic = extractSessionTopic(text);
+                        if (topic)
+                            return topic;
+                    }
+                }
+            }
+            buffer = buffer.slice(lineStart);
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return undefined;
+}
 /** Live teams teammates. Reuses AgentManager which already polls PIDs via `kill -0`. */
 export async function listTeamsActive() {
     const mgr = new AgentManager();
@@ -135,6 +210,7 @@ export async function listTeamsActive() {
         const sessionFile = a.agentType === 'claude' && a.cwd
             ? findClaudeSessionFile(a.cwd, sessionId ?? undefined)
             : undefined;
+        const topic = sessionFile ? quickExtractTopic(sessionFile) : undefined;
         return {
             context: 'teams',
             kind: a.agentType,
@@ -142,6 +218,7 @@ export async function listTeamsActive() {
             sessionId,
             cwd: a.cwd ?? undefined,
             label: a.name ?? undefined,
+            topic,
             sessionFile,
             startedAtMs: a.startedAt.getTime(),
             status: classifyActivity(sessionFile),
@@ -160,10 +237,16 @@ export async function listTerminalsActive() {
     const procByPid = new Map();
     for (const r of await readProcessTable())
         procByPid.set(r.pid, r);
+    // Build label map from Claude's sessions/*.json for /rename support
+    const labelMap = buildClaudeLabelMap();
     return entries.map((t) => {
         const sessionFile = t.kind === 'claude' && t.cwd
             ? findClaudeSessionFile(t.cwd, t.sessionId)
             : undefined;
+        // Prefer label from live terminal, fall back to Claude's session label
+        const label = t.label ?? (t.sessionId ? labelMap.get(t.sessionId) : undefined) ?? undefined;
+        // Extract topic from session file (first meaningful user message)
+        const topic = sessionFile ? quickExtractTopic(sessionFile) : undefined;
         return {
             context: 'terminal',
             kind: t.kind,
@@ -171,7 +254,8 @@ export async function listTerminalsActive() {
             pid: t.pid,
             sessionId: t.sessionId,
             cwd: t.cwd ?? undefined,
-            label: t.label ?? undefined,
+            label,
+            topic,
             sessionFile,
             startedAtMs: t.startedAtMs,
             status: classifyActivity(sessionFile),
@@ -355,6 +439,7 @@ export async function listUnattributedActive(attributed) {
         const { pid, kind } = candidates[i];
         const cwd = cwds[i];
         const sessionFile = kind === 'claude' && cwd ? findClaudeSessionFile(cwd) : undefined;
+        const topic = sessionFile ? quickExtractTopic(sessionFile) : undefined;
         const host = detectHost(pid, procByPid);
         const context = host && UI_HOSTS.has(host) ? 'terminal' : 'headless';
         out.push({
@@ -363,6 +448,7 @@ export async function listUnattributedActive(attributed) {
             host,
             pid,
             cwd,
+            topic,
             sessionFile,
             status: classifyActivity(sessionFile),
         });

package/dist/lib/session/cloud.js

@@ -13,10 +13,10 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
-import { getAgentsDir } from '../state.js';
+import { getCacheDir } from '../state.js';
 const PROXY_BASE = process.env.RUSH_PROXY_BASE ?? 'https://api.prix.dev';
 const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
-const CLOUD_CACHE_DIR = path.join(getAgentsDir(), 'cache', 'cloud-runs');
+const CLOUD_CACHE_DIR = path.join(getCacheDir(), 'cloud-runs');
 function readToken() {
     if (!fs.existsSync(USER_YAML)) {
         throw new Error('Not logged in to Rush. Run `rush login` first.');

package/dist/lib/session/db.d.ts

@@ -137,3 +137,7 @@ export declare function getRowCount(): {
     sessions: number;
     textRows: number;
 };
+/** Count sessions older than the given timestamp (for dry-run previews). */
+export declare function countSessionsOlderThan(cutoffMs: number): number;
+/** Delete sessions older than the given timestamp. Returns the number of rows deleted. */
+export declare function deleteSessionsOlderThan(cutoffMs: number): number;

package/dist/lib/session/db.js

@@ -9,9 +9,9 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import Database from '../sqlite.js';
-import { getUserAgentsDir } from '../state.js';
-const SESSIONS_DIR = path.join(getUserAgentsDir(), 'sessions');
-const DB_PATH = path.join(SESSIONS_DIR, 'sessions.db');
+import { getSessionsDir, getSessionsDbPath } from '../state.js';
+const SESSIONS_DIR = getSessionsDir();
+const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. */
 const SCHEMA_VERSION = 5;
 /**
@@ -151,6 +151,11 @@ export function getDB() {
     db.pragma('journal_mode = WAL');
     db.pragma('synchronous = NORMAL');
     db.pragma('temp_store = MEMORY');
+    // Wait up to 10s instead of failing immediately on SQLITE_BUSY. Multiple
+    // agents (CLIs, indexers, hooks) all open this DB concurrently; without a
+    // busy timeout, parallel writers throw "database is locked" the moment one
+    // holds the write lock. 10s is well above any realistic transaction here.
+    db.pragma('busy_timeout = 10000');
     db.exec(SCHEMA);
     const current = db.prepare(`SELECT value FROM meta WHERE key = 'schema_version'`).get();
     const currentVersion = current ? parseInt(current.value, 10) : 0;
@@ -638,3 +643,29 @@ export function getRowCount() {
     const textRows = db.prepare(`SELECT COUNT(*) AS c FROM session_text`).get().c;
     return { sessions, textRows };
 }
+/** Count sessions older than the given timestamp (for dry-run previews). */
+export function countSessionsOlderThan(cutoffMs) {
+    const db = getDB();
+    const cutoffIso = new Date(cutoffMs).toISOString();
+    const row = db.prepare(`SELECT COUNT(*) AS n FROM sessions WHERE timestamp < ?`).get(cutoffIso);
+    return row.n;
+}
+/** Delete sessions older than the given timestamp. Returns the number of rows deleted. */
+export function deleteSessionsOlderThan(cutoffMs) {
+    const db = getDB();
+    const cutoffIso = new Date(cutoffMs).toISOString();
+    const rows = db.prepare(`SELECT id, file_path FROM sessions WHERE timestamp < ?`).all(cutoffIso);
+    if (rows.length === 0)
+        return 0;
+    const txn = db.transaction(() => {
+        for (const { id, file_path } of rows) {
+            db.prepare(`DELETE FROM session_text WHERE session_id = ?`).run(id);
+            db.prepare(`DELETE FROM sessions WHERE id = ?`).run(id);
+            if (file_path) {
+                db.prepare(`DELETE FROM scan_ledger WHERE file_path = ?`).run(canonicalLedgerKey(file_path));
+            }
+        }
+    });
+    txn();
+    return rows.length;
+}