tokentracker-cli 1.3.5 → 1.3.6

package/src/lib/session-analytics.js

@@ -28,10 +28,12 @@ const fsp = require("node:fs/promises");
 const os = require("node:os");
 const path = require("node:path");
 const readline = require("node:readline");
-const { listClaudeProjectFiles, listRolloutFilesDeep, claudeMessageDedupKey, normalizeClaudeUsage } = require("./rollout");
+const { listClaudeProjectFiles, listRolloutFilesDeep, claudeMessageDedupKey, normalizeClaudeUsage, readZcodeDbMessages, coerceEpochMs, normalizeOpencodeModelFields, deriveOpencodeMessageFingerprint } = require("./rollout");
 const { parseCodexRolloutFile } = require("./codex-rollout-parser");
 const { computeRowCost, getModelPricingInfo } = require("./pricing");
-const { normalizePerformance, mergePerformance, createClaudePerformanceCollector, createCodexPerformanceCollector } = require("./session-performance");
+const { normalizePerformance, mergePerformance, createClaudePerformanceCollector, createCodexPerformanceCollector, createZcodePerformanceCollector } = require("./session-performance");
+const { readSqliteJsonRows } = require("./sqlite-reader");
+const { resolveZcodeNativeDbPath } = require("./install-resolver");
 const { USD_TICKS_PER_USD, normalizeGrokUsage } = require("./grok-usage");
 const wsl = require("./wsl-probe");
 const {
@@ -70,7 +72,16 @@ const {
 // long-context subset) and folds delivery signals into the token parser's
 // single pass instead of parsing every Codex file twice.
 // v14 adds request-level estimated performance and Claude model usage.
-const SIDECAR_VERSION = 16;
+// v15/v16 tighten Codex delivery-signal parsing (uncommented bump).
+// v17 adds ZCode sessions from ~/.zcode/cli/db/db.sqlite — one SQLite db
+// scanning to many per-session rows — so every cached row is rebuilt.
+// v18 corrects ZCode project keys and request timestamp units, and invalidates
+// inventories that earlier builds may have cached after a failed database read.
+// v19 scans both ZCode installs as one deduplicated inventory and separates
+// provider retries from repeated user requests.
+// v20 also invalidates unchanged-stat caches after an observed database lock.
+// v21 retains the request count when several ZCode events share a minute.
+const SIDECAR_VERSION = 21;
 const EDIT_TOOLS = new Set([
   "apply_patch",
   "edit",
@@ -1162,6 +1173,408 @@ async function scanGrokSession(filePath) {
   });
 }
 
+// ZCode (Z.ai's CLI, an OpenCode fork) keeps everything in one SQLite DB at
+// ~/.zcode/cli/db/db.sqlite: a `session` table (id/parent_id/directory/title),
+// a `model_usage` table (per-request counters) and OpenCode's legacy `message`
+// table (assistant messages with inclusive token snapshots). Billable tokens
+// come from readZcodeDbMessages() — the exact same reader, inclusive→disjoint
+// normalization and sub-agent provider blocklist the usage sync uses — so the
+// session browser and the usage card can never drift apart. The per-request
+// signal columns live only in model_usage, so they are read separately and
+// feed performance/counter estimates only, never token totals.
+function zcodeTableColumns(dbPath, table) {
+  // throwOnReadFailure: a missing table answers pragma_table_info with an
+  // empty row set (no error), so the only way to land in the reader's failure
+  // path is a genuinely unreadable db — which must propagate, never read as
+  // "no table" (see the throw in scanZcodeSessions below).
+  const rows = readSqliteJsonRows(dbPath, `SELECT name FROM pragma_table_info('${table}')`, {
+    label: "ZCode",
+    timeout: 10_000,
+    maxBuffer: 1024 * 1024,
+    throwOnReadFailure: true,
+  });
+  return new Set((Array.isArray(rows) ? rows : []).map((row) => String(row?.name || "")));
+}
+
+// Messages from readZcodeDbMessages already carry disjoint opencode-shaped
+// tokens ({ input, output, reasoning, cache.read, cache.write }); map them
+// onto the session pipeline's column names. tokenTotals() recomputes the sum.
+function zcodeMessageTotals(data) {
+  const tokens = data?.tokens || {};
+  const totals = tokenTotals({
+    input_tokens: tokens.input,
+    cached_input_tokens: tokens.cache?.read,
+    cache_creation_input_tokens: tokens.cache?.write,
+    output_tokens: tokens.output,
+    reasoning_output_tokens: tokens.reasoning,
+  });
+  // The usage queue's total is input + output + cache_creation + cache_read +
+  // reasoning_output (rollout.js addTotals); tokenTotals' generic total omits
+  // reasoning. ZCode splits reasoning out of output, so fold it back in here or
+  // the session browser undercounts every thinking request against the card.
+  totals.total_tokens += totals.reasoning_output_tokens;
+  return totals;
+}
+
+const ZCODE_SIGNAL_REQUIRED_COLUMNS = [
+  "session_id", "model_id", "provider_id", "status", "started_at", "id",
+  "output_tokens", "duration_ms", "time_to_first_token_ms", "query_source",
+];
+
+// One db yields many session rows, so unlike the per-file scanners this scan
+// returns an array (the entries loop in buildSessionAnalyticsInternal handles
+// both shapes). Errors on the db as a whole propagate: the caller counts the
+// file as skipped instead of caching an empty inventory as "no sessions".
+//
+// WSL dbs arrive as UNC paths (\\wsl$\…), and SQLite over the Plan 9 bridge
+// cannot take the locks even a read needs ("database is locked"). The usage
+// readers snapshot such paths query-by-query; the scan runs several queries
+// plus readZcodeDbMessages against one db, so snapshot once here and run the
+// whole scan (metadata, signals, turns, tools, messages) against the local
+// copy — otherwise the metadata query succeeds while the message read fails
+// on the same database.
+async function scanZcodeSessions(dbPaths) {
+  const paths = [...new Set((Array.isArray(dbPaths) ? dbPaths : [dbPaths]).filter(Boolean))];
+  const snapshots = [];
+  const inputs = [];
+  try {
+    for (const dbPath of paths) {
+      let effectiveDbPath = dbPath;
+      if (wsl.isUncPath(dbPath)) {
+        try {
+          const snapshot = wsl.snapshotSqliteDb(dbPath);
+          snapshots.push(snapshot);
+          effectiveDbPath = snapshot.path;
+        } catch (_error) { /* Direct read decides whether this UNC server supports SQLite. */ }
+      }
+      inputs.push(readZcodeSessionInputs(effectiveDbPath));
+    }
+    return buildZcodeSessionRecords(inputs, paths[0]);
+  } finally {
+    for (const snapshot of snapshots) snapshot.cleanup();
+  }
+}
+
+/** Read metadata and numeric events from one database; real read failures propagate. */
+function readZcodeSessionInputs(dbPath) {
+  const options = { label: "ZCode", timeout: 30_000, maxBuffer: 50 * 1024 * 1024, readOnly: true, throwOnReadFailure: true };
+  const sessionColumns = zcodeTableColumns(dbPath, "session");
+  if (!sessionColumns.has("id")) return { sessionRows: [], messages: [], requestRows: [], turnRows: [], toolRows: [] };
+  const optionalColumns = ["parent_id", "directory", "title", "time_created", "time_updated"];
+  const selectColumns = ["id", ...optionalColumns.filter((name) => sessionColumns.has(name))];
+  const orderBy = sessionColumns.has("time_created") ? " ORDER BY time_created ASC, id ASC" : " ORDER BY id ASC";
+  const sessionRows = readSqliteJsonRows(
+    dbPath,
+    `SELECT ${selectColumns.join(", ")} FROM session${orderBy}`,
+    options,
+  );
+  const messages = readZcodeDbMessages(dbPath, { readOnly: true }, { propagateReadFailure: true });
+  const modelUsageColumns = zcodeTableColumns(dbPath, "model_usage");
+  const requestRows = ZCODE_SIGNAL_REQUIRED_COLUMNS.every((name) => modelUsageColumns.has(name))
+    ? readSqliteJsonRows(dbPath, `SELECT id, session_id, model_id, status, started_at, output_tokens, duration_ms, time_to_first_token_ms, query_source
+       FROM model_usage
+       WHERE status IN ('completed', 'error')
+         AND trim(provider_id) != ''
+         AND provider_id NOT LIKE '%anthropic%'
+         AND provider_id NOT LIKE '%openai%'
+         AND provider_id NOT LIKE '%google%'
+       ORDER BY started_at ASC, id ASC`, options)
+    : [];
+  const turnColumns = zcodeTableColumns(dbPath, "turn_usage");
+  const turnRows = turnColumns.has("session_id")
+    ? readSqliteJsonRows(dbPath, `SELECT session_id${turnColumns.has("turn_id") ? ", turn_id" : ""} FROM turn_usage`, options)
+    : [];
+  const toolColumns = zcodeTableColumns(dbPath, "tool_usage");
+  const toolRows = ["session_id", "tool_name", "turn_id"].every((name) => toolColumns.has(name))
+    ? readSqliteJsonRows(dbPath, "SELECT session_id, turn_id, tool_name FROM tool_usage", options)
+    : [];
+  return { sessionRows, messages, requestRows, turnRows, toolRows };
+}
+
+/** Merge only shared event identities, retaining both installs' distinct tails. */
+function uniqueZcodeRows(rows, keyFor) {
+  const seen = new Set();
+  return rows.filter((row) => {
+    const key = keyFor(row);
+    if (!key) return true;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function buildZcodeSessionRecords(inputs, displayPath) {
+  const collect = (key) => inputs.flatMap((input) => input[key] || []);
+  const eventKey = (row, sessionKey, idKey) => row?.[sessionKey] && row?.[idKey]
+    ? `${row[sessionKey]}\u0000${row[idKey]}` : null;
+  const sessionRows = uniqueZcodeRows(collect("sessionRows"), (row) => row?.id);
+  const fingerprintOwners = new Map();
+  const forkCopies = new Set();
+  const messages = uniqueZcodeRows(collect("messages"), (row) => eventKey(row, "sessionID", "id"))
+    .filter((message) => {
+      // Use the ledger's existing narrow fork-copy contract, including both
+      // timestamps, all token columns, model and provider. Never dedup two
+      // separate turns within one session by counters alone.
+      const fingerprint = deriveOpencodeMessageFingerprint({
+        msg: message.data, totals: zcodeMessageTotals(message.data), source: "zcode",
+      });
+      const owner = fingerprint && fingerprintOwners.get(fingerprint);
+      if (owner && owner !== message.sessionID) {
+        forkCopies.add(eventKey(message, "sessionID", "id"));
+        return false;
+      }
+      if (fingerprint) fingerprintOwners.set(fingerprint, message.sessionID);
+      return true;
+    });
+  const requestRows = uniqueZcodeRows(collect("requestRows"), (row) => eventKey(row, "session_id", "id"))
+    .filter((row) => !forkCopies.has(eventKey(row, "session_id", "id")));
+  const turnRows = uniqueZcodeRows(collect("turnRows"), (row) => eventKey(row, "session_id", "turn_id"));
+  const toolRows = collect("toolRows");
+
+  const messagesBySession = new Map();
+  // propagateReadFailure: a failed native-usage query must abort the scan (the
+  // caller counts the db as skipped) rather than silently degrade to the
+  // legacy tables and cache a zero-token inventory for those sessions.
+  for (const message of messages) {
+    const sessionId = String(message?.sessionID || "").trim();
+    if (!sessionId) continue;
+    let group = messagesBySession.get(sessionId);
+    if (!group) {
+      group = [];
+      messagesBySession.set(sessionId, group);
+    }
+    group.push(message);
+  }
+
+  // Request-level signals (never token totals). Only completed requests feed
+  // duration-based estimates; error rows count toward error_count alone. The
+  // provider filter mirrors isZcodeNativeMessage's blocklist (see rollout.js):
+  // rows ZCode orchestrated through claude/codex/gemini sub-agents already
+  // appear as their own provider's sessions and must not skew signals either.
+  const signalsBySession = new Map();
+  for (const row of requestRows) {
+    const sessionId = String(row?.session_id || "").trim();
+    if (!sessionId) continue;
+    let signals = signalsBySession.get(sessionId);
+    if (!signals) {
+      signals = {
+        collector: createZcodePerformanceCollector(),
+        apiDurationMs: 0,
+        compactionCount: 0,
+        errorCount: 0,
+        // Request wall-clock extremes from model_usage. Messages only carry
+        // startedAt (the reader maps it to timeUpdated), so without these the
+        // last generation's duration never reaches ended_at and a session's
+        // final request reports a zero-length span.
+        firstRequestIso: null,
+        lastRequestEndIso: null,
+        // [startMs, endMs] per request for the active-time union below.
+        activeSpans: [],
+      };
+      signalsBySession.set(sessionId, signals);
+    }
+    // Match readZcodeNativeUsageMessages: databases may store epoch seconds
+    // or milliseconds, but request spans and message bounds must share units.
+    const requestStartMs = coerceEpochMs(row?.started_at);
+    if (requestStartMs > 0) {
+      const startIso = new Date(requestStartMs).toISOString();
+      if (!signals.firstRequestIso || startIso < signals.firstRequestIso) signals.firstRequestIso = startIso;
+      // duration_ms only exists on completed rows; an error request still
+      // occupied its start instant, so its end falls back to the start.
+      const durationMs = row.status === "completed" ? finite(row.duration_ms) : 0;
+      const endIso = new Date(requestStartMs + durationMs).toISOString();
+      if (!signals.lastRequestEndIso || endIso > signals.lastRequestEndIso) signals.lastRequestEndIso = endIso;
+      signals.activeSpans.push([requestStartMs, requestStartMs + durationMs]);
+    }
+    if (row.status === "error") {
+      signals.errorCount += 1;
+      continue;
+    }
+    if (row.query_source === "compact") signals.compactionCount += 1;
+    signals.apiDurationMs += finite(row.duration_ms);
+    signals.collector.consumeUsage({
+      model: normalizeSessionModel(row.model_id) || "unknown",
+      outputTokens: finite(row.output_tokens),
+      durationMs: finite(row.duration_ms),
+      timeToFirstTokenMs: typeof row.time_to_first_token_ms === "number" ? row.time_to_first_token_ms : undefined,
+    });
+  }
+  const turnsBySession = new Map();
+  for (const row of turnRows) {
+    const sessionId = String(row?.session_id || "").trim();
+    if (!sessionId) continue;
+    turnsBySession.set(sessionId, (turnsBySession.get(sessionId) || 0) + 1);
+  }
+
+  // ZCode writes Capitalized tool names (Edit/Write); EDIT_TOOLS is lowercase.
+  // An edit turn is a turn that used an edit tool, matching the Grok definition.
+  const editTurnsBySession = new Map();
+  const editTurnIds = new Map();
+  for (const row of toolRows) {
+    if (!EDIT_TOOLS.has(String(row?.tool_name || "").toLowerCase())) continue;
+    const sessionId = String(row?.session_id || "").trim();
+    const turnId = String(row?.turn_id || "").trim();
+    if (!sessionId || !turnId) continue;
+    let turns = editTurnIds.get(sessionId);
+    if (!turns) {
+      turns = new Set();
+      editTurnIds.set(sessionId, turns);
+    }
+    turns.add(turnId);
+  }
+  for (const [sessionId, turns] of editTurnIds) editTurnsBySession.set(sessionId, turns.size);
+
+  const records = [];
+  for (const row of Array.isArray(sessionRows) ? sessionRows : []) {
+    const sessionId = String(row?.id || "").trim();
+    if (!sessionId) continue;
+    const messages = messagesBySession.get(sessionId) || [];
+    const tokens = emptyTotals();
+    const modelUsageByModel = new Map();
+    const bounds = emptyBounds();
+    const usageBuckets = new Map();
+    const messagePoints = [];
+    let messageCwd = null;
+    for (const message of messages) {
+      const data = message?.data || {};
+      // OpenCode v1 messages carry a flat modelID; v2 (session_message era)
+      // nests it as model.id, and some forks wrote model as a plain string.
+      // Resolve every shape through the shared normalizer so by-model
+      // attribution and pricing match the usage sync on v2-layout databases.
+      const model = normalizeSessionModel(normalizeOpencodeModelFields(data).modelId) || "unknown";
+      const delta = zcodeMessageTotals(data);
+      addTotals(tokens, delta);
+      let usage = modelUsageByModel.get(model);
+      if (!usage) {
+        usage = { model, ...emptyTotals(), usage_events: 0 };
+        modelUsageByModel.set(model, usage);
+      }
+      addTotals(usage, delta);
+      usage.usage_events += 1;
+      // Message timestamps are epoch-ms integers; updateBounds() only accepts
+      // ISO strings and silently drops anything else.
+      const timeUpdated = Number(message?.timeUpdated);
+      if (Number.isFinite(timeUpdated) && timeUpdated > 0) {
+        updateBounds(bounds, new Date(timeUpdated).toISOString());
+        messagePoints.push(timeUpdated);
+        // Minute buckets (same shape as the Codex scanner's) feed the from/to
+        // day filter in scopeSessionUsage; without them a multi-day session
+        // bills its whole lifetime to every day it touches.
+        const timestamp = new Date(Math.floor(timeUpdated / 60_000) * 60_000).toISOString();
+        const bucketKey = `${timestamp}\u0000${model}`;
+        const bucket = usageBuckets.get(bucketKey) || { timestamp, model, ...emptyTotals(), usage_events: 0 };
+        addTotals(bucket, delta);
+        bucket.usage_events += 1;
+        usageBuckets.set(bucketKey, bucket);
+      }
+      if (!messageCwd && typeof data.path?.cwd === "string" && data.path.cwd.trim()) {
+        messageCwd = data.path.cwd.trim();
+      }
+    }
+    // Sessions without any message (claude-import migrations the import did
+    // not rebuild, sessions abandoned before the first reply) keep the row's
+    // own wall-clock span; they end up with zero tokens and the browser's
+    // existing total_tokens > 0 filter drops them from the listing.
+    if (messages.length === 0) {
+      const created = Number(row?.time_created);
+      const updated = Number(row?.time_updated);
+      if (Number.isFinite(created) && created > 0) updateBounds(bounds, new Date(created).toISOString());
+      if (Number.isFinite(updated) && updated > 0) updateBounds(bounds, new Date(updated).toISOString());
+    }
+
+    const signals = signalsBySession.get(sessionId) || null;
+    if (signals) {
+      // Widen the wall-clock span with model_usage request extremes: message
+      // timestamps are request starts, so the final request's duration would
+      // otherwise vanish from ended_at (a 10s request reads as a 0-length
+      // span). Direct comparison instead of updateBounds() keeps active_ms
+      // (idle-gap working time) driven by the interval union below.
+      if (signals.firstRequestIso && (!bounds.started_at || signals.firstRequestIso < bounds.started_at)) {
+        bounds.started_at = signals.firstRequestIso;
+      }
+      if (signals.lastRequestEndIso && (!bounds.ended_at || signals.lastRequestEndIso > bounds.ended_at)) {
+        bounds.ended_at = signals.lastRequestEndIso;
+      }
+    }
+    // Active time = the union of request execution intervals plus message
+    // instants, with spans ≤ IDLE_GAP_MS apart bridged. updateBounds' gap
+    // accumulator only measures message-start-to-message-start, which loses
+    // the execution time of every request but the last one (two 10s requests
+    // around a 1h pause must read 20s, not 10s); the union also collapses
+    // parallel requests instead of counting them twice. Legacy-only sessions
+    // contribute points alone, which degenerates to the same idle-gap span
+    // the generic scanners produce.
+    const spans = [...(signals ? signals.activeSpans : []), ...messagePoints.map((ms) => [ms, ms])]
+      .filter(([startMs, endMs]) => Number.isFinite(startMs) && Number.isFinite(endMs))
+      .sort((a, b) => a[0] - b[0]);
+    let unionActiveMs = 0;
+    let unionStart = null;
+    let unionEnd = null;
+    for (const [startMs, endMs] of spans) {
+      if (unionStart === null) {
+        unionStart = startMs;
+        unionEnd = endMs;
+        continue;
+      }
+      if (startMs <= unionEnd + IDLE_GAP_MS) {
+        if (endMs > unionEnd) unionEnd = endMs;
+        continue;
+      }
+      unionActiveMs += unionEnd - unionStart;
+      unionStart = startMs;
+      unionEnd = endMs;
+    }
+    if (unionStart !== null) unionActiveMs += unionEnd - unionStart;
+    bounds.active_ms = unionActiveMs;
+    const finished = signals ? signals.collector.finish() : { performance: normalizePerformance(), byModel: new Map() };
+    const modelUsage = [...modelUsageByModel.values()].map((usage) => ({
+      ...usage,
+      performance: finished.byModel.get(usage.model) || normalizePerformance(),
+    }));
+    const cwd = typeof row?.directory === "string" && row.directory.trim() ? row.directory.trim() : messageCwd;
+    records.push(finalizeRecord({
+      version: SIDECAR_VERSION,
+      session_hash: sessionHash("zcode", sessionId),
+      session_id: sessionId,
+      // Local-only lineage: ZCode's own parent_id (subagent/workflow children).
+      parent_session_id: typeof row?.parent_id === "string" && row.parent_id.trim() ? row.parent_id.trim() : null,
+      // Local-only: stripped in summarizeSessions before any cloud/CSV export.
+      title: cleanSessionTitle(row?.title),
+      source: "zcode",
+      // A database copied between Windows and POSIX retains its original cwd.
+      project_key: projectKey(cwd && cwd.replace(/\\/g, "/"), displayPath),
+      project_ref: cwd || null,
+      model: modelUsage.length > 1 ? "mixed" : (modelUsage[0]?.model || "unknown"),
+      model_usage: modelUsage,
+      usage_buckets: [...usageBuckets.values()],
+      ...bounds,
+      turns: turnsBySession.get(sessionId) || 0,
+      edit_turns: editTurnsBySession.get(sessionId) || 0,
+      // Provider/API retries are not repeated user requests. This numeric
+      // metadata has no user-prompt repetition evidence.
+      retry_turns: 0,
+      tokens,
+      usage_events: messages.length,
+      usage_precision: messages.length > 0 ? "reported" : "unavailable",
+      cost_source: "model_pricing",
+      provider_cost_usd: null,
+      model_calls: messages.length,
+      api_duration_ms: signals ? signals.apiDurationMs : 0,
+      error_count: signals ? signals.errorCount : 0,
+      compaction_count: signals ? signals.compactionCount : 0,
+      performance: finished.performance,
+      provenance: {
+        source: "local-session-log",
+        confidence: "observed",
+        retry_confidence: "unavailable",
+        content_retained: false,
+        usage: messages.length > 0 ? "zcode-db-messages" : "unavailable",
+      },
+    }));
+  }
+  return records;
+}
+
 // Multi-root discovery: on Windows a native install and a WSL one both count.
 // `sync` already walks both Claude homes (src/commands/sync.js), so without this
 // the WSL work lands in the token totals but is invisible in the session browser
@@ -1387,7 +1800,36 @@ async function discoverSessionFiles(home, env = process.env, deps = {}) {
   const claude = allClaude.filter((filePaths) => !filePaths.some((filePath) => filePath
     .split(path.sep)
     .some((segment) => segment.endsWith(CLAUDE_MEM_OBSERVER_PROJECT_SUFFIX))));
-  return { claude, codex: groupCodexFiles([...codex, ...archived]), grok, incomplete };
+  // ZCode has no sessions directory tree — one SQLite db per install. Resolve
+  // it like the usage sync does (src/commands/sync.js): native candidate first
+  // (ZCODE_HOME, home, win32 APPDATA fallback), then the WSL install when the
+  // WSL mode probes it, picked with the same mode priority (default wsl-first)
+  // so the browser reads the same installs the usage card counts. "both"
+  // preserves both paths; the scanner merges shared session/event identities.
+  const zcodePlatform = deps.platform || process.platform;
+  const zcodeNativeDbPath = (deps.resolveZcodeNativeDbPath || resolveZcodeNativeDbPath)({ home, env, platform: zcodePlatform });
+  // Same WSL gate as providerRoots(): discoverWslHome resolves \\wsl$
+  // independently of `home`, so a custom/injected home must not splice the
+  // machine's live WSL db into an isolated scan. `probeWsl` is the deliberate
+  // opt-in (defaults to true only for the machine's own home).
+  const zcodeProbeWsl = deps.probeWsl !== undefined
+    ? Boolean(deps.probeWsl)
+    : path.resolve(home) === path.resolve((deps.homedir || os.homedir)());
+  const zcodeWslHome = zcodePlatform === "win32" && zcodeProbeWsl && wsl.shouldProbeWsl(env)
+    ? (deps.discoverWslHome || wsl.discoverWslHome)(".zcode", { env })
+    : null;
+  const zcodeExisting = (dbPath) => (dbPath && fs.existsSync(dbPath) ? dbPath : null);
+  const zcodeWslDbPath = zcodeWslHome ? path.join(zcodeWslHome, "cli", "db", "db.sqlite") : null;
+  const zcodePaths = zcodePlatform === "win32"
+    ? wsl.resolveAllWin32Paths({
+      nativeValue: zcodeExisting(zcodeNativeDbPath),
+      wslValue: zcodeExisting(zcodeWslDbPath),
+      env,
+      platform: zcodePlatform,
+    })
+    : { native: zcodeExisting(zcodeNativeDbPath), wsl: null };
+  const zcode = [...new Set(Object.values(zcodePaths).filter(Boolean))];
+  return { claude, codex: groupCodexFiles([...codex, ...archived]), grok, zcode, incomplete };
 }
 
 // Warn once per unreadable directory per process: the dashboard polls this
@@ -1492,6 +1934,12 @@ function analyticsEntryStatKey(source, filePath) {
     const primary = filePaths[0];
     return `${sessionStat}|summary:${sessionFileStatKey(grokSummaryPathFor(primary)) || "missing"}|signals:${sessionFileStatKey(grokSignalsPathFor(primary)) || "missing"}`;
   }
+  if (source === "zcode") {
+    // A WAL-mode db can absorb writes without touching the main file's mtime,
+    // so the sidecar files are part of the db's identity for cache checks.
+    return `${sessionStat}|sidecars:${filePaths.map((filePath) =>
+      `wal:${sessionFileStatKey(`${filePath}-wal`) || "missing"}|shm:${sessionFileStatKey(`${filePath}-shm`) || "missing"}`).join("|")}`;
+  }
   return sessionStat;
 }
 
@@ -1514,13 +1962,18 @@ async function writeAtomic(filePath, content) {
 async function buildSessionAnalyticsInternal({ home = os.homedir(), force = false, cacheTtlMs = 5 * 60_000 } = {}) {
   const sidecarPath = resolveSessionSidecarPath(home);
   const metaPath = `${sidecarPath}.meta.json`;
+  // A lock/permission failure need not alter the database's stat signature.
+  // Keep a separate durable invalidation marker while preserving the complete
+  // sidecar and metadata. TTL, signature and per-file reuse must all retry it.
+  const incompleteZcodePath = `${metaPath}.zcode-incomplete`;
+  const retryZcodeScan = fs.existsSync(incompleteZcodePath);
   let previousMeta = null;
   if (!force) {
     try {
       previousMeta = JSON.parse(fs.readFileSync(metaPath, "utf8"));
       const checkedAt = Date.parse(previousMeta.checked_at || previousMeta.generated_at || "");
       if (
-        previousMeta.version === SIDECAR_VERSION &&
+        !retryZcodeScan && previousMeta.version === SIDECAR_VERSION &&
         Number.isFinite(checkedAt) &&
         Date.now() - checkedAt < Math.max(0, Number(cacheTtlMs) || 0)
       ) {
@@ -1553,8 +2006,10 @@ async function buildSessionAnalyticsInternal({ home = os.homedir(), force = fals
     ...discovered.grok,
     ...discovered.grok.map(grokSummaryPathFor),
     ...discovered.grok.map(grokSignalsPathFor),
+    // db + its WAL sidecars: the trio is one logical file for change detection.
+    ...(discovered.zcode || []).flatMap((dbPath) => [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]),
   ]);
-  if (!force && previousMeta?.version === SIDECAR_VERSION && previousMeta.signature === signature) {
+  if (!force && !retryZcodeScan && previousMeta?.version === SIDECAR_VERSION && previousMeta.signature === signature) {
     await writeAtomic(metaPath, `${JSON.stringify({ ...previousMeta, checked_at: new Date().toISOString() })}\n`);
     return readSidecar(sidecarPath);
   }
@@ -1574,44 +2029,74 @@ async function buildSessionAnalyticsInternal({ home = os.homedir(), force = fals
     ...discovered.claude.map((filePaths) => ({ source: "claude", filePath: filePaths, scan: scanClaudeSession })),
     ...discovered.codex.map((filePaths) => ({ source: "codex", filePath: filePaths, scan: scanCodexSession })),
     ...discovered.grok.map((filePath) => ({ source: "grok", filePath, scan: scanGrokSession })),
+    ...(discovered.zcode.length ? [{ source: "zcode", filePath: discovered.zcode, scan: scanZcodeSessions }] : []),
   ];
   // Files we could not turn into a row (permission denied, half-written line,
   // vanished mid-scan). Swallowing these silently made sessions disappear with
   // no signal at all; count them so the API can say so.
   let skippedFiles = 0;
+  let incompleteZcodeScan = false;
   for (const entry of entries) {
     const cacheKey = sessionFileCacheKey(entry.source, entry.filePath);
     const statKey = analyticsEntryStatKey(entry.source, entry.filePath);
     if (!statKey) {
       skippedFiles += 1;
+      if (entry.source === "zcode") incompleteZcodeScan = true;
       continue;
     }
-    let row = null;
-    if (!force && previousFiles[cacheKey]?.stat_key === statKey) {
-      row = previousRowsByFile.get(cacheKey) || null;
+    let rows = null;
+    if (!force && !(entry.source === "zcode" && retryZcodeScan) && previousFiles[cacheKey]?.stat_key === statKey) {
+      if (entry.source === "zcode") {
+        // One db scans to many cached rows; recover them all from the previous
+        // pass. An empty recovery means the sidecar lost its rows — rescan.
+        const cached = previousRows.filter((row) => row?.source === "zcode");
+        rows = cached.length ? cached : null;
+      } else {
+        const row = previousRowsByFile.get(cacheKey) || null;
+        rows = row ? [row] : null;
+      }
     }
-    if (!row) {
+    if (!rows) {
       try {
-        row = await entry.scan(entry.filePath);
+        const scanned = await entry.scan(entry.filePath);
+        rows = Array.isArray(scanned) ? scanned.filter(Boolean) : (scanned ? [scanned] : []);
       } catch (error) {
         // One active/partial session must not poison the sidecar, but do not
         // pretend it never existed either.
         skippedFiles += 1;
+        if (entry.source === "zcode") incompleteZcodeScan = true;
         if (!process.env.NODE_TEST_CONTEXT) {
           console.warn(`[session-analytics] skipped ${entry.source} session file: ${error?.message || error}`);
         }
+        rows = [];
       }
     }
-    if (!row) continue;
-    repriceSessionRecord(row);
-    // A one-way file hash enables incremental reuse without persisting or
-    // exposing the user's local session path.
-    row._cache_key = cacheKey;
-    sessions.push(row);
-    nextFiles[cacheKey] = { stat_key: statKey };
+    for (const row of rows) {
+      repriceSessionRecord(row);
+      // A one-way file hash enables incremental reuse without persisting or
+      // exposing the user's local session path. ZCode's rows all share one db,
+      // so key each by the db path plus its session id; a bare session id as a
+      // separate path element would be path.resolve()d against the process cwd
+      // and never match across runs.
+      row._cache_key = entry.source === "zcode" && row.session_id
+        ? `${cacheKey}#${sessionHash("zcode", row.session_id)}`
+        : cacheKey;
+      sessions.push(row);
+    }
+    if (rows.length > 0) nextFiles[cacheKey] = { stat_key: statKey };
+  }
+  if (incompleteZcodeScan) {
+    await writeAtomic(incompleteZcodePath, "1\n");
+    // ZCode databases form one deduplicated inventory. If any read fails, retain its last
+    // complete rows even on a forced refresh; skippedFiles still reports that
+    // these rows could not be refreshed. Older cache schemas must be rebuilt.
+    sessions.push(...readSidecar(sidecarPath).filter((row) =>
+      row.source === "zcode" && row.version === SIDECAR_VERSION));
   }
   sessions.sort((a, b) => String(b.ended_at || "").localeCompare(String(a.ended_at || "")));
-  if (incompleteDirs.length === 0) {
+  // A failed database scan is an incomplete inventory. Keep the last complete
+  // snapshot and signature so an unchanged database is retried next build.
+  if (incompleteDirs.length === 0 && !incompleteZcodeScan) {
     const content = sessions.map(serializeSessionRecord).join("\n") + (sessions.length ? "\n" : "");
     await writeAtomic(sidecarPath, content);
     const generatedAt = new Date().toISOString();
@@ -1622,6 +2107,7 @@ async function buildSessionAnalyticsInternal({ home = os.homedir(), force = fals
       checked_at: generatedAt,
       files: nextFiles,
     })}\n`);
+    await fsp.rm(incompleteZcodePath, { force: true });
   }
   // Non-enumerable so the array still behaves exactly like a plain row list
   // for every existing caller (map/filter/JSON of the rows is unaffected).
@@ -1708,7 +2194,7 @@ function scopeSessionUsage(row, from, to, context) {
 
 function summarizeSessions(sessions, { from = "", to = "", includeSessions = true, timeZone, offsetMinutes } = {}) {
   const context = { timeZone, offsetMinutes };
-  const filtered = annotateCodexThreadUsage((sessions || [])
+  const filtered = annotateThreadUsage((sessions || [])
     .filter((row) => withinDayRange(row, from, to, context))
     // Efficiency is a session-lifetime metric: both tokens and edit turns
     // must describe that same population. The browser scopes consumption
@@ -1799,7 +2285,7 @@ function summarizeSessions(sessions, { from = "", to = "", includeSessions = tru
       if (key === primaryModel) agg.retries += finite(row.retry_turns);
       byModel.set(key, agg);
     }
-    if (row.source === "codex" && row.parent_session_hash) {
+    if ((row.source === "codex" || row.source === "zcode") && row.parent_session_hash) {
       const name = row.agent_role || row.agent_nickname || "subagent";
       const sub = subagents.get(name) || {
         name,
@@ -1816,9 +2302,9 @@ function summarizeSessions(sessions, { from = "", to = "", includeSessions = tru
       subagents.set(name, sub);
       continue;
     }
-    // Codex child rollouts are first-class rows. A spawn call in the parent is
+    // Codex and ZCode children are first-class rows. A spawn call in the parent is
     // a control-plane event, not token usage, so do not mix in an estimate.
-    if (row.source === "codex") continue;
+    if (row.source === "codex" || row.source === "zcode") continue;
     for (const [name, calls] of Object.entries(row.subagent_types || {})) {
       const sub = subagents.get(name) || { name, calls: 0, sessions: 0, total_tokens: 0, cost_usd: 0 };
       sub.calls += finite(calls);
@@ -2079,32 +2565,36 @@ function mergeSessionFragments(rows) {
   return merged;
 }
 
-// Attach exact Codex parent/child usage without changing the authoritative
-// per-session total_tokens field. Combined fields are derived views only, so
-// summing total_tokens across all rows still equals the global usage ledger.
-function annotateCodexThreadUsage(rows) {
+// Attach exact Codex/ZCode parent→child usage without changing the
+// authoritative per-session total_tokens field. Combined fields are derived
+// views only, so summing total_tokens across all rows still equals the global
+// usage ledger. ZCode joins the same lineage pass: its subagent/workflow
+// children carry parent_session_id from the session table, so the browser can
+// nest them under their parent and count them as its subagents.
+function annotateThreadUsage(rows) {
   const byId = new Map();
   const childrenById = new Map();
   const linkedParentById = new Map();
+  const identity = (row, id = row.session_id) => `${row.source}\u0000${id}`;
 
   for (const row of rows || []) {
-    if (row?.source !== "codex" || typeof row.session_id !== "string" || !row.session_id) continue;
-    const existing = byId.get(row.session_id);
+    if ((row?.source !== "codex" && row?.source !== "zcode") || typeof row.session_id !== "string" || !row.session_id) continue;
+    const existing = byId.get(identity(row));
     if (existing && existing !== row) {
       existing.parent_link_conflict = true;
       row.parent_link_conflict = true;
       continue;
     }
-    byId.set(row.session_id, row);
+    byId.set(identity(row), row);
   }
 
   function hasParentCycle(start) {
     const seen = new Set();
     let current = start;
-    while (current?.parent_session_id && byId.has(current.parent_session_id)) {
-      if (seen.has(current.session_id) || current.parent_session_id === current.session_id) return true;
-      seen.add(current.session_id);
-      current = byId.get(current.parent_session_id);
+    while (current?.parent_session_id && byId.has(identity(current, current.parent_session_id))) {
+      if (seen.has(identity(current)) || current.parent_session_id === current.session_id) return true;
+      seen.add(identity(current));
+      current = byId.get(identity(current, current.parent_session_id));
     }
     return false;
   }
@@ -2112,48 +2602,49 @@ function annotateCodexThreadUsage(rows) {
   for (const row of byId.values()) {
     const parentId = typeof row.parent_session_id === "string" ? row.parent_session_id.trim() : "";
     if (!parentId) continue;
+    const parentKey = identity(row, parentId);
     if (row.parent_link_conflict || hasParentCycle(row)) {
       row.parent_link_conflict = true;
       continue;
     }
-    if (!byId.has(parentId)) {
+    if (!byId.has(parentKey)) {
       row.orphaned_subagent = true;
       continue;
     }
-    const children = childrenById.get(parentId) || [];
+    const children = childrenById.get(parentKey) || [];
     children.push(row);
-    childrenById.set(parentId, children);
-    linkedParentById.set(row.session_id, parentId);
+    childrenById.set(parentKey, children);
+    linkedParentById.set(identity(row), parentKey);
   }
 
   const memo = new Map();
   function aggregate(row, visiting = new Set()) {
-    if (memo.has(row.session_id)) return memo.get(row.session_id);
-    if (visiting.has(row.session_id)) {
+    if (memo.has(identity(row))) return memo.get(identity(row));
+    if (visiting.has(identity(row))) {
       row.parent_link_conflict = true;
       return { count: 0, tokens: 0, cost: 0 };
     }
     const nextVisiting = new Set(visiting);
-    nextVisiting.add(row.session_id);
+    nextVisiting.add(identity(row));
     let count = 0;
     let tokens = 0;
     let cost = 0;
-    for (const child of childrenById.get(row.session_id) || []) {
+    for (const child of childrenById.get(identity(row)) || []) {
       const nested = aggregate(child, nextVisiting);
       count += 1 + nested.count;
       tokens += finite(child.total_tokens) + nested.tokens;
       cost += finite(child.cost_usd) + nested.cost;
     }
     const result = { count, tokens, cost };
-    memo.set(row.session_id, result);
+    memo.set(identity(row), result);
     return result;
   }
 
   function rootFor(row) {
-    const seen = new Set([row.session_id]);
+    const seen = new Set([identity(row)]);
     let current = row;
-    while (current && linkedParentById.has(current.session_id)) {
-      const linkedParentId = linkedParentById.get(current.session_id);
+    while (current && linkedParentById.has(identity(current))) {
+      const linkedParentId = linkedParentById.get(identity(current));
       if (seen.has(linkedParentId)) {
         row.parent_link_conflict = true;
         break;
@@ -2165,12 +2656,14 @@ function annotateCodexThreadUsage(rows) {
   }
 
   for (const row of rows || []) {
+    const threadAware = (row.source === "codex" || row.source === "zcode")
+      && typeof row.session_id === "string" && row.session_id;
     row.own_total_tokens = finite(row.total_tokens);
     row.own_cost_usd = finite(row.cost_usd);
-    row.direct_subagent_count = row.source === "codex" && row.session_id
-      ? (childrenById.get(row.session_id) || []).length
+    row.direct_subagent_count = threadAware
+      ? (childrenById.get(identity(row)) || []).length
       : 0;
-    const nested = row.source === "codex" && row.session_id
+    const nested = threadAware
       ? aggregate(row)
       : { count: 0, tokens: 0, cost: 0 };
     row.descendant_subagent_count = nested.count;
@@ -2178,8 +2671,8 @@ function annotateCodexThreadUsage(rows) {
     row.subagent_cost_usd = nested.cost;
     row.combined_total_tokens = finite(row.total_tokens) + nested.tokens;
     row.combined_cost_usd = finite(row.cost_usd) + nested.cost;
-    if (row.source === "codex" && row.session_id) {
-      const parent = byId.get(linkedParentById.get(row.session_id));
+    if (threadAware) {
+      const parent = byId.get(linkedParentById.get(identity(row)));
       row.parent_session_hash = parent?.session_hash || null;
       row.root_session_hash = rootFor(row).session_hash || row.session_hash;
     }
@@ -2193,7 +2686,7 @@ function annotateCodexThreadUsage(rows) {
 // local API.
 function listSessionsForBrowser(sessions, { from = "", to = "", limit = 0, timeZone, offsetMinutes } = {}) {
   const context = { timeZone, offsetMinutes };
-  const filtered = annotateCodexThreadUsage(mergeSessionFragments(sessions)
+  const filtered = annotateThreadUsage(mergeSessionFragments(sessions)
     // Only sessions that actually spent tokens are worth listing. This drops
     // two kinds of noise: non-session logs under ~/.claude/projects
     // (skill-injections.jsonl, journal.jsonl, …), and sessions abandoned before
@@ -2236,6 +2729,7 @@ module.exports = {
   scanClaudeSession,
   scanCodexSession,
   scanGrokSession,
+  scanZcodeSessions,
   buildSessionAnalytics,
   summarizeSessions,
   listSessionsForBrowser,