@phnx-labs/agents-cli 1.21.2 → 1.22.0

package/dist/lib/session/db.js

@@ -12,14 +12,20 @@ import Database from '../sqlite.js';
 import { parseSession } from './parse.js';
 import { extractRecentDirectoriesTouched, extractTodoProgressFromEvents } from './state.js';
 import { getSessionsDir, getSessionsDbPath } from '../state.js';
+import { query as queryEvents } from '../events.js';
 import { machineForSessionFile } from './origin-machine.js';
 import { loadSessionActorIndex, readSessionActorRecord } from './actor-sidecar.js';
+import { toolCallsFromEvents } from './tool-calls.js';
+import { persistToolCalls, purgeToolCalls, toolEvidenceSourcePath } from './tool-store.js';
+import { extractSkills, extractSlashCommands } from './highlights.js';
+import { resolveResource } from '../resources.js';
+import { discoverPlugins } from '../plugins.js';
 const SESSIONS_DIR = getSessionsDir();
 const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/05-sessions.md calls the constant the source of truth). */
-export const SCHEMA_VERSION = 22;
+export const SCHEMA_VERSION = 30;
 /**
  * Canonicalize a file path for use as a scan_ledger key. The same physical
  * session file is reachable via multiple aliases — `~/.claude/projects/x.jsonl`
@@ -85,7 +91,9 @@ CREATE TABLE IF NOT EXISTS sessions (
   linear_project TEXT,
   linear_project_url TEXT,
   actor TEXT,
-  initiated_by TEXT
+  initiated_by TEXT,
+  used_browser INTEGER,
+  used_computer INTEGER
 );
 CREATE INDEX IF NOT EXISTS idx_sessions_timestamp ON sessions(timestamp DESC);
 CREATE INDEX IF NOT EXISTS idx_sessions_cwd ON sessions(cwd);
@@ -140,6 +148,96 @@ CREATE TABLE IF NOT EXISTS dir_ledger (
   entry_count INTEGER NOT NULL,
   scanned_at INTEGER NOT NULL
 );
+
+-- One redacted evidence row per tool call. The ordinal is assigned in
+-- transcript order and is stable across incremental appends.
+CREATE TABLE IF NOT EXISTS tool_calls (
+  call_key TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  ordinal INTEGER NOT NULL,
+  source_call_id TEXT,
+  timestamp TEXT NOT NULL,
+  tool TEXT NOT NULL,
+  input TEXT NOT NULL,
+  outcome TEXT NOT NULL,
+  exit_code INTEGER,
+  status_code INTEGER,
+  error_code TEXT,
+  output TEXT,
+  error TEXT,
+  parse_error TEXT,
+  evidence_bytes INTEGER NOT NULL,
+  UNIQUE(session_id, ordinal)
+);
+CREATE INDEX IF NOT EXISTS idx_tool_calls_session ON tool_calls(session_id, ordinal);
+CREATE INDEX IF NOT EXISTS idx_tool_calls_tool ON tool_calls(tool COLLATE NOCASE);
+CREATE INDEX IF NOT EXISTS idx_tool_calls_outcome ON tool_calls(outcome);
+
+CREATE TABLE IF NOT EXISTS tool_call_programs (
+  call_key TEXT NOT NULL,
+  program TEXT NOT NULL COLLATE NOCASE,
+  PRIMARY KEY(call_key, program)
+);
+CREATE INDEX IF NOT EXISTS idx_tool_call_programs_program ON tool_call_programs(program, call_key);
+
+-- Ordered static program sites retain repeated commands within one Bash call.
+-- The complete redacted command stays on tool_calls.input; these rows contain
+-- only the normalized program and whether it is a wrapper or effective target.
+CREATE TABLE IF NOT EXISTS tool_program_occurrences (
+  call_key TEXT NOT NULL,
+  occurrence_ordinal INTEGER NOT NULL,
+  program TEXT NOT NULL COLLATE NOCASE,
+  role TEXT NOT NULL CHECK(role IN ('wrapper', 'effective')),
+  PRIMARY KEY(call_key, occurrence_ordinal)
+);
+CREATE INDEX IF NOT EXISTS idx_tool_program_occurrences_program
+  ON tool_program_occurrences(program, call_key);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS tool_call_text USING fts5(
+  call_key UNINDEXED,
+  tool,
+  input,
+  output,
+  error,
+  tokenize = 'trigram'
+);
+
+-- Independent of scan_ledger: schema migration never forces the normal
+-- session index to reread history. Existing transcripts are backfilled only
+-- by the explicit, bounded agents sessions backfill tools command.
+CREATE TABLE IF NOT EXISTS tool_scan_ledger (
+  session_id TEXT PRIMARY KEY,
+  file_path TEXT NOT NULL UNIQUE,
+  file_mtime_ms INTEGER NOT NULL,
+  file_size INTEGER NOT NULL,
+  extractor_version INTEGER NOT NULL,
+  indexed_at INTEGER NOT NULL,
+  call_count INTEGER NOT NULL,
+  evidence_bytes INTEGER NOT NULL
+);
+
+-- Skill/slash-command usage per session (#12), computed from a session's
+-- parsed transcript (extractSkills / extractSlashCommands, session/highlights.ts)
+-- and joined at write time against the currently-installed resource/plugin
+-- (resolveResource / discoverPlugins) for provenance — repo_root + snapshot_sha
+-- answer "which repo, which commit installed this skill/command", plugin/source
+-- answer "which plugin, which DotAgents layer". A resource renamed or uninstalled
+-- since the session ran leaves plugin/source/repo_root/snapshot_sha NULL rather
+-- than a stale guess. One row per (session, kind, name); count is how many
+-- times that skill/command fired in the session.
+CREATE TABLE IF NOT EXISTS session_resource_usage (
+  session_id TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  name TEXT NOT NULL,
+  plugin TEXT,
+  source TEXT,
+  repo_root TEXT,
+  snapshot_sha TEXT,
+  count INTEGER NOT NULL DEFAULT 1,
+  PRIMARY KEY (session_id, kind, name)
+);
+CREATE INDEX IF NOT EXISTS idx_session_resource_usage_kind_name ON session_resource_usage(kind, name);
+CREATE INDEX IF NOT EXISTS idx_session_resource_usage_plugin ON session_resource_usage(plugin);
 `;
 let dbInstance = null;
 /**
@@ -361,12 +459,11 @@ function migrateSchema(db, fromVersion) {
             .prepare(`SELECT id, agent, file_path FROM sessions WHERE machine IS NULL OR machine = ''`)
             .all();
         const upd = db.prepare(`UPDATE sessions SET machine = ? WHERE id = ?`);
-        const txn = db.transaction((items) => {
-            for (const r of items) {
-                upd.run(machineForSessionFile(r.file_path, r.agent), r.id);
-            }
-        });
-        txn(rows);
+        // migrateSchema runs inside getDB's schema transaction, so these writes
+        // deliberately share that transaction instead of opening a nested one.
+        for (const row of rows) {
+            upd.run(machineForSessionFile(row.file_path, row.agent), row.id);
+        }
     }
     if (fromVersion < 19) {
         // v18 → v19: actor provenance (RUSH-2018) — who initiated the session and
@@ -401,11 +498,186 @@ function migrateSchema(db, fromVersion) {
         db.exec(`DELETE FROM scan_ledger; DELETE FROM dir_ledger;`);
     }
     if (fromVersion < 22) {
+        // v21 → v22: persist the transcript's aggregate tool-call count.
         const cols = db.prepare(`PRAGMA table_info(sessions)`).all();
         if (!cols.some(c => c.name === 'tool_call_count'))
             db.exec(`ALTER TABLE sessions ADD COLUMN tool_call_count INTEGER`);
         db.exec(`DELETE FROM scan_ledger; DELETE FROM dir_ledger;`);
     }
+    if (fromVersion < 23) {
+        // v22 → v23: persist usedBrowser/usedComputer (#11) so the sessions picker
+        // preview can trust a positive detection instead of re-deriving it from a
+        // transcript regex on every render. Computed from a sessionId-scoped read
+        // of the events log (see detectToolUsage), not from the parsed transcript,
+        // so no ledger wipe is needed here — a rescan re-derives them regardless.
+        //
+        // Deliberately NO DEFAULT (NULL on ALTER, for every pre-existing row):
+        // NULL means "not yet computed by this scanner" (a legacy row), distinct
+        // from a real, computed 0/false.
+        const cols = db.prepare(`PRAGMA table_info(sessions)`).all();
+        if (!cols.some(c => c.name === 'used_browser'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN used_browser INTEGER`);
+        if (!cols.some(c => c.name === 'used_computer'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN used_computer INTEGER`);
+    }
+    if (fromVersion < 24) {
+        // v23 → v24: session_resource_usage (#12) — skill/slash-command usage per
+        // session, joined against the currently-installed resource/plugin for
+        // provenance. No ledger wipe: writeResourceUsage() owns this table.
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS session_resource_usage (
+        session_id TEXT NOT NULL,
+        kind TEXT NOT NULL,
+        name TEXT NOT NULL,
+        plugin TEXT,
+        source TEXT,
+        repo_root TEXT,
+        snapshot_sha TEXT,
+        count INTEGER NOT NULL DEFAULT 1,
+        PRIMARY KEY (session_id, kind, name)
+      );
+      CREATE INDEX IF NOT EXISTS idx_session_resource_usage_kind_name ON session_resource_usage(kind, name);
+      CREATE INDEX IF NOT EXISTS idx_session_resource_usage_plugin ON session_resource_usage(plugin);
+    `);
+    }
+    if (fromVersion < 25) {
+        // v24 → v25: tool-call evidence uses an independent ledger. Do not clear
+        // scan_ledger or dir_ledger: normal session listing stays warm, while tool
+        // history is filled once on demand.
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS tool_calls (
+        call_key TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        ordinal INTEGER NOT NULL,
+        source_call_id TEXT,
+        timestamp TEXT NOT NULL,
+        tool TEXT NOT NULL,
+        input TEXT NOT NULL,
+        outcome TEXT NOT NULL,
+        exit_code INTEGER,
+        status_code INTEGER,
+        error_code TEXT,
+        output TEXT,
+        error TEXT,
+        parse_error TEXT,
+        evidence_bytes INTEGER NOT NULL,
+        UNIQUE(session_id, ordinal)
+      );
+      CREATE INDEX IF NOT EXISTS idx_tool_calls_session ON tool_calls(session_id, ordinal);
+      CREATE INDEX IF NOT EXISTS idx_tool_calls_tool ON tool_calls(tool COLLATE NOCASE);
+      CREATE INDEX IF NOT EXISTS idx_tool_calls_outcome ON tool_calls(outcome);
+      CREATE TABLE IF NOT EXISTS tool_call_programs (
+        call_key TEXT NOT NULL,
+        program TEXT NOT NULL COLLATE NOCASE,
+        PRIMARY KEY(call_key, program)
+      );
+      CREATE INDEX IF NOT EXISTS idx_tool_call_programs_program ON tool_call_programs(program, call_key);
+      CREATE VIRTUAL TABLE IF NOT EXISTS tool_call_text USING fts5(
+        call_key UNINDEXED,
+        tool,
+        input,
+        output,
+        error,
+        tokenize = 'unicode61 remove_diacritics 2'
+      );
+      CREATE TABLE IF NOT EXISTS tool_scan_ledger (
+        file_path TEXT PRIMARY KEY,
+        file_mtime_ms INTEGER NOT NULL,
+        file_size INTEGER NOT NULL,
+        extractor_version INTEGER NOT NULL,
+        indexed_at INTEGER NOT NULL,
+        call_count INTEGER NOT NULL,
+        evidence_bytes INTEGER NOT NULL
+      );
+    `);
+    }
+    if (fromVersion < 26) {
+        // v25 → v26: make append accounting O(changed calls), including empty
+        // deltas, instead of reading every historical evidence row per append.
+        const callCols = db.prepare(`PRAGMA table_info(tool_calls)`).all();
+        if (!callCols.some((column) => column.name === 'evidence_bytes')) {
+            db.exec(`ALTER TABLE tool_calls ADD COLUMN evidence_bytes INTEGER NOT NULL DEFAULT 0`);
+        }
+        const ledgerCols = db.prepare(`PRAGMA table_info(tool_scan_ledger)`).all();
+        if (!ledgerCols.some((column) => column.name === 'evidence_bytes')) {
+            db.exec(`ALTER TABLE tool_scan_ledger ADD COLUMN evidence_bytes INTEGER NOT NULL DEFAULT 0`);
+        }
+        // The first tool schema existed only in prerelease development builds. Force its tool
+        // evidence through one bounded rebuild rather than trusting zeroed totals.
+        db.exec(`DELETE FROM tool_scan_ledger`);
+    }
+    if (fromVersion < 27) {
+        // v26 → v27: the original unicode word tokenizer could not prefilter the
+        // substring semantics promised by input/output/error queries. Rebuild only
+        // the derived FTS table from already-redacted call rows; transcripts and
+        // both scan ledgers remain warm.
+        db.exec(`
+      DROP TABLE IF EXISTS tool_call_text;
+      CREATE VIRTUAL TABLE tool_call_text USING fts5(
+        call_key UNINDEXED,
+        tool,
+        input,
+        output,
+        error,
+        tokenize = 'trigram'
+      );
+      INSERT INTO tool_call_text (call_key, tool, input, output, error)
+      SELECT call_key, tool, input, coalesce(output, ''), coalesce(error, '')
+      FROM tool_calls;
+    `);
+    }
+    if (fromVersion < 28) {
+        // v27 → v28: retain every static program occurrence instead of only the
+        // distinct program set. The source transcript is rebuilt only by the
+        // explicit tools backfill; normal session and directory ledgers stay warm.
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS tool_program_occurrences (
+        call_key TEXT NOT NULL,
+        occurrence_ordinal INTEGER NOT NULL,
+        program TEXT NOT NULL COLLATE NOCASE,
+        role TEXT NOT NULL CHECK(role IN ('wrapper', 'effective')),
+        PRIMARY KEY(call_key, occurrence_ordinal)
+      );
+      CREATE INDEX IF NOT EXISTS idx_tool_program_occurrences_program
+        ON tool_program_occurrences(program, call_key);
+      DELETE FROM tool_scan_ledger;
+    `);
+    }
+    if (fromVersion < 29) {
+        // v28 → v29: coverage and query planning address the independent tool
+        // ledger by session id. Rebuild only this derived ledger so a tool query
+        // never has to resolve or stat transcript paths.
+        db.exec(`
+      DROP TABLE tool_scan_ledger;
+      CREATE TABLE tool_scan_ledger (
+        session_id TEXT PRIMARY KEY,
+        file_path TEXT NOT NULL UNIQUE,
+        file_mtime_ms INTEGER NOT NULL,
+        file_size INTEGER NOT NULL,
+        extractor_version INTEGER NOT NULL,
+        indexed_at INTEGER NOT NULL,
+        call_count INTEGER NOT NULL,
+        evidence_bytes INTEGER NOT NULL
+      );
+    `);
+    }
+    if (fromVersion < 30) {
+        // v29 → v30: prerelease tool-index builds temporarily used schema versions
+        // later owned by independent main migrations. Repair from the physical
+        // schema because a v29 marker alone cannot prove these columns are present.
+        const cols = new Set(db.prepare(`PRAGMA table_info(sessions)`).all().map((column) => column.name));
+        if (!cols.has('tool_call_count')) {
+            db.exec(`
+        ALTER TABLE sessions ADD COLUMN tool_call_count INTEGER;
+        DELETE FROM scan_ledger;
+        DELETE FROM dir_ledger;
+      `);
+        }
+        if (!cols.has('used_browser'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN used_browser INTEGER`);
+        if (!cols.has('used_computer'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN used_computer INTEGER`);
+    }
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export function getDB() {
@@ -413,24 +685,37 @@ export function getDB() {
         return dbInstance;
     fs.mkdirSync(SESSIONS_DIR, { recursive: true });
     const db = new Database(DB_PATH);
-    db.pragma('journal_mode = WAL');
-    db.pragma('synchronous = NORMAL');
-    db.pragma('temp_store = MEMORY');
-    // Wait up to 30s instead of failing immediately on SQLITE_BUSY. Multiple
+    // Wait up to 30s instead of failing immediately on SQLITE_BUSY. Install the
+    // handler before journal_mode: concurrent first opens can race for its schema
+    // lock, before a later busy_timeout would have a chance to wait. Multiple
     // agents (CLIs, skills, hooks) open this DB concurrently. The first scan of
     // a new version home can take longer than 10s; concurrent callers need enough
     // headroom to wait. The ledger-recheck in upsertSessionsBatch makes
     // subsequent writers near-instant, so 30s is a rarely-reached safety net.
     db.pragma('busy_timeout = 30000');
+    db.pragma('journal_mode = WAL');
+    db.pragma('synchronous = NORMAL');
+    db.pragma('temp_store = MEMORY');
     db.exec(SCHEMA);
-    const current = db.prepare(`SELECT value FROM meta WHERE key = 'schema_version'`).get();
-    const currentVersion = current ? parseInt(current.value, 10) : 0;
-    if (!current) {
+    const readSchemaVersion = () => {
+        const row = db.prepare(`SELECT value FROM meta WHERE key = 'schema_version'`).get();
+        return row ? parseInt(row.value, 10) : undefined;
+    };
+    const currentVersion = readSchemaVersion();
+    if (currentVersion === undefined) {
         db.prepare(`INSERT OR IGNORE INTO meta(key, value) VALUES ('schema_version', ?)`).run(String(SCHEMA_VERSION));
     }
     else if (currentVersion < SCHEMA_VERSION) {
-        migrateSchema(db, currentVersion);
-        db.prepare(`INSERT OR REPLACE INTO meta(key, value) VALUES ('schema_version', ?)`).run(String(SCHEMA_VERSION));
+        // Re-read after BEGIN IMMEDIATE acquires the writer lock. A second process
+        // may have completed the migration while this connection was waiting.
+        const migrate = db.transaction(() => {
+            const lockedVersion = readSchemaVersion();
+            if (lockedVersion === undefined || lockedVersion >= SCHEMA_VERSION)
+                return;
+            migrateSchema(db, lockedVersion);
+            db.prepare(`INSERT OR REPLACE INTO meta(key, value) VALUES ('schema_version', ?)`).run(String(SCHEMA_VERSION));
+        });
+        migrate();
     }
     // Index last_activity only after the column is guaranteed to exist — fresh DBs
     // get it from CREATE TABLE above, existing pre-v8 DBs from the migration just
@@ -769,7 +1054,7 @@ const upsertSessionStmt = (db) => db.prepare(`
     file_path, file_mtime_ms, file_size, scanned_at, is_team_origin,
     pr_url, pr_number, worktree_slug, ticket_id, spawned_team, plan, todos,
     recent_directories_touched, linear_project, linear_project_url, machine,
-    actor, initiated_by
+    actor, initiated_by, used_browser, used_computer
   ) VALUES (
     @id, @short_id, @agent, @origin, @routine_name, @routine_run_id,
     @version, @account, @timestamp, @last_activity,
@@ -778,7 +1063,7 @@ const upsertSessionStmt = (db) => db.prepare(`
     @file_path, @file_mtime_ms, @file_size, @scanned_at, @is_team_origin,
     @pr_url, @pr_number, @worktree_slug, @ticket_id, @spawned_team, @plan, @todos,
     @recent_directories_touched, @linear_project, @linear_project_url, @machine,
-    @actor, @initiated_by
+    @actor, @initiated_by, @used_browser, @used_computer
   )
   ON CONFLICT(id) DO UPDATE SET
     short_id = excluded.short_id,
@@ -823,6 +1108,8 @@ const upsertSessionStmt = (db) => db.prepare(`
     plan = excluded.plan,
     todos = excluded.todos,
     recent_directories_touched = excluded.recent_directories_touched,
+    used_browser = excluded.used_browser,
+    used_computer = excluded.used_computer,
     linear_project = CASE
       WHEN excluded.ticket_id IS NOT sessions.ticket_id THEN excluded.linear_project
       ELSE COALESCE(excluded.linear_project, sessions.linear_project)
@@ -841,11 +1128,124 @@ const upsertSessionStmt = (db) => db.prepare(`
     actor = COALESCE(sessions.actor, excluded.actor),
     initiated_by = COALESCE(sessions.initiated_by, excluded.initiated_by)
 `);
+/**
+ * Did this session emit at least one browser/computer-automation event?
+ * A scoped, sessionId-filtered read of the events log — NOT a re-scan of the
+ * (potentially huge) transcript — since browser.navigate / browser.screenshot
+ * / computer.action are recorded there via events.ts's emit(), keyed by the
+ * same session id that is this row's `meta.id` (the provenance floor stamps
+ * AGENT_SESSION_ID/AGENTS_SESSION_ID on every such event at emit time).
+ *
+ * Called independently of {@link enrichCachedSessionMeta} (which SKIPS
+ * claude/codex entries in the batch path because their caller already parsed
+ * the transcript for todos/recentDirectoriesTouched) — this never touches the
+ * transcript, so it must run for every agent, every time.
+ */
+function detectToolUsage(sessionId) {
+    const usedBrowser = queryEvents({ sessionId, eventTypes: ['browser.navigate', 'browser.screenshot'], limit: 1 }).length > 0;
+    const usedComputer = queryEvents({ sessionId, eventTypes: ['computer.action'], limit: 1 }).length > 0;
+    return { usedBrowser, usedComputer };
+}
+const deleteResourceUsageStmt = (db) => db.prepare(`DELETE FROM session_resource_usage WHERE session_id = ?`);
+const insertResourceUsageStmt = (db) => db.prepare(`
+  INSERT INTO session_resource_usage (session_id, kind, name, plugin, source, repo_root, snapshot_sha, count)
+  VALUES (@session_id, @kind, @name, @plugin, @source, @repo_root, @snapshot_sha, @count)
+`);
+/**
+ * Resolve a skill/slash-command's provenance for `session_resource_usage`
+ * (#12). A flat (non-namespaced) resource resolves via resolveResource()'s
+ * project/user/system/extra-repo scan. A namespaced one (`plugin:name`, e.g.
+ * `rush:design` — the shape both a plugin skill's `args.skill` and a plugin
+ * command's SessionEvent.slashCommand carry) is plugin-owned and lives under
+ * the plugin's own directory, invisible to resolveResource()'s flat scan —
+ * resolved instead against the already-discovered plugin list. Neither found
+ * (renamed or uninstalled since the session ran) returns all-undefined
+ * rather than a stale guess.
+ */
+function resolveResourceProvenance(kind, name, cwd, plugins) {
+    const listOf = (p) => (kind === 'skills' ? p.skills : p.commands);
+    const colonIdx = name.indexOf(':');
+    if (colonIdx > 0) {
+        const pluginName = name.slice(0, colonIdx);
+        const shortName = name.slice(colonIdx + 1);
+        const plugin = plugins.find((p) => p.name === pluginName && listOf(p).includes(shortName));
+        if (!plugin)
+            return {};
+        return { plugin: plugin.name, source: plugin.marketplace, repoRoot: plugin.repoRoot, snapshotSha: plugin.snapshotSha };
+    }
+    const resolved = resolveResource(kind, name, cwd);
+    if (resolved)
+        return { source: resolved.source, repoRoot: resolved.repoRoot, snapshotSha: resolved.snapshotSha };
+    const plugin = plugins.find((p) => listOf(p).includes(name));
+    if (!plugin)
+        return {};
+    return { plugin: plugin.name, source: plugin.marketplace, repoRoot: plugin.repoRoot, snapshotSha: plugin.snapshotSha };
+}
+/**
+ * Persist already-computed skill/slash-command tallies for a session (#12)
+ * into `session_resource_usage`, replacing any prior rows for it (a rescan's
+ * usage supersedes the old — same replace-on-upsert shape as the FTS text
+ * below). `discoverPlugins()` (real I/O: manifest + directory reads) only
+ * runs when there is actually a skill/command to resolve, so a session with
+ * neither pays nothing beyond the DELETE.
+ *
+ * Split from {@link writeResourceUsage} so a caller that already has the
+ * tallies (claude/codex's incremental accumulator — see
+ * ClaudeParseState.skillEvents/slashCommandEvents, threaded onto
+ * SessionMeta.skillsUsed/slashCommandsUsed) can write without re-parsing the
+ * transcript to re-derive them.
+ *
+ * Deliberately NOT wrapped in its own `db.transaction()`: better-sqlite3
+ * (this repo's wrapper included) does not support nested transactions, and
+ * `upsertSessionsBatch` calls this from INSIDE its own outer transaction. A
+ * standalone caller (enrichCachedSessionMeta, outside any transaction) still
+ * gets each statement committed individually — a crash between the DELETE
+ * and an INSERT self-heals on the next rescan, the same risk profile as any
+ * other un-batched write in this file.
+ */
+function writeResourceUsageFromTallies(sessionId, skills, commands, cwd) {
+    const db = getDB();
+    const del = deleteResourceUsageStmt(db);
+    const ins = insertResourceUsageStmt(db);
+    del.run(sessionId);
+    if (skills.length === 0 && commands.length === 0)
+        return;
+    const plugins = discoverPlugins({ cwd });
+    for (const { name, count } of skills) {
+        const prov = resolveResourceProvenance('skills', name, cwd, plugins);
+        ins.run({
+            session_id: sessionId, kind: 'skill', name, count,
+            plugin: prov.plugin ?? null, source: prov.source ?? null,
+            repo_root: prov.repoRoot ?? null, snapshot_sha: prov.snapshotSha ?? null,
+        });
+    }
+    for (const { name, count } of commands) {
+        const bare = name.replace(/^\//, '');
+        const prov = resolveResourceProvenance('commands', bare, cwd, plugins);
+        ins.run({
+            session_id: sessionId, kind: 'command', name: bare, count,
+            plugin: prov.plugin ?? null, source: prov.source ?? null,
+            repo_root: prov.repoRoot ?? null, snapshot_sha: prov.snapshotSha ?? null,
+        });
+    }
+}
+/**
+ * Persist skill/slash-command usage for a session (#12) by deriving the
+ * tallies from a full parsed transcript. Used by {@link enrichCachedSessionMeta}
+ * (every `upsertSession()` call, and `upsertSessionsBatch` for every harness
+ * EXCEPT claude/codex, which pre-compute skillsUsed/slashCommandsUsed via
+ * their incremental accumulator instead — see writeResourceUsageFromTallies
+ * and the call site in upsertSessionsBatch).
+ */
+function writeResourceUsage(sessionId, events, cwd) {
+    writeResourceUsageFromTallies(sessionId, extractSkills(events), extractSlashCommands(events), cwd);
+}
 function enrichCachedSessionMeta(meta) {
     if (!meta.filePath)
         return meta;
     try {
         const events = parseSession(meta.filePath, meta.agent);
+        writeResourceUsage(meta.id, events, meta.cwd);
         return {
             ...meta,
             todos: extractTodoProgressFromEvents(events),
@@ -903,6 +1303,7 @@ export function upsertSession(meta, content, scan) {
     // row AND backfills one indexed null-first (before its sidecar existed), while a
     // rescan carrying no actor still keeps the stored owner.
     const actorRec = meta.actor ? undefined : readSessionActorRecord(meta.id);
+    const toolUsage = detectToolUsage(meta.id);
     const db = getDB();
     const { upsert, delText, insText, readLabel } = stmts(db);
     const row = {
@@ -946,6 +1347,8 @@ export function upsertSession(meta, content, scan) {
         machine: resolveMachine(meta),
         actor: meta.actor ?? actorRec?.actor ?? null,
         initiated_by: meta.initiatedBy ?? actorRec?.initiatedBy ?? null,
+        used_browser: toolUsage.usedBrowser ? 1 : 0,
+        used_computer: toolUsage.usedComputer ? 1 : 0,
     };
     const txn = db.transaction(() => {
         upsert.run(row);
@@ -994,9 +1397,38 @@ export function upsertSessionsBatch(entries) {
     const byPath = new Map(entries
         .filter(e => e.scan && e.meta.filePath)
         .map(e => [canonicalLedgerKey(e.meta.filePath), e]));
-    const enrichedEntries = entries.map(entry => entry.meta.agent === 'claude' || entry.meta.agent === 'codex'
-        ? entry
-        : { ...entry, meta: enrichCachedSessionMeta(entry.meta) });
+    const enrichedEntries = entries.map(entry => {
+        if (entry.meta.agent === 'claude' || entry.meta.agent === 'codex' || !entry.meta.filePath)
+            return entry;
+        try {
+            const toolSourcePath = toolEvidenceSourcePath(entry.meta.filePath, entry.meta.agent);
+            const toolScan = toolSourcePath === entry.meta.filePath
+                ? entry.scan
+                : (() => {
+                    const stat = fs.statSync(toolSourcePath);
+                    return { fileMtimeMs: stat.mtimeMs, fileSize: stat.size };
+                })();
+            // Non-resumable harnesses already parse here for todos/recent dirs. Derive
+            // the tool index from those same in-memory events: no second file read.
+            const events = parseSession(entry.meta.filePath, entry.meta.agent);
+            writeResourceUsage(entry.meta.id, events, entry.meta.cwd);
+            return {
+                ...entry,
+                meta: {
+                    ...entry.meta,
+                    todos: extractTodoProgressFromEvents(events),
+                    recentDirectoriesTouched: extractRecentDirectoriesTouched(events, entry.meta.cwd),
+                },
+                toolCalls: toolCallsFromEvents(events),
+                toolScan,
+                toolIndexMode: 'replace',
+            };
+        }
+        catch {
+            return entry;
+        }
+    });
+    const writtenEntries = [];
     const txn = db.transaction((items) => {
         // Re-read the ledger now that we hold the write lock. Any file committed
         // by a concurrent process since our pre-scan is visible here.
@@ -1016,7 +1448,8 @@ export function upsertSessionsBatch(entries) {
                 }
             }
         }
-        for (const { meta, content, scan, parserState, contentText } of items) {
+        for (const entry of items) {
+            const { meta, content, scan, parserState, contentText } = entry;
             if (alreadyIndexed.has(meta.id))
                 continue;
             // Per-row guard: one malformed session (e.g. a required field that resolves to
@@ -1026,6 +1459,15 @@ export function upsertSessionsBatch(entries) {
             // back when the error escapes `fn`, so catching + skipping here leaves the txn valid
             // and committable. We deliberately do NOT stamp the ledger for a skipped row, so the
             // next scan re-tries it (self-healing once the underlying parser is fixed).
+            const toolUsage = detectToolUsage(meta.id);
+            // claude/codex skip enrichCachedSessionMeta above (preserving their
+            // resumable-parse optimization) — write their pre-computed
+            // skillsUsed/slashCommandsUsed (folded incrementally by discover.ts's
+            // accumulator) here instead. Every other harness already got this
+            // write from enrichCachedSessionMeta() in the .map() above.
+            if (meta.agent === 'claude' || meta.agent === 'codex') {
+                writeResourceUsageFromTallies(meta.id, meta.skillsUsed ?? [], meta.slashCommandsUsed ?? [], meta.cwd);
+            }
             try {
                 upsert.run({
                     id: meta.id,
@@ -1068,6 +1510,8 @@ export function upsertSessionsBatch(entries) {
                     machine: resolveMachine(meta),
                     actor: meta.actor ?? actorIndex.get(meta.id)?.actor ?? null,
                     initiated_by: meta.initiatedBy ?? actorIndex.get(meta.id)?.initiatedBy ?? null,
+                    used_browser: toolUsage.usedBrowser ? 1 : 0,
+                    used_computer: toolUsage.usedComputer ? 1 : 0,
                 });
                 delText.run(meta.id);
                 insText.run(meta.id, 
@@ -1077,6 +1521,7 @@ export function upsertSessionsBatch(entries) {
                 if (scan && meta.filePath) {
                     ledger.run(canonicalLedgerKey(meta.filePath), scan.fileMtimeMs, scan.fileSize, now, parserState ?? null, contentText ?? null);
                 }
+                writtenEntries.push(entry);
             }
             catch (err) {
                 if (process.stderr.isTTY) {
@@ -1086,6 +1531,20 @@ export function upsertSessionsBatch(entries) {
         }
     });
     txn(enrichedEntries);
+    // Tool evidence shares the transcript parse above but owns an independent
+    // transaction/ledger. If this write fails, the normal session row remains
+    // valid and ensureToolIndex retries from the missing tool ledger later.
+    for (const entry of writtenEntries) {
+        const toolScan = entry.toolScan ?? entry.scan;
+        if (!toolScan || !entry.toolCalls)
+            continue;
+        try {
+            persistToolCalls(db, entry.meta, entry.toolCalls, toolScan, entry.toolIndexMode ?? 'replace');
+        }
+        catch {
+            // Boundary is intentionally retryable via tool_scan_ledger.
+        }
+    }
 }
 /**
  * Sync labels for a set of sessions. For each id in the map, if the stored
@@ -1260,6 +1719,11 @@ function rowToMeta(row) {
         // Narrow the free-text column to the known kinds; an unexpected value maps
         // to undefined rather than being asserted as a valid kind.
         initiatedBy: row.initiated_by === 'human' || row.initiated_by === 'agent' ? row.initiated_by : undefined,
+        // NULL = never computed by this scanner (legacy row) — leave undefined so
+        // the sessions picker knows to fall back to the transcript-regex detection
+        // instead of trusting a false "never used browser/computer".
+        usedBrowser: row.used_browser === null ? undefined : row.used_browser === 1,
+        usedComputer: row.used_computer === null ? undefined : row.used_computer === 1,
     };
 }
 function parseJsonColumn(value) {
@@ -1392,6 +1856,21 @@ function buildSessionWhere(options) {
     if (options.onlyTeamOrigin) {
         where.push('IFNULL(is_team_origin, 0) = 1');
     }
+    // #12: join against session_resource_usage. A subquery IN, not a real JOIN
+    // on the base SELECT, keeps `SELECT * FROM sessions` untouched for every
+    // other caller of buildSessionWhere() (countSessions, the usage rollup, …)
+    // that never wants a skill/plugin filter.
+    if (options.skill) {
+        where.push(`id IN (
+      SELECT session_id FROM session_resource_usage
+      WHERE kind = 'skill' AND (name = ? COLLATE NOCASE OR name LIKE ? COLLATE NOCASE)
+    )`);
+        params.push(options.skill, `%:${options.skill}`);
+    }
+    if (options.plugin) {
+        where.push(`id IN (SELECT session_id FROM session_resource_usage WHERE plugin = ? COLLATE NOCASE)`);
+        params.push(options.plugin);
+    }
     const clause = where.length > 0 ? `WHERE ${where.join(' AND ')}` : '';
     return { clause, params };
 }
@@ -1414,13 +1893,26 @@ export function querySessions(options = {}) {
             : 'ORDER BY IFNULL(last_activity, timestamp) DESC, timestamp DESC';
     const sql = `SELECT * FROM sessions ${clause} ${orderClause} ${limitClause}`;
     const rows = db.prepare(sql).all(...params);
+    if (options.skipExistenceCheck) {
+        const trimmed = options.limit ? rows.slice(0, options.limit) : rows;
+        return trimmed.map(rowToMeta);
+    }
     // Belt-and-suspenders: drop rows whose JSONL no longer exists on disk. The
     // authoritative fix is to keep file_path in sync (see updateSessionFilePaths
     // callers), but skipping vanished rows here prevents phantom sessions from
     // surfacing in the Factory UI if any code path forgets to rewrite (#136).
     // Synthetic rows (OpenClaw channels/cron — see scanOpenClawIncremental) carry
     // an empty file_path and are exempt; they're keyed by CLI output, not files.
-    const live = rows.filter(r => !r.file_path || fs.existsSync(r.file_path));
+    const missing = rows.filter(r => r.file_path && !fs.existsSync(r.file_path));
+    if (missing.length > 0) {
+        const purge = db.transaction(() => {
+            for (const row of missing)
+                purgeToolCalls(db, row.id);
+        });
+        purge();
+    }
+    const missingIds = new Set(missing.map((row) => row.id));
+    const live = rows.filter(r => !r.file_path || !missingIds.has(r.id));
     const trimmed = options.limit ? live.slice(0, options.limit) : live;
     return trimmed.map(rowToMeta);
 }