@krtclcdy/tersio 2.25.5 → 2.25.6

package/dist/extensions/shared/usage-ledger.js

@@ -1,8 +1,9 @@
-// Shared usage ledger: append-only JSON lines, read by the CLI, `/tersio`, and the Dashboard. Best-effort; corrupt lines are skipped on read.
+// Usage ledger: append-only JSON lines, read by the CLI, `/tersio`, and the Dashboard. Corrupt lines are skipped.
 import fs from 'node:fs';
 import path from 'node:path';
-import { homeDir, isPiProcess, piAgentDir, resolveRtkBinary, tersioDataPath } from './utils.js';
 import { execFileSync } from 'node:child_process';
+import { homeDir, isPiProcess, piAgentDir, resolveRtkBinary, tersioDataPath } from './utils.js';
+import { sqliteRead } from './sqlite.js';
 export function ledgerPath() {
     const override = process.env.TERSIO_USAGE_FILE;
     if (override)
@@ -50,7 +51,7 @@ function stampMs(ts) {
 export function durOf(v) {
     return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : undefined;
 }
-// Measured cost: usage.cost.total, or a bare number in old fixtures. Anything else means unrecorded, which is deliberately not 0.
+// Measured cost: usage.cost.total, or a bare number in old fixtures. Anything else means unrecorded, not 0.
 export function costOf(usage) {
     const c = usage.cost;
     if (typeof c === 'number')
@@ -87,7 +88,7 @@ export function sessionsDirs() {
     const override = process.env.TERSIO_SESSIONS_DIR;
     if (override)
         return [override];
-    // Both hosts, not just the running one: a session on pi is missing from the dashboard entirely if we stop at the first directory that exists.
+    // Both hosts, not just the running one: a pi session is missing if we stop at the first existing directory.
     const dirs = isPiProcess()
         ? [path.join(piAgentDir(), 'sessions'), path.join(homeDir(), '.omp', 'agent', 'sessions')]
         : [path.join(homeDir(), '.omp', 'agent', 'sessions'), path.join(piAgentDir(), 'sessions')];
@@ -129,22 +130,20 @@ export function opencodeDbPath() {
     catch { /* fall through to the platform default */ }
     return path.join(homeDir(), 'Library', 'Application Support', 'opencode', 'opencode.db');
 }
-// Two on-disk shapes: legacy `message` (role/modelID/providerID live inside `data`),
-// current `session_message` (role in the `type` column, model under data.model).
-// Scalars only: the `data` blob holds newlines and tabs, which the sqlite3 CLI would split.
+// `message` vs `session_message`: read scalars only, since the blob's newlines break the row-per-line output.
 const OC_DB_ORDER = ' ORDER BY time_created;';
-const OC_DB_COLUMNS = 'json_extract(data,\'$.time.created\'), json_extract(data,\'$.time.completed\'),' +
+const OC_DB_COLUMNS = 'json_extract(data,\'$.time.created\'), json_extract(data,\'$.time.streamed\'), json_extract(data,\'$.time.completed\'),' +
     ' json_extract(data,\'$.tokens.input\'), json_extract(data,\'$.tokens.output\'),' +
     ' json_extract(data,\'$.tokens.cache.read\'), json_extract(data,\'$.tokens.cache.write\'), json_extract(data,\'$.cost\')';
-const ocDbLegacy = (since) => `SELECT id, time_created, json_extract(data,'$.role'), json_extract(data,'$.providerID'), json_extract(data,'$.modelID'), ${OC_DB_COLUMNS}` +
+const OC_DB_TOOLS = '(SELECT group_concat(json_extract(j.value,\'$.name\')) FROM json_each(data,\'$.content\') j' +
+    ' WHERE json_extract(j.value,\'$.type\')=\'tool\')';
+const ocDbLegacy = (since) => `SELECT id, time_created, json_extract(data,'$.role'), json_extract(data,'$.providerID'), json_extract(data,'$.modelID'), ${OC_DB_COLUMNS}, ${OC_DB_TOOLS}` +
     ` FROM message WHERE json_extract(data,'$.role')='assistant' AND time_created > ${since}${OC_DB_ORDER}`;
-const ocDbCurrent = (since) => `SELECT id, time_created, 'assistant', json_extract(data,'$.model.providerID'), json_extract(data,'$.model.id'), ${OC_DB_COLUMNS}` +
+const ocDbCurrent = (since) => `SELECT id, time_created, 'assistant', json_extract(data,'$.model.providerID'), json_extract(data,'$.model.id'), ${OC_DB_COLUMNS}, ${OC_DB_TOOLS}` +
     ` FROM session_message WHERE type='assistant' AND time_created > ${since}${OC_DB_ORDER}`;
 // A re-scan window covers tokens that land after the row was created, so a late fill is not lost.
 export const OPENCODE_DB_OVERLAP_MS = 3_600_000;
-// execFileSync caps output at 1MB; a busy table clears it in one SELECT.
-export const SQLITE_READ_BUFFER = 50 * 1024 * 1024;
-// Empty when sqlite3 is absent or the db is unreadable; that is a sync skip, not a failure.
+// Empty when no SQLite is available or the db is unreadable; that is a sync skip, not a failure.
 export function readOpencodeDbRows(db, sinceMs) {
     if (!Number.isFinite(sinceMs))
         return [];
@@ -153,7 +152,7 @@ export function readOpencodeDbRows(db, sinceMs) {
             return [];
         const since = Math.max(0, Math.floor(sinceMs));
         // Separate calls: a db holding only one table must not cancel the other.
-        const run = (sql) => execFileSync('sqlite3', ['-separator', '\t', '-readonly', db, sql], { encoding: 'utf8', timeout: 30000, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: SQLITE_READ_BUFFER });
+        const run = (sql) => sqliteRead(db, sql);
         let out = '';
         try {
             out += run(ocDbLegacy(since));
@@ -167,17 +166,18 @@ export function readOpencodeDbRows(db, sinceMs) {
         for (const line of out.split('\n')) {
             if (!line.trim())
                 continue;
-            const [id, created, role, providerID, modelID, tCreated, tCompleted, input, output, cacheRead, cacheWrite, cost] = line.split('\t');
+            const [id, created, role, providerID, modelID, tCreated, tStreamed, tCompleted, input, output, cacheRead, cacheWrite, cost, tools] = line.split('\t');
             const n = (v) => (v !== undefined && v !== '' && Number.isFinite(Number(v)) ? Number(v) : undefined);
             rows.push({
                 id,
                 created: Number(created),
+                tools: tools ?? '',
                 row: {
                     role,
                     modelID,
                     providerID,
                     tokens: { input: n(input), output: n(output), cache: { read: n(cacheRead), write: n(cacheWrite) } },
-                    time: { created: n(tCreated), completed: n(tCompleted) },
+                    time: { created: n(tCreated), streamed: n(tStreamed), completed: n(tCompleted) },
                     cost: n(cost),
                 },
             });
@@ -225,7 +225,7 @@ const RTK_ELIGIBLE_HEADS = new Set([
 export function newSessionAccum() {
     return { byModel: {}, byDay: {}, byDayModel: {}, byTool: {}, byModelMessages: {}, byHost: {}, byAgent: {}, byAgentMessages: {}, byModelMeasured: {}, byModelCostMessages: {}, totals: zeroBreakdown(), messages: 0, costMeasured: 0, recent: [], recentFloor: Number.POSITIVE_INFINITY };
 }
-export function ingestSessionRow(accum, model, usage, ts, durMs, run, toolNames, host, id, agent) {
+export function ingestSessionRow(accum, model, usage, ts, durMs, run, toolNames, host, id, agent, ttftMs) {
     const watermark = readResetWatermark();
     const ms = ts === undefined ? NaN : typeof ts === 'number' ? ts : Date.parse(ts);
     if (watermark > 0 && (!Number.isFinite(ms) || ms < watermark))
@@ -250,11 +250,9 @@ export function ingestSessionRow(accum, model, usage, ts, durMs, run, toolNames,
     const num = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0);
     if (Number.isFinite(ms)) {
         const outcome = run ?? { st: 'completed' };
-        // The store holds every message ever recorded, but only the newest few are ever read. Skip
-        // anything older than the floor, and re-read the floor when the list is full, so a 50k-row
-        // store costs 2000 rows of memory instead of 50k.
+        // Only the newest rows are read: skip below the floor, and a 50k-row store costs 2000 rows of memory.
         if (accum.recent.length < RECENT_LIMIT || ms >= accum.recentFloor) {
-            accum.recent.push({ m: key, i: num(usage.input), o: num(usage.output), t: ms, d: durOf(durMs), h: host, cr: num(usage.cacheRead), cw: num(usage.cacheWrite), usd: costOf(usage), st: outcome.st, code: outcome.code, note: outcome.note, id });
+            accum.recent.push({ m: key, i: num(usage.input), o: num(usage.output), t: ms, d: durOf(durMs), tf: durOf(ttftMs), h: host, cr: num(usage.cacheRead), cw: num(usage.cacheWrite), usd: costOf(usage), st: outcome.st, code: outcome.code, note: outcome.note, id });
             if (accum.recent.length > RECENT_LIMIT) {
                 let drop = 0;
                 for (let k = 1; k < accum.recent.length; k += 1)
@@ -326,7 +324,7 @@ export function classifySessionLine(row) {
         const command = part.arguments?.command;
         tools.push(`bash:${leadBinary(command)}`);
     }
-    return { kind: 'assistant_row', model, usage: msg.usage, durMs: typeof msg.duration === 'number' ? msg.duration : computedDur, run: statusOf(msg), tools };
+    return { kind: 'assistant_row', model, usage: msg.usage, durMs: typeof msg.duration === 'number' ? msg.duration : computedDur, ttftMs: typeof msg.ttft === 'number' ? msg.ttft : undefined, run: statusOf(msg), tools };
 }
 // True when at least one token bucket holds a positive finite count.
 export function hasPositiveUsage(usage) {
@@ -337,6 +335,25 @@ export function hasPositiveUsage(usage) {
     }
     return false;
 }
+/** Tool names an OpenCode message called; v2 passes SQL's comma-joined string as the blob holds newlines. */
+export function opencodeToolNames(message, joined) {
+    if (joined !== undefined)
+        return joined === '' ? [] : joined.split(',');
+    const parts = message?.content;
+    if (!Array.isArray(parts))
+        return [];
+    const names = [];
+    for (const part of parts) {
+        if (!part || typeof part !== 'object')
+            continue;
+        if (part.type !== 'tool')
+            continue;
+        const name = part.name;
+        if (typeof name === 'string' && name)
+            names.push(name);
+    }
+    return names;
+}
 // One OpenCode message file; assistant rows carry the token buckets.
 export function classifyOpencodeMessage(obj) {
     if (!obj || typeof obj !== 'object' || obj.role !== 'assistant')
@@ -358,14 +375,16 @@ export function classifyOpencodeMessage(obj) {
     const num = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : undefined);
     const created = num(obj.time?.created);
     const completed = num(obj.time?.completed);
+    // `streamed` is when the first token arrived, so it is the host's own first-token latency.
+    const streamed = num(obj.time?.streamed);
     return {
         model: `opencode/${provider}/${model}`,
         usage,
         ms: created,
         durMs: created !== undefined && completed !== undefined && completed > created ? completed - created : undefined,
+        ttftMs: created !== undefined && streamed !== undefined && streamed > created ? streamed - created : undefined,
     };
 }
-// One OpenCode message file into the shared accum. The msg id is the file name.
 export function processOpencodeFile(accum, text, file) {
     let obj;
     try {
@@ -374,18 +393,19 @@ export function processOpencodeFile(accum, text, file) {
     catch {
         return;
     }
-    const parsed = classifyOpencodeMessage(obj);
+    const message = obj;
+    const parsed = classifyOpencodeMessage(message);
     if (!parsed)
         return;
     const id = file ? path.basename(file).replace(/\.[^.]+$/, '') || undefined : undefined;
-    ingestSessionRow(accum, parsed.model, parsed.usage, parsed.ms, parsed.durMs, { st: 'completed' }, undefined, 'opencode', id, 'main');
+    ingestSessionRow(accum, parsed.model, parsed.usage, parsed.ms, parsed.durMs, { st: 'completed' }, opencodeToolNames(message), 'opencode', id, 'main', parsed.ttftMs);
 }
 // One v2 message row into the shared accum. The msg id is the row primary key.
 export function ingestOpencodeDbRow(accum, row) {
     const parsed = classifyOpencodeMessage(row.row);
     if (!parsed)
         return;
-    ingestSessionRow(accum, parsed.model, parsed.usage, parsed.ms, parsed.durMs, { st: 'completed' }, undefined, 'opencode', row.id, 'main');
+    ingestSessionRow(accum, parsed.model, parsed.usage, parsed.ms, parsed.durMs, { st: 'completed' }, opencodeToolNames(row.row, row.tools), 'opencode', row.id, 'main', parsed.ttftMs);
 }
 // Fold `:free`/`-free` suffixes and case variants into one chart key.
 export function canonicalModelId(model) {
@@ -396,8 +416,7 @@ export function messageRowId(row) {
     const id = row.id;
     return typeof id === 'string' && id ? id : undefined;
 }
-// Vendor names mirror the dashboard map; CLI needs names only. Family first:
-// gateway segments shadow it (minimaxai holds xai, gemma rides nvidia).
+// Vendor names mirror the dashboard map; family first, so gateway segments shadow it (minimaxai holds xai).
 const VENDOR_RES = [
     [/inclusionai|ling-/i, 'InclusionAI'],
     [/minimax/i, 'MiniMax'],
@@ -533,9 +552,7 @@ export function hostOfSessionFile(file) {
         return 'opencode';
     return 'pi';
 }
-// Which agent ran a session file, from its own `session` row: a transcript with a parent
-// session is a subagent's, and everything else is the main agent. The row is the host's own
-// record, so a mirrored transcript carries the same answer as the stats database.
+// A transcript with a parent session ran as a subagent; the host's own row, so a mirror answers the same.
 export function agentOfSessionText(text) {
     if (!text.includes('parentSession'))
         return 'main';
@@ -652,7 +669,7 @@ export function processSessionText(accum, state, text, host, agent) {
             }
             if (parsed.kind !== 'assistant_row' || !parsed.model || !parsed.usage)
                 continue;
-            ingestSessionRow(accum, parsed.model, parsed.usage, row.timestamp, parsed.durMs, parsed.run, parsed.tools, host, rid, agent);
+            ingestSessionRow(accum, parsed.model, parsed.usage, row.timestamp, parsed.durMs, parsed.run, parsed.tools, host, rid, agent, parsed.ttftMs);
         }
         catch { /* skip corrupt lines */ }
     }
@@ -696,16 +713,12 @@ export function leadBinary(command) {
     }
     return 'bash';
 }
-// --- Pricing lives in ./pricing.ts (live LiteLLM cache + fallback table) ---
+// Pricing lives in ./pricing.ts (live LiteLLM cache + fallback table).
 import { DEFAULT_PRICE, PRICE_TIERS_FIRM, canonicalPriceId, priceFor, pricesOverridePath, refreshPricesIfStale } from './pricing.js';
 import { co2GramsFor, energyWhFor } from './carbon.js';
 export { DEFAULT_PRICE, PRICE_TIERS_FIRM, priceFor, pricesOverridePath, refreshPricesIfStale };
 export { co2GramsFor, energyWhFor };
-/**
- * Price one model's tokens. `measured` is the cost the host reported for those tokens; it outranks
- * every rate card, because it is the only figure from the party that billed. Pass undefined rather
- * than 0 for a cost nobody reported: `costOf` keeps the two apart.
- */
+/** Price one model's tokens; `measured` outranks every rate card, so pass undefined when unreported. */
 export function usdCost(t, model, measured) {
     const m = 1 / 1_000_000;
     if (measured !== undefined) {
@@ -727,8 +740,7 @@ export function usdCost(t, model, measured) {
     };
     return {
         usd: buckets.input + buckets.output + buckets.cacheRead + buckets.cacheWrite,
-        // A tier the caller cannot stand behind is not a price. `tail` and `default` are estimates,
-        // and a report that sums them beside measured cost reads as a bill it is not.
+        // `tail`/`default` are estimates; summing them beside measured cost reads as a bill it is not.
         priced: PRICE_TIERS_FIRM.includes(hit.tier),
         tier: hit.tier,
         buckets,
@@ -759,7 +771,7 @@ export function readUsage() {
     }
     return rows;
 }
-// Delete the ledger file and return the rows cleared. Tersio-owned data only: transcripts and the RTK database are never touched.
+// Delete the ledger file and return the rows cleared. Tersio-owned data only: transcripts and the RTK database stay.
 export function clearUsageLedger() {
     const rows = readUsage().length;
     try {

package/dist/extensions/shared/usage-store.js

@@ -1,8 +1,8 @@
-// extensions/shared/usage-store.ts — tersio-owned usage.db. A cache of the live parse, never a fork; missing sqlite3 → sync false / read null.
-import { execFileSync } from 'node:child_process';
+// usage-store.ts — tersio-owned usage.db. A cache of the live parse, not a fork; no SQLite → sync false / read null.
 import fs from 'node:fs';
 import path from 'node:path';
-import { RECENT_LIMIT, SQLITE_READ_BUFFER, canonicalModelId, classifySessionLine, classifyOpencodeMessage, costOf, durOf, agentOfSessionText, hostOfSessionFile, ingestSessionRow, messageRowId, OPENCODE_DB_OVERLAP_MS, opencodeDbPath, opencodeSessionsDir, newSessionAccum, readOpencodeDbRows, sessionsDirs, walkJsonl, } from './usage-ledger.js';
+import { sqliteExec, sqliteRead } from './sqlite.js';
+import { RECENT_LIMIT, canonicalModelId, classifySessionLine, classifyOpencodeMessage, costOf, durOf, agentOfSessionText, hostOfSessionFile, ingestSessionRow, messageRowId, OPENCODE_DB_OVERLAP_MS, opencodeDbPath, opencodeSessionsDir, newSessionAccum, opencodeToolNames, readOpencodeDbRows, sessionsDirs, walkJsonl, } from './usage-ledger.js';
 import { tersioDataPath } from './utils.js';
 import { MODEL_ALIASES } from './pricing.js';
 import { tersioSettingsFile } from './plugin-settings.js';
@@ -24,25 +24,21 @@ function nullNum(v) {
 function nullStr(v) {
     return v === undefined ? 'NULL' : esc(v);
 }
+// A failed INSERT stops before COMMIT, so it leaves no DELETEs behind.
 function run(db, sql) {
-    // -bail stops the script before COMMIT, so a failed INSERT never leaves DELETEs behind.
-    execFileSync('sqlite3', ['-bail', db, sql], { stdio: ['ignore', 'ignore', 'ignore'], timeout: 30000 });
+    sqliteExec(db, sql);
 }
 function query(db, sql) {
-    const out = execFileSync('sqlite3', ['-separator', '\t', db, sql], {
-        encoding: 'utf8',
-        timeout: 30000,
-        stdio: ['ignore', 'pipe', 'ignore'],
-        maxBuffer: SQLITE_READ_BUFFER,
-    });
-    return out
+    return sqliteRead(db, sql)
         .split('\n')
         .filter((line) => line.trim())
         .map((line) => line.split('\t'));
 }
 // Bump on a parse change: unchanged transcripts are never re-read.
-const PARSER_VERSION = '12';
-// A re-parse that keeps less than half the rows means transcripts vanished mid-migration; the backup is restored instead of publishing the loss.
+const PARSER_VERSION = '13';
+/** OpenCode rows gained tool names; re-read by id, since a PARSER_VERSION bump drops rotated history. */
+const OPENCODE_TOOLS_VERSION = '1';
+// A re-parse keeping under half the rows means transcripts vanished mid-migration; the backup is restored instead.
 const REPARSE_GUARD_RATIO = 0.5;
 let guardReport = null;
 /** Why the last sync refused to publish a re-parse, if it did. */
@@ -52,18 +48,14 @@ export function reparseGuardReport() {
 const SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS meta (k TEXT PRIMARY KEY, v TEXT NOT NULL);` +
     `CREATE TABLE IF NOT EXISTS files (id INTEGER PRIMARY KEY AUTOINCREMENT, path TEXT UNIQUE NOT NULL, mtime REAL NOT NULL, size INTEGER NOT NULL);` +
     `CREATE TABLE IF NOT EXISTS messages (file_id INTEGER NOT NULL REFERENCES files(id), t REAL, model TEXT NOT NULL,` +
-    ` i INTEGER NOT NULL, o INTEGER NOT NULL, d REAL, cr INTEGER NOT NULL, cw INTEGER NOT NULL,` +
+    ` i INTEGER NOT NULL, o INTEGER NOT NULL, d REAL, tf REAL, cr INTEGER NOT NULL, cw INTEGER NOT NULL,` +
     ` usd REAL, st TEXT NOT NULL, code REAL, note TEXT, tools TEXT NOT NULL DEFAULT '[]', h TEXT, a TEXT, id TEXT);` +
-    // Every read filters or orders by one of these three. Without them each sync and each read
-    // walks the whole table: the watermark scan, the day buckets, and the recent list all scan.
+    // Every read filters or orders by one of these three; without them each sync and read scans the table.
     `CREATE INDEX IF NOT EXISTS idx_messages_file ON messages(file_id);` +
     `CREATE INDEX IF NOT EXISTS idx_messages_t ON messages(t);` +
     `CREATE INDEX IF NOT EXISTS idx_messages_h_t ON messages(h, t);` +
     `CREATE INDEX IF NOT EXISTS idx_messages_model ON messages(model);`;
-/**
- * WAL plus a checkpoint at the end of a sync: the write path stops paying an fsync per commit,
- * and the main file still holds every row, so a backup that copies only usage.db loses nothing.
- */
+/** WAL + a checkpoint: the write path avoids an fsync per commit, and usage.db alone holds every row. */
 function pragmas(db) {
     run(db, 'PRAGMA journal_mode=WAL;' +
         'PRAGMA synchronous=NORMAL;' +
@@ -81,7 +73,7 @@ function storedParserVersion(db) {
         return null;
     }
 }
-// A store written by a newer tersio: this code has no forward migration, so a re-parse would swap rotated history for whatever transcripts are left.
+// A store written by a newer tersio: no forward migration, so a re-parse would swap rotated history for what is left.
 function isDowngrade(stored) {
     if (stored === null)
         return false;
@@ -109,6 +101,16 @@ function newestOpencodeMs(db) {
         return null;
     }
 }
+/** Whether the OpenCode tools backfill ran; unfilled rows stay empty, so this widens the scan once. */
+function opencodeToolsBackfilled(db) {
+    try {
+        const rows = query(db, `SELECT v FROM meta WHERE k='opencode_tools';`);
+        return rows.length > 0 && rows[0][0] === OPENCODE_TOOLS_VERSION;
+    }
+    catch {
+        return false;
+    }
+}
 // Same pre-migration state as the newest backup: another copy churns the 3-slot rotation for nothing.
 function newestBackupMatches(stored) {
     if (stored === null)
@@ -124,7 +126,7 @@ function newestBackupMatches(stored) {
         return false;
     }
 }
-// v9 shape (path-keyed rows) migrates in place with zero re-parse, so history survives even when transcripts are gone.
+// v9 shape (path-keyed rows) migrates in place with zero re-parse, so history survives even without transcripts.
 function canMigrateInPlace(db) {
     try {
         const names = query(db, `PRAGMA table_info(messages);`).map((r) => r[1]);
@@ -141,7 +143,7 @@ function migrateInPlace(db, preCount) {
             `CREATE TABLE files_new (id INTEGER PRIMARY KEY AUTOINCREMENT, path TEXT UNIQUE NOT NULL, mtime REAL NOT NULL, size INTEGER NOT NULL);` +
             `INSERT INTO files_new (path, mtime, size) SELECT path, mtime, size FROM files;` +
             `CREATE TABLE messages_new (file_id INTEGER NOT NULL REFERENCES files_new(id), t REAL, model TEXT NOT NULL,` +
-            ` i INTEGER NOT NULL, o INTEGER NOT NULL, d REAL, cr INTEGER NOT NULL, cw INTEGER NOT NULL,` +
+            ` i INTEGER NOT NULL, o INTEGER NOT NULL, d REAL, tf REAL, cr INTEGER NOT NULL, cw INTEGER NOT NULL,` +
             ` usd REAL, st TEXT NOT NULL, code REAL, note TEXT, tools TEXT NOT NULL DEFAULT '[]', h TEXT, a TEXT, id TEXT);` +
             `INSERT INTO messages_new (file_id, ${cols}) SELECT (SELECT id FROM files_new WHERE files_new.path = messages.file), ${cols} FROM messages;` +
             `DROP TABLE messages;DROP TABLE files;` +
@@ -160,9 +162,7 @@ function migrateInPlace(db, preCount) {
         return false;
     }
 }
-// v12 shape gains the agent kind (`main`, `subagent`) with a bare ALTER for the two names the
-// store already holds. No rows move and no re-parse is forced, so the existing rows read
-// `NULL` for it: a report then shows them under the main agent only, and new rows carry it.
+// v12 adds the agent kind with a bare ALTER; existing rows read NULL and report under the main agent.
 function canAddAgent(db) {
     try {
         const names = query(db, `PRAGMA table_info(messages);`).map((r) => r[1]);
@@ -172,8 +172,6 @@ function canAddAgent(db) {
         return false;
     }
 }
-// v12 shape gains the agent kind (`main`, `subagent`) with a bare ALTER: no rows move, so no
-// re-parse is forced. Existing rows read NULL, which a report folds under the main agent.
 function addAgentColumn(db) {
     try {
         run(db, `ALTER TABLE messages ADD COLUMN a TEXT;`);
@@ -183,6 +181,44 @@ function addAgentColumn(db) {
     }
     return true;
 }
+// v13 shape gains the first-token latency with a bare ALTER, so no row moves and no wipe runs.
+function canAddTtft(db) {
+    try {
+        const names = query(db, `PRAGMA table_info(messages);`).map((r) => r[1]);
+        return names.includes('file_id') && !names.includes('tf');
+    }
+    catch {
+        return false;
+    }
+}
+// The column is additive, and a rotated transcript cannot be re-parsed, so the ALTER precedes the backfill.
+function addTtftColumn(db) {
+    try {
+        run(db, `ALTER TABLE messages ADD COLUMN tf REAL;`);
+    }
+    catch {
+        return false;
+    }
+    return !canAddTtft(db);
+}
+/** First-token-latency marker; unchanged transcripts are never revisited, so old stores stay null. */
+const TTFT_VERSION = '1';
+function ttftBackfilled(db) {
+    try {
+        const rows = query(db, `SELECT v FROM meta WHERE k='ttft_backfill';`);
+        return rows.length > 0 && rows[0][0] === TTFT_VERSION;
+    }
+    catch {
+        return false;
+    }
+}
+/** Clears ledger mtimes so every transcript re-reads; synthetic `db#row-id` OpenCode keys stay untouched. */
+function markTranscriptsDirty(db) {
+    try {
+        run(db, `UPDATE files SET mtime = 0 WHERE path NOT LIKE '%#%';`);
+    }
+    catch { /* a store with no files table yet, or a read-only file: nothing to backfill */ }
+}
 // v10 shape gains the message id with a bare ALTER: no rows move, so no re-parse and no guard trip.
 function canAlterInPlace(db) {
     try {
@@ -233,10 +269,14 @@ function ensureSchema(db, forceWipe) {
             run(db, `INSERT OR REPLACE INTO meta (k,v) VALUES ('parser_version','${PARSER_VERSION}');`);
             return;
         }
-        // The agent column is additive on the current shape: adding it keeps every row, and the
-        // unchanged transcripts that already hold their rows simply read NULL until a re-parse.
+        // The agent column is additive: every row survives and unchanged transcripts read NULL until a re-parse.
         if (stored !== null && canAddAgent(db) && addAgentColumn(db)) {
-            run(db, `INSERT OR REPLACE INTO meta (k,v) VALUES ('parser_version','${PARSER_VERSION}');`);
+            run(db, `INSERT OR REPLACE INTO meta (k, v) VALUES ('parser_version','${PARSER_VERSION}');`);
+            return;
+        }
+        // The ttft column is additive too; its values come from the backfill in `syncUsageDb`.
+        if (stored !== null && canAddTtft(db) && addTtftColumn(db)) {
+            run(db, `INSERT OR REPLACE INTO meta (k, v) VALUES ('parser_version','${PARSER_VERSION}');`);
             return;
         }
         run(db, `DROP TABLE IF EXISTS messages;DROP TABLE IF EXISTS files;` + SCHEMA_SQL +
@@ -347,22 +387,22 @@ function readFiles(db) {
     catch { /* fresh db */ }
     return known;
 }
-// OpenCode rows carry no status, code, note, tool list, or subagent marker: only tokens and the
-// msg id. They record as the main agent, so a store never holds a NULL kind.
-function opencodeStoredRow(oc, host, id) {
+// OpenCode rows carry only tokens, msg id, and tools; they record as the main agent, so no NULL kind.
+function opencodeStoredRow(oc, host, id, tools) {
     return {
         t: oc.ms ?? null,
         model: canonicalModelId(oc.model),
         i: intOf(oc.usage.input),
         o: intOf(oc.usage.output),
         d: durOf(oc.durMs),
+        tf: durOf(oc.ttftMs),
         cr: intOf(oc.usage.cacheRead),
         cw: intOf(oc.usage.cacheWrite),
         usd: costOf(oc.usage),
         st: 'completed',
         code: undefined,
         note: undefined,
-        tools: [],
+        tools,
         host,
         agent: 'main',
         id,
@@ -373,13 +413,14 @@ function parseFile(text, host, file, agent) {
     // Guarded: a JSONL transcript must fall through, not abort the sync.
     let oc = null;
     try {
-        oc = classifyOpencodeMessage(JSON.parse(text));
+        const message = JSON.parse(text);
+        oc = classifyOpencodeMessage(message);
+        if (oc) {
+            rows.push(opencodeStoredRow(oc, host, file ? path.basename(file).replace(/\.[^.]+$/, '') : undefined, opencodeToolNames(message)));
+            return rows;
+        }
     }
     catch { /* JSONL */ }
-    if (oc) {
-        rows.push(opencodeStoredRow(oc, host, file ? path.basename(file).replace(/\.[^.]+$/, '') : undefined));
-        return rows;
-    }
     let codexProvider = null;
     let codexModel = null;
     for (const line of text.split('\n')) {
@@ -411,6 +452,7 @@ function parseFile(text, host, file, agent) {
                     i: intOf(usage.input),
                     o: intOf(usage.output),
                     d: undefined,
+                    tf: undefined,
                     cr: intOf(usage.cacheRead),
                     cw: intOf(usage.cacheWrite),
                     usd: costOf(usage),
@@ -436,6 +478,7 @@ function parseFile(text, host, file, agent) {
                 i: intOf(usage.input),
                 o: intOf(usage.output),
                 d: dur,
+                tf: durOf(parsed.ttftMs),
                 cr: intOf(usage.cacheRead),
                 cw: intOf(usage.cacheWrite),
                 usd: costOf(usage),
@@ -453,12 +496,12 @@ function parseFile(text, host, file, agent) {
     return rows;
 }
 function insertSql(file, r) {
-    return `INSERT INTO messages (file_id, t, model, i, o, d, cr, cw, usd, st, code, note, tools, h, a, id) VALUES (` +
+    return `INSERT INTO messages (file_id, t, model, i, o, d, tf, cr, cw, usd, st, code, note, tools, h, a, id) VALUES (` +
         `(SELECT id FROM files WHERE path=${esc(file)}),${r.t === null ? 'NULL' : String(r.t)},${esc(r.model)},${r.i},${r.o},` +
-        `${nullNum(r.d)},${r.cr},${r.cw},${nullNum(r.usd)},${esc(r.st)},` +
+        `${nullNum(r.d)},${nullNum(r.tf)},${r.cr},${r.cw},${nullNum(r.usd)},${esc(r.st)},` +
         `${nullNum(r.code)},${nullStr(r.note)},${esc(JSON.stringify(r.tools))},${nullStr(r.host)},${nullStr(r.agent ?? undefined)},${nullStr(r.id)});`;
 }
-// Unchanged transcripts are skipped via mtime+size; rows for deleted ones are kept so rotation never erases history. False when sqlite3 is unavailable.
+// Unchanged transcripts are skipped via mtime+size; rows for deleted ones are kept so rotation never erases history.
 export function syncUsageDb() {
     let db;
     guardReport = null;
@@ -477,6 +520,9 @@ export function syncUsageDb() {
         if (migrated && !forced)
             preWipe = countMessages(db);
         ensureSchema(db, forced);
+        // One rewrite so the additive column's NULL rows gain latency; runs while the marker is absent.
+        if (!downgrade && !ttftBackfilled(db))
+            markTranscriptsDirty(db);
         maybeScheduledBackup(db);
     }
     catch {
@@ -501,8 +547,10 @@ export function syncUsageDb() {
     const ocDbPath = opencodeDbPath();
     if (process.env.TERSIO_SESSIONS_DIR === undefined || process.env.TERSIO_OPENCODE_DB !== undefined) {
         const newest = newestOpencodeMs(db);
+        // A store predating the tool names re-reads the whole table once; the marker closes the window.
+        const since = newest === null || !opencodeToolsBackfilled(db) ? 0 : newest - OPENCODE_DB_OVERLAP_MS;
         if (newest !== null || fs.existsSync(ocDbPath)) {
-            ocDbRows.push(...readOpencodeDbRows(ocDbPath, newest === null ? 0 : newest - OPENCODE_DB_OVERLAP_MS));
+            ocDbRows.push(...readOpencodeDbRows(ocDbPath, since));
         }
     }
     const known = readFiles(db);
@@ -522,6 +570,7 @@ export function syncUsageDb() {
         if (!prev || prev.mtime !== entry.mtime || prev.size !== entry.size)
             changed.push(file);
     }
+    // `ocDbRows` is non-empty whenever the backfill window is open, so this never skips it.
     if (!changed.length && !ocDbRows.length)
         return true;
     const chunks = [];
@@ -571,7 +620,7 @@ export function syncUsageDb() {
             if (!push(`INSERT INTO files (path, mtime, size) VALUES (${esc(key)},${row.created},0)` +
                 ` ON CONFLICT(path) DO UPDATE SET mtime=excluded.mtime;` +
                 `DELETE FROM messages WHERE file_id=(SELECT id FROM files WHERE path=${esc(key)});` +
-                insertSql(key, opencodeStoredRow(parsed, 'opencode', row.id))))
+                insertSql(key, opencodeStoredRow(parsed, 'opencode', row.id, opencodeToolNames(row.row, row.tools)))))
                 return false;
         }
     }
@@ -580,6 +629,16 @@ export function syncUsageDb() {
     }
     if (!push(`INSERT OR REPLACE INTO meta (k, v) VALUES ('last_sync',${esc(String(Date.now()))});`))
         return false;
+    // Only once the rows are written, so a sync that fails midway widens the scan again.
+    if (ocDbRows.length > 0) {
+        if (!push(`INSERT OR REPLACE INTO meta (k, v) VALUES ('opencode_tools','${OPENCODE_TOOLS_VERSION}');`))
+            return false;
+    }
+    // Set only after the rewrite commits: a crash mid-backfill leaves mtimes cleared and the marker absent.
+    if (changed.length > 0) {
+        if (!push(`INSERT OR REPLACE INTO meta (k, v) VALUES ('ttft_backfill','${TTFT_VERSION}');`))
+            return false;
+    }
     if (!flush())
         return false;
     if (preWipe > 0) {
@@ -617,18 +676,18 @@ export function readUsageDb() {
     }
     let rows;
     try {
-        // The `tools` column is the widest by far and the common case is the literal `[]`, so it is
-        // read as one column and skipped in JS rather than parsed per row. A store written before
-        // the agent column does not hold it, so the row is read without that column.
+        // The wide `tools` column is read as one string and skipped in JS; a pre-agent store is read without it.
         const names = query(db, `PRAGMA table_info(messages);`).map((r) => r[1]);
         const agentCol = names.includes('a') ? 'a' : "''";
-        rows = query(db, `SELECT t, model, i, o, d, cr, cw, usd, st, code, note, tools, h, ${agentCol}, id FROM messages;`);
+        // A store predating first-token latency has no `tf` column; read NULL so the row still loads.
+        const tfCol = names.includes('tf') ? 'tf' : 'NULL';
+        rows = query(db, `SELECT t, model, i, o, d, cr, cw, usd, st, code, note, tools, h, ${agentCol}, id, ${tfCol} FROM messages;`);
     }
     catch {
         return null;
     }
     const accum = newSessionAccum();
-    for (const [t, model, i, o, d, cr, cw, usd, st, code, note, tools, h, a, id] of rows) {
+    for (const [t, model, i, o, d, cr, cw, usd, st, code, note, tools, h, a, id, tf] of rows) {
         const ts = t === '' ? undefined : Number(t);
         let toolNames = [];
         if (tools && tools !== '[]' && tools !== '') {
@@ -654,7 +713,7 @@ export function readUsageDb() {
             st: st === 'error' || st === 'aborted' ? st : 'completed',
             code: code === '' ? undefined : Number(code),
             note: note === '' ? undefined : note,
-        }, toolNames, h === '' ? undefined : h, id === '' || id === undefined ? undefined : id, a === '' ? undefined : a);
+        }, toolNames, h === '' ? undefined : h, id === '' || id === undefined ? undefined : id, a === '' ? undefined : a, tf === undefined || tf === '' ? undefined : Number(tf));
     }
     accum.recent.sort((a, b) => b.t - a.t);
     let syncedAt = 0;