tokenusage-cli 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/LICENSE +22 -0
  3. package/README.md +94 -0
  4. package/THIRD_PARTY_NOTICES.md +140 -0
  5. package/bin/tokenusage.js +69 -0
  6. package/package.json +59 -0
  7. package/src/cli.js +134 -0
  8. package/src/commands/device-login.js +205 -0
  9. package/src/commands/diagnostics.js +38 -0
  10. package/src/commands/doctor.js +110 -0
  11. package/src/commands/init.js +2436 -0
  12. package/src/commands/sessions.js +29 -0
  13. package/src/commands/status.js +1747 -0
  14. package/src/commands/sync.js +7934 -0
  15. package/src/commands/uninstall.js +312 -0
  16. package/src/lib/account-usage-dedup.js +267 -0
  17. package/src/lib/antigravity-paths.js +48 -0
  18. package/src/lib/ark-agent-plan-limits.js +438 -0
  19. package/src/lib/ark-coding-plan-limits.js +537 -0
  20. package/src/lib/async-queue-reader.js +138 -0
  21. package/src/lib/atomic-json.js +27 -0
  22. package/src/lib/bearer-token.js +11 -0
  23. package/src/lib/categorizer-utils.js +232 -0
  24. package/src/lib/claude-categorizer.js +1343 -0
  25. package/src/lib/claude-config.js +279 -0
  26. package/src/lib/claude-user-identity.js +56 -0
  27. package/src/lib/cli-ui.js +179 -0
  28. package/src/lib/cloud-account.js +541 -0
  29. package/src/lib/cloud-device-token.js +141 -0
  30. package/src/lib/cloud-sync-prefs.js +14 -0
  31. package/src/lib/cloud-usage-reset.js +115 -0
  32. package/src/lib/codex-config.js +595 -0
  33. package/src/lib/codex-context-breakdown.js +806 -0
  34. package/src/lib/codex-model-attribution.js +128 -0
  35. package/src/lib/codex-rollout-parser.js +1471 -0
  36. package/src/lib/codex-service-tier.js +49 -0
  37. package/src/lib/codex-token-refresh.js +140 -0
  38. package/src/lib/codex-token-usage.js +195 -0
  39. package/src/lib/codex-usage-record.js +195 -0
  40. package/src/lib/command-runner.js +313 -0
  41. package/src/lib/commandcode-limits.js +317 -0
  42. package/src/lib/context-health.js +124 -0
  43. package/src/lib/cursor-config.js +605 -0
  44. package/src/lib/cursor-store.js +1918 -0
  45. package/src/lib/debug-flags.js +7 -0
  46. package/src/lib/devin-limits.js +249 -0
  47. package/src/lib/devin-usage.js +212 -0
  48. package/src/lib/diagnostics.js +383 -0
  49. package/src/lib/doctor.js +385 -0
  50. package/src/lib/dumate.js +95 -0
  51. package/src/lib/fs.js +455 -0
  52. package/src/lib/function-url.js +14 -0
  53. package/src/lib/gemini-config.js +291 -0
  54. package/src/lib/git-outcomes.js +243 -0
  55. package/src/lib/grok-context-breakdown.js +890 -0
  56. package/src/lib/grok-hook.js +360 -0
  57. package/src/lib/grok-limits.js +865 -0
  58. package/src/lib/grok-usage.js +98 -0
  59. package/src/lib/heatmap-compact.js +114 -0
  60. package/src/lib/ingest-sanitize.js +41 -0
  61. package/src/lib/init-flow.js +42 -0
  62. package/src/lib/install-resolver.js +170 -0
  63. package/src/lib/jsonl-lines.js +134 -0
  64. package/src/lib/kimi-model-repair.js +173 -0
  65. package/src/lib/kimi-profile.js +61 -0
  66. package/src/lib/kimi-session.js +216 -0
  67. package/src/lib/local-api.js +3588 -0
  68. package/src/lib/machine-id.js +238 -0
  69. package/src/lib/multi-install-parser.js +113 -0
  70. package/src/lib/notify-command.js +38 -0
  71. package/src/lib/omp-hook.js +589 -0
  72. package/src/lib/openclaw-cli.js +104 -0
  73. package/src/lib/openclaw-hook.js +375 -0
  74. package/src/lib/openclaw-session-plugin.js +560 -0
  75. package/src/lib/opencode-config.js +121 -0
  76. package/src/lib/opencode-go-limits.js +807 -0
  77. package/src/lib/outcomes-engine.js +253 -0
  78. package/src/lib/passive-mode.js +219 -0
  79. package/src/lib/pet-packages.js +722 -0
  80. package/src/lib/pricing/curated-overrides.json +822 -0
  81. package/src/lib/pricing/index.js +379 -0
  82. package/src/lib/pricing/litellm-fetcher.js +172 -0
  83. package/src/lib/pricing/matcher.js +456 -0
  84. package/src/lib/pricing/seed-snapshot.json +1 -0
  85. package/src/lib/progress.js +76 -0
  86. package/src/lib/project-usage-purge.js +117 -0
  87. package/src/lib/prompt.js +24 -0
  88. package/src/lib/provider-status.js +104 -0
  89. package/src/lib/proxy-env.js +489 -0
  90. package/src/lib/proxy-settings.js +163 -0
  91. package/src/lib/qoder-cn-cli-limits.js +119 -0
  92. package/src/lib/qoder-limits.js +880 -0
  93. package/src/lib/quiet-warnings.js +26 -0
  94. package/src/lib/rollout.js +25966 -0
  95. package/src/lib/runtime-config.js +259 -0
  96. package/src/lib/scan-roots.js +277 -0
  97. package/src/lib/sentry.js +231 -0
  98. package/src/lib/session-analytics.js +2972 -0
  99. package/src/lib/session-performance.js +237 -0
  100. package/src/lib/session-upload.js +379 -0
  101. package/src/lib/skill-usage.js +267 -0
  102. package/src/lib/skills-manager.js +1591 -0
  103. package/src/lib/source-metadata.js +48 -0
  104. package/src/lib/sqlite-reader.js +215 -0
  105. package/src/lib/star-cta.js +73 -0
  106. package/src/lib/subscription-manager.js +293 -0
  107. package/src/lib/subscriptions.js +508 -0
  108. package/src/lib/telemetry.js +193 -0
  109. package/src/lib/tracker-paths.js +16 -0
  110. package/src/lib/trae-cn-config.js +548 -0
  111. package/src/lib/trae-db.js +127 -0
  112. package/src/lib/trae-snapshot.js +230 -0
  113. package/src/lib/trae-sqlite.js +143 -0
  114. package/src/lib/trae-usage.js +121 -0
  115. package/src/lib/upload-queue.js +134 -0
  116. package/src/lib/upload-throttle.js +171 -0
  117. package/src/lib/usage-limits.js +4552 -0
  118. package/src/lib/wrapped-aggregator.js +236 -0
  119. package/src/lib/wsl-probe.js +281 -0
  120. package/src/lib/zcode-limits.js +1172 -0
  121. package/src/lib/zcode-reset-credits.js +66 -0
  122. package/test/cli-smoke.test.js +53 -0
  123. package/test/ingest-sanitize.test.js +162 -0
  124. package/test/quiet-warnings.test.js +53 -0
  125. package/test/session-upload.test.js +427 -0
@@ -0,0 +1,2972 @@
1
+ "use strict";
2
+
3
+ // Metadata-only session analytics sidecar.
4
+ //
5
+ // Never persisted, anywhere: prompts, assistant message bodies, tool arguments,
6
+ // command output, diffs. Prompts are read only to fingerprint a repeated
7
+ // request (a one-way hash, never stored).
8
+ //
9
+ // Persisted to the LOCAL sidecar only (~/.tokenusage/tracker, 0600 file in a
10
+ // 0700 dir), because the session browser needs them to identify and resume a
11
+ // session:
12
+ // - `title` — the one line the agent wrote to name the session (Claude's
13
+ // "ai-title" record, Codex's thread_name). Agent-authored, not the user's
14
+ // prompt, but it does summarize what the session was about, so treat it as
15
+ // session content: local-only, never uploaded.
16
+ // - `session_id` — the vendor session UUID, needed for `--resume`.
17
+ // - `project_ref` — the session's working directory. The resume command only
18
+ // works from that directory, so the UI shows it and lets the user copy it.
19
+ //
20
+ // All three are stripped in summarizeSessions() before anything reaches the
21
+ // cloud or a CSV export, and the browser endpoint that keeps them is served
22
+ // only over loopback. `test/session-analytics.test.js` guards that boundary —
23
+ // if you add a field here, decide which side of it the field belongs on.
24
+
25
+ const crypto = require("node:crypto");
26
+ const fs = require("node:fs");
27
+ const fsp = require("node:fs/promises");
28
+ const os = require("node:os");
29
+ const path = require("node:path");
30
+ const readline = require("node:readline");
31
+ const { listClaudeProjectFiles, listRolloutFilesDeep, claudeMessageDedupKey, normalizeClaudeUsage, readZcodeDbMessages, coerceEpochMs, resolveZcodeInstallPaths, normalizeOpencodeModelFields, normalizeOpencodeTokens, deriveOpencodeMessageFingerprint } = require("./rollout");
32
+ const { parseCodexRolloutFile } = require("./codex-rollout-parser");
33
+ const { computeRowCost, getModelPricingInfo } = require("./pricing");
34
+ const { normalizePerformance, mergePerformance, createClaudePerformanceCollector, createCodexPerformanceCollector, createZcodePerformanceCollector } = require("./session-performance");
35
+ const { readSqliteJsonRows, readSqliteJsonRowsAsync } = require("./sqlite-reader");
36
+ const { resolveZcodeNativeDbPath, resolveInstallPaths } = require("./install-resolver");
37
+ const { readCursorStateSummary } = require("./cursor-store");
38
+ const { USD_TICKS_PER_USD, normalizeGrokUsage } = require("./grok-usage");
39
+ const wsl = require("./wsl-probe");
40
+ const { discoverKimiWireFiles, kimiSessionDependencies, readKimiSessions } = require("./kimi-session");
41
+ const {
42
+ appendUniqueDirs,
43
+ dedupeDirsByRealpath,
44
+ expandHome,
45
+ loadScanRootsConfig,
46
+ normalizeScanRootsConfig,
47
+ scanRootDirState,
48
+ } = require("./scan-roots");
49
+
50
+ // Bump the sidecar when derived metrics change so cached rows are rebuilt
51
+ // instead of leaving the dashboard on the previous (over-counted) heuristic.
52
+ // v7 adds the raw session_id (local-only, needed to build resume commands for
53
+ // the session browser); it never leaves the Node process through the cloud.
54
+ // v8 adds an agent-authored one-line title: Claude's "ai-title" session-log
55
+ // record and Codex's thread_name from session_index.jsonl. Both are metadata
56
+ // the agent wrote itself, never the raw prompt body, and stay local-only
57
+ // alongside session_id (no self-parsed prompt fallback, so the strict
58
+ // metadata-only guarantee holds).
59
+ // v9 changes derived metrics, so every cached row must be rebuilt:
60
+ // - duration_ms is now *active* time (see IDLE_GAP_MS), not the wall-clock
61
+ // span between the first and last log line, which read as 89 days on
62
+ // resumed/forked sessions.
63
+ // - session_id is only set when the log actually contained a sessionId
64
+ // record. It used to fall back to the file's basename, which produced
65
+ // resume commands for non-session files (`claude --resume journal`).
66
+ // v10 adds Grok Build sessions (~/.grok/sessions/**/updates.jsonl), scanned
67
+ // from turn_completed.usage + tool_call metadata. Bump so Claude/Codex rows
68
+ // stay valid while Grok entries appear on the next full rebuild.
69
+ // v11 groups native/WSL copies of one logical Claude/Codex session and scans
70
+ // their union, deduping shared records while retaining divergent tails.
71
+ // v12 fixes Grok's mutually exclusive token columns, retains exact reported
72
+ // cost, and adds metadata-only usage diagnostics to the local session browser.
73
+ // v13 stores per-model Codex usage (including observed reroutes and the exact
74
+ // long-context subset) and folds delivery signals into the token parser's
75
+ // single pass instead of parsing every Codex file twice.
76
+ // v14 adds request-level estimated performance and Claude model usage.
77
+ // v15/v16 tighten Codex delivery-signal parsing (uncommented bump).
78
+ // v17 adds ZCode sessions from ~/.zcode/cli/db/db.sqlite — one SQLite db
79
+ // scanning to many per-session rows — so every cached row is rebuilt.
80
+ // v18 corrects ZCode project keys and request timestamp units, and invalidates
81
+ // inventories that earlier builds may have cached after a failed database read.
82
+ // v19 scans both ZCode installs as one deduplicated inventory and separates
83
+ // provider retries from repeated user requests.
84
+ // v20 also invalidates unchanged-stat caches after an observed database lock.
85
+ // v21 retains the request count when several ZCode events share a minute.
86
+ // v22 adds metadata-only OpenCode database sessions.
87
+ // v23 excludes database updates and user records from request durations.
88
+ // v24 keeps OpenCode usage dates at event time and fork history on its ancestor.
89
+ // v25 adds Kimi wire sessions, including official/legacy migration dedup.
90
+ const SIDECAR_VERSION = 25;
91
+ const EDIT_TOOLS = new Set([
92
+ "apply_patch",
93
+ "edit",
94
+ "write",
95
+ "multiedit",
96
+ "notebookedit",
97
+ // Grok Build write tools (ACP tool titles / x.ai/tool.name).
98
+ "search_replace",
99
+ "str_replace",
100
+ "create_file",
101
+ "write_file",
102
+ ]);
103
+ const PLACEHOLDER_MODELS = new Set(["<synthetic>", "synthetic", "<unknown>", "unknown"]);
104
+ const CLAUDE_MEM_OBSERVER_PROJECT_SUFFIX = "--claude-mem-observer-sessions";
105
+ const CODEX_SUBAGENT_TOOLS = new Set(["spawn_agent", "multi_agent_v1__spawn_agent"]);
106
+ const CODEX_SIGNAL_TOOLS = new Set([...EDIT_TOOLS, ...CODEX_SUBAGENT_TOOLS]);
107
+ const GROK_SUBAGENT_TOOLS = new Set(["spawn_subagent", "spawn_agent"]);
108
+
109
+ function normalizeSessionModel(value) {
110
+ if (typeof value !== "string") return null;
111
+ const model = value.trim();
112
+ if (!model || PLACEHOLDER_MODELS.has(model.toLowerCase())) return null;
113
+ return model;
114
+ }
115
+
116
+ function resolveSessionSidecarPath(home = os.homedir()) {
117
+ return path.join(home, ".tokenusage", "tracker", "session.queue.jsonl");
118
+ }
119
+
120
+ function sessionHash(source, id) {
121
+ return crypto.createHash("sha256").update(`${source}\0${id || "unknown"}`).digest("hex").slice(0, 24);
122
+ }
123
+
124
+ function finite(value) {
125
+ const number = Number(value || 0);
126
+ return Number.isFinite(number) && number > 0 ? number : 0;
127
+ }
128
+
129
+ function tokenTotals(usage) {
130
+ const input_tokens = finite(usage?.input_tokens);
131
+ const cached_input_tokens = finite(usage?.cache_read_input_tokens ?? usage?.cached_input_tokens);
132
+ const cache_creation_input_tokens = finite(usage?.cache_creation_input_tokens);
133
+ const output_tokens = finite(usage?.output_tokens);
134
+ const reasoning_output_tokens = finite(usage?.reasoning_output_tokens);
135
+ const total_tokens = input_tokens + cached_input_tokens + cache_creation_input_tokens + output_tokens;
136
+ return { input_tokens, cached_input_tokens, cache_creation_input_tokens, output_tokens, reasoning_output_tokens, total_tokens };
137
+ }
138
+
139
+ function addTotals(target, delta) {
140
+ for (const key of ["input_tokens", "cached_input_tokens", "cache_creation_input_tokens", "output_tokens", "reasoning_output_tokens", "total_tokens"]) {
141
+ target[key] = finite(target[key]) + finite(delta?.[key]);
142
+ }
143
+ for (const key of MODEL_USAGE_SUM_FIELDS) {
144
+ if (!/^(?:long_context_|priority_)|^(?:usage_events|rerouted_usage_events)$/.test(key)) continue;
145
+ if (delta?.[key]) target[key] = finite(target[key]) + finite(delta[key]);
146
+ }
147
+ }
148
+
149
+ function emptyTotals() {
150
+ return tokenTotals({});
151
+ }
152
+
153
+ function mergeUsageMetadata(target, usage) {
154
+ for (const field of ["selected_models", "reroute_reasons"]) {
155
+ if (Array.isArray(usage[field])) target[field] = [...new Set([...(target[field] || []), ...usage[field]])];
156
+ }
157
+ if (usage.model_attribution === "effective") target.model_attribution = "effective";
158
+ }
159
+
160
+ const MODEL_USAGE_SUM_FIELDS = [
161
+ "input_tokens",
162
+ "cached_input_tokens",
163
+ "cache_creation_input_tokens",
164
+ "output_tokens",
165
+ "reasoning_output_tokens",
166
+ "total_tokens",
167
+ "long_context_input_tokens",
168
+ "long_context_cached_input_tokens",
169
+ "long_context_cache_creation_input_tokens",
170
+ "long_context_output_tokens",
171
+ "long_context_reasoning_output_tokens",
172
+ "priority_input_tokens",
173
+ "priority_cached_input_tokens",
174
+ "priority_cache_creation_input_tokens",
175
+ "priority_output_tokens",
176
+ "priority_reasoning_output_tokens",
177
+ "priority_long_context_input_tokens",
178
+ "priority_long_context_cached_input_tokens",
179
+ "priority_long_context_cache_creation_input_tokens",
180
+ "priority_long_context_output_tokens",
181
+ "priority_long_context_reasoning_output_tokens",
182
+ "usage_events",
183
+ "rerouted_usage_events",
184
+ "long_context_usage_events",
185
+ "priority_usage_events",
186
+ // Not a token counter: an edit turn is a turn, and turn_context both marks
187
+ // where a turn begins and names its model, so an edit turn has exactly one
188
+ // owner. Splitting it here keeps by_model.tokens_per_edit a ratio over one
189
+ // population instead of this model's tokens over the whole session's turns.
190
+ "edit_turns",
191
+ ];
192
+
193
+ function normalizeModelUsageRows(rows) {
194
+ const byModel = new Map();
195
+ for (const value of Array.isArray(rows) ? rows : []) {
196
+ const model = normalizeSessionModel(value?.model) || "unknown";
197
+ let row = byModel.get(model);
198
+ if (!row) {
199
+ row = {
200
+ model,
201
+ ...Object.fromEntries(MODEL_USAGE_SUM_FIELDS.map((field) => [field, 0])),
202
+ selected_models: new Set(),
203
+ reroute_reasons: new Set(),
204
+ model_attribution: "selected",
205
+ performance: normalizePerformance(),
206
+ };
207
+ byModel.set(model, row);
208
+ }
209
+ for (const field of MODEL_USAGE_SUM_FIELDS) row[field] += finite(value?.[field]);
210
+ row.performance = mergePerformance(row.performance, value?.performance);
211
+ if (Array.isArray(value?.selected_models)) {
212
+ for (const selected of value.selected_models) {
213
+ const normalized = normalizeSessionModel(selected);
214
+ if (normalized) row.selected_models.add(normalized);
215
+ }
216
+ } else if (model !== "unknown") {
217
+ // serializeModelUsageRow() omits selected_models when it is just the
218
+ // effective model repeated. An absent field therefore means "selected
219
+ // == effective", which is the case for every non-rerouted row.
220
+ row.selected_models.add(model);
221
+ }
222
+ for (const reason of Array.isArray(value?.reroute_reasons) ? value.reroute_reasons : []) {
223
+ if (typeof reason === "string" && reason.trim()) row.reroute_reasons.add(reason.trim());
224
+ }
225
+ if (value?.model_attribution === "effective" || finite(value?.rerouted_usage_events) > 0) {
226
+ row.model_attribution = "effective";
227
+ }
228
+ }
229
+ return [...byModel.values()]
230
+ .filter((row) => ["total_tokens", "input_tokens", "cached_input_tokens", "cache_creation_input_tokens", "output_tokens", "reasoning_output_tokens"]
231
+ .some((field) => row[field] > 0))
232
+ .map((row) => ({
233
+ ...row,
234
+ selected_models: [...row.selected_models].sort(),
235
+ reroute_reasons: [...row.reroute_reasons].sort(),
236
+ }))
237
+ .sort((a, b) => b.total_tokens - a.total_tokens || a.model.localeCompare(b.model));
238
+ }
239
+
240
+ // The sidecar is re-read on every dashboard request, so keep it small: omit
241
+ // the model_usage fields that normalizeModelUsageRows() reconstructs on read.
242
+ // These omissions are lossless - zero counters default to 0, an absent
243
+ // selected_models re-seeds from `model`, model_attribution is derived from
244
+ // rerouted_usage_events, and cost_usd/pricing are always recomputed by
245
+ // repriceSessionRecord(). Worth ~19% of the file on a 6.8k-session history,
246
+ // most of it the long_context_* counters for sessions with no requests over
247
+ // OPENAI_LONG_CONTEXT_INPUT_THRESHOLD in src/lib/pricing/index.js.
248
+ function serializeModelUsageRow(row) {
249
+ const out = { model: row.model };
250
+ for (const field of MODEL_USAGE_SUM_FIELDS) {
251
+ const value = finite(row[field]);
252
+ if (value !== 0) out[field] = value;
253
+ }
254
+ const selected = Array.isArray(row.selected_models) ? row.selected_models : [];
255
+ if (!(selected.length === 1 && selected[0] === row.model)) out.selected_models = selected;
256
+ if (Array.isArray(row.reroute_reasons) && row.reroute_reasons.length > 0) {
257
+ out.reroute_reasons = row.reroute_reasons;
258
+ }
259
+ if (row.model_attribution === "effective") out.model_attribution = "effective";
260
+ if (row.performance?.estimated_request_count || row.performance?.first_response_sample_count) out.performance = row.performance;
261
+ return out;
262
+ }
263
+
264
+ function serializeSessionRecord(row) {
265
+ if (!Array.isArray(row?.model_usage) || row.model_usage.length === 0) {
266
+ return JSON.stringify(row);
267
+ }
268
+ return JSON.stringify({ ...row, model_usage: row.model_usage.map(serializeModelUsageRow) });
269
+ }
270
+
271
+ function repriceSessionRecord(record) {
272
+ if (Array.isArray(record.usage_buckets)) {
273
+ record.usage_buckets = record.usage_buckets.map((bucket) => ({
274
+ ...bucket, cost_usd: computeRowCost({ source: record.source, ...bucket }),
275
+ }));
276
+ }
277
+ const modelUsage = normalizeModelUsageRows(record?.model_usage);
278
+ if (modelUsage.length > 0) {
279
+ let hasUnpricedUsage = false;
280
+ for (const row of modelUsage) {
281
+ row.cost_usd = computeRowCost({ source: record.source, ...row });
282
+ row.pricing = getModelPricingInfo(row.model, { source: record.source });
283
+ if (row.total_tokens > 0 && row.pricing.status === "unpriced") hasUnpricedUsage = true;
284
+ }
285
+ record.model_usage = modelUsage;
286
+ record.model = modelUsage.length > 1 ? "mixed" : modelUsage[0].model;
287
+ if (record.cost_source === "provider_reported" && Number.isFinite(Number(record.provider_cost_usd)) && Number(record.provider_cost_usd) >= 0) {
288
+ record.cost_usd = Number(record.provider_cost_usd);
289
+ if (modelUsage.length === 1) modelUsage[0].cost_usd = record.cost_usd;
290
+ } else {
291
+ record.cost_usd = modelUsage.reduce((sum, row) => sum + finite(row.cost_usd), 0);
292
+ record.cost_source = "model_pricing";
293
+ record.cost_is_partial = hasUnpricedUsage;
294
+ }
295
+ // Internal labels such as `codex-auto-review` expose token usage but not
296
+ // an underlying public model/rate. Keep their tokens, leave their cost at
297
+ // zero, and explicitly mark the session estimate as a known lower bound.
298
+ } else {
299
+ const providerCost = Number(record.provider_cost_usd);
300
+ record.cost_usd = record.cost_source === "provider_reported"
301
+ && Number.isFinite(providerCost)
302
+ && providerCost >= 0
303
+ ? providerCost
304
+ : computeRowCost({ source: record.source, model: record.model, ...record.tokens });
305
+ if (record.cost_source !== "provider_reported" && finite(record.total_tokens || record.tokens?.total_tokens) > 0
306
+ && getModelPricingInfo(record.model, { source: record.source }).status === "unpriced") record.cost_is_partial = true;
307
+ }
308
+ record.cost_per_edit = record.edit_turns > 0 ? record.cost_usd / record.edit_turns : null;
309
+ return record;
310
+ }
311
+
312
+ // The model_usage wire contract is DENSE: every field dashboard/src/lib/
313
+ // sessions-api.ts declares is present on every row. Storage is free to be
314
+ // sparse - serializeModelUsageRow() drops zero counters, and a record with no
315
+ // model_usage at all (Grok sessions and sessions written
316
+ // by an older sidecar) has nothing to trim in the first place - but neither
317
+ // shape may leak into an API response, or the declared type describes a row
318
+ // that does not exist. Densify here, the one point both the by_model
319
+ // aggregation and toSessionBrowserRow() pass through.
320
+ function denseModelUsageRow(overrides = {}) {
321
+ return {
322
+ model: "unknown",
323
+ ...Object.fromEntries(MODEL_USAGE_SUM_FIELDS.map((field) => [field, 0])),
324
+ selected_models: [],
325
+ reroute_reasons: [],
326
+ model_attribution: "selected",
327
+ cost_usd: 0,
328
+ performance: normalizePerformance(),
329
+ ...overrides,
330
+ };
331
+ }
332
+
333
+ function modelUsageForAggregation(record) {
334
+ const editTurns = finite(record?.edit_turns);
335
+ const rows = normalizeModelUsageRows(record?.model_usage);
336
+ if (rows.length === 0) {
337
+ return [denseModelUsageRow({
338
+ model: normalizeSessionModel(record?.model) || "unknown",
339
+ ...record?.tokens,
340
+ total_tokens: finite(record?.total_tokens || record?.tokens?.total_tokens),
341
+ cost_usd: finite(record?.cost_usd),
342
+ edit_turns: editTurns,
343
+ performance: normalizePerformance(record?.performance),
344
+ pricing: getModelPricingInfo(record?.model, { source: record?.source }),
345
+ })];
346
+ }
347
+ const priced = rows.map((row) => denseModelUsageRow({
348
+ ...row,
349
+ pricing: getModelPricingInfo(row.model, { source: record.source }),
350
+ cost_usd: Number.isFinite(Number(row.cost_usd))
351
+ ? Number(row.cost_usd)
352
+ : computeRowCost({ source: record.source, ...row }),
353
+ }));
354
+ if (record.cost_source === "provider_reported" && priced.length === 1) priced[0].cost_usd = finite(record.cost_usd);
355
+ // Sum(rows.edit_turns) has to equal record.edit_turns or the by_model column
356
+ // stops summing to summary.edit_turns. It can fall short two ways: a sidecar
357
+ // written before model_usage carried edit_turns, and an edit turn whose model
358
+ // produced no billable delta, leaving no usage row to attach to. Fold the
359
+ // residual into the busiest model - normalizeModelUsageRows() sorts by
360
+ // total_tokens - which is the same approximation `retries` uses.
361
+ const assigned = priced.reduce((sum, row) => sum + finite(row.edit_turns), 0);
362
+ const residual = editTurns - assigned;
363
+ if (residual > 0) priced[0].edit_turns = finite(priced[0].edit_turns) + residual;
364
+ return priced;
365
+ }
366
+
367
+ function safeTimestamp(value) {
368
+ if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) return null;
369
+ return new Date(value).toISOString();
370
+ }
371
+
372
+ // A session that was resumed days later, or whose file replays inherited
373
+ // history from a fork, spans a wall-clock range that says nothing about how
374
+ // long the user actually worked (observed: 2142h / 89 days on a session with
375
+ // zero turns). Accumulate *active* time instead: the sum of gaps between
376
+ // consecutive log timestamps, excluding any gap longer than IDLE_GAP_MS. The
377
+ // long jump from replayed history to real work is one such gap, so it drops
378
+ // out on its own. started_at / ended_at still carry the true span.
379
+ const IDLE_GAP_MS = 30 * 60 * 1000;
380
+
381
+ function emptyBounds() {
382
+ return { started_at: null, ended_at: null, active_ms: 0, _last_ts_ms: null };
383
+ }
384
+
385
+ function updateBounds(bounds, value) {
386
+ const timestamp = safeTimestamp(value);
387
+ if (!timestamp) return;
388
+ if (!bounds.started_at || timestamp < bounds.started_at) bounds.started_at = timestamp;
389
+ if (!bounds.ended_at || timestamp > bounds.ended_at) bounds.ended_at = timestamp;
390
+ const ms = Date.parse(timestamp);
391
+ if (!Number.isFinite(ms)) return;
392
+ if (Number.isFinite(bounds._last_ts_ms)) {
393
+ const delta = ms - bounds._last_ts_ms;
394
+ // Ignore out-of-order lines and idle gaps; only real working time counts.
395
+ if (delta > 0 && delta <= IDLE_GAP_MS) bounds.active_ms += delta;
396
+ }
397
+ bounds._last_ts_ms = ms;
398
+ }
399
+
400
+ // Throwaway per-agent checkouts (`.claude/worktrees/<id>`, `.codex/worktrees/…`)
401
+ // are not the project the user is working on, and the directory is usually gone
402
+ // by the time the session is browsed.
403
+ function isWorktreeRef(ref) {
404
+ return /[\\/](worktrees|subagents)[\\/]/.test(String(ref || ""));
405
+ }
406
+
407
+ function projectKey(cwd, filePath) {
408
+ const value = cwd || path.dirname(filePath || "");
409
+ return path.basename(String(value).replace(/[\\/]+$/, "")) || "unknown";
410
+ }
411
+
412
+ function extractClaudePrompt(obj) {
413
+ if (!obj || obj.type !== "user" || obj.isMeta) return null;
414
+ const content = obj.message?.content;
415
+ if (Array.isArray(content)) {
416
+ if (content.length > 0 && content.every((block) => block?.type === "tool_result")) return null;
417
+ const text = content
418
+ .filter((block) => block?.type === "text" && typeof block.text === "string")
419
+ .map((block) => block.text)
420
+ .join("\n")
421
+ .trim();
422
+ if (!text) return null;
423
+ if (text === "[Request interrupted by user]" || text.startsWith("<task-notification>")) return null;
424
+ return text;
425
+ }
426
+ if (typeof content !== "string") return null;
427
+ const text = content.trim();
428
+ if (!text || text === "[Request interrupted by user]" || text.startsWith("<task-notification>")) return null;
429
+ return text;
430
+ }
431
+
432
+ function promptFingerprint(prompt) {
433
+ return crypto.createHash("sha256").update(prompt.replace(/\s+/g, " ")).digest("hex");
434
+ }
435
+
436
+ // Normalize a session title into a single short line. Titles come ONLY from
437
+ // the agent's own metadata (Claude's ai-title, Codex's thread_name) — never
438
+ // the raw prompt body — so the metadata-only privacy guarantee holds. They
439
+ // stay local-only alongside session_id.
440
+ function cleanSessionTitle(value) {
441
+ if (typeof value !== "string") return null;
442
+ const text = value.replace(/\s+/g, " ").trim();
443
+ if (!text) return null;
444
+ return text.length > 120 ? `${text.slice(0, 117).trimEnd()}…` : text;
445
+ }
446
+
447
+ function extractCodexPrompt(obj) {
448
+ if (obj?.type !== "event_msg" || obj.payload?.type !== "user_message") return null;
449
+ if (typeof obj.payload.message === "string") {
450
+ const message = obj.payload.message.trim();
451
+ return message || null;
452
+ }
453
+ const elements = Array.isArray(obj.payload.text_elements) ? obj.payload.text_elements : [];
454
+ const text = elements
455
+ .map((item) => {
456
+ if (typeof item === "string") return item;
457
+ if (typeof item?.text === "string") return item.text;
458
+ if (typeof item?.value === "string") return item.value;
459
+ return "";
460
+ })
461
+ .filter(Boolean)
462
+ .join("\n")
463
+ .trim();
464
+ return text || null;
465
+ }
466
+
467
+ function canonicalToolName(value) {
468
+ const name = String(value || "").trim().toLowerCase();
469
+ if (!name) return "";
470
+ return name.replace(/^functions[.:/]/, "").replace(/^tools[.:/]/, "");
471
+ }
472
+
473
+ function extractCodexSignalTools(payload) {
474
+ if (!payload || !["function_call", "custom_tool_call"].includes(payload.type)) return [];
475
+ const directName = canonicalToolName(payload.name);
476
+ if (directName && directName !== "exec") return [directName];
477
+ if (directName !== "exec" || typeof payload.input !== "string") return [];
478
+
479
+ const names = [];
480
+ for (const name of CODEX_SIGNAL_TOOLS) {
481
+ const pattern = new RegExp(`\\btools\\.${name}\\s*\\(`, "gi");
482
+ for (const _match of payload.input.matchAll(pattern)) names.push(name);
483
+ }
484
+ return names;
485
+ }
486
+
487
+ function finalizeRecord(record) {
488
+ delete record._last_ts_ms;
489
+ record.active_ms = Math.max(0, finite(record.active_ms));
490
+ record.duration_ms = record.active_ms;
491
+ record.total_tokens = finite(record.total_tokens || record.tokens?.total_tokens);
492
+ record.performance = normalizePerformance(record.performance);
493
+ repriceSessionRecord(record);
494
+ record.productive = record.edit_turns > 0;
495
+ // A first-pass delivery has exactly one user turn containing an observed
496
+ // edit and no repeated user request. The legacy one_shot field stays as an
497
+ // API/CSV alias, but now follows this cross-provider definition.
498
+ record.first_pass = record.edit_turns === 1 && record.retry_turns === 0;
499
+ record.one_shot = record.first_pass;
500
+ record.tokens_per_edit = record.edit_turns > 0 ? record.total_tokens / record.edit_turns : null;
501
+ record.cost_per_edit = record.edit_turns > 0 ? record.cost_usd / record.edit_turns : null;
502
+ return record;
503
+ }
504
+
505
+ function sessionStorageUsage(filePaths) {
506
+ let bytes = 0;
507
+ const allocated = process.platform !== "win32";
508
+ for (const file of new Set(filePaths)) {
509
+ try {
510
+ const stat = fs.statSync(file);
511
+ if (!stat.isFile()) continue;
512
+ bytes += allocated && Number.isFinite(stat.blocks) ? stat.blocks * 512 : stat.size;
513
+ } catch { /* deleted or unreadable while scanning */ }
514
+ }
515
+ return { session_store_bytes: bytes, session_store_metric: allocated ? "allocated" : "logical" };
516
+ }
517
+
518
+ function readableSessionPaths(filePath) {
519
+ const candidates = (Array.isArray(filePath) ? filePath : [filePath]).filter(Boolean);
520
+ const readable = candidates.filter((value) => sessionFileStatKey(value));
521
+ if (!readable.length) {
522
+ throw new Error("session files vanished before they could be scanned");
523
+ }
524
+ return readable;
525
+ }
526
+
527
+ function isRecoverableSessionReadError(error) {
528
+ return ["ENOENT", "EACCES", "EPERM", "EISDIR", "EIO", "ESTALE"].includes(error?.code);
529
+ }
530
+
531
+ async function scanClaudeSession(filePath) {
532
+ // Native and WSL mounts can disappear independently after discovery. Keep
533
+ // the surviving mirror instead of dropping the whole logical session.
534
+ const filePaths = readableSessionPaths(filePath);
535
+ const primaryFilePath = filePaths[0] || String(filePath || "");
536
+ const tokens = emptyTotals();
537
+ // One logical cross-root group is cached and scanned as a unit, so widening
538
+ // this set across that group stays deterministic. Unrelated files (including
539
+ // same-UUID siblings inside one root) are never grouped here.
540
+ const seenMessages = new Set();
541
+ const performanceCollector = createClaudePerformanceCollector();
542
+ const modelUsageByModel = new Map();
543
+ const editTurnsByModel = new Map();
544
+ const bounds = emptyBounds();
545
+ // The basename keeps grouping stable for files that never write a sessionId
546
+ // record, but only an *observed* sessionId may become a resumable
547
+ // session_id — otherwise non-session logs under ~/.claude/projects (e.g.
548
+ // skill-injections.jsonl, journal.jsonl) yield `claude --resume journal`,
549
+ // a command that always fails.
550
+ let rawSessionId = path.basename(primaryFilePath, ".jsonl");
551
+ let observedSessionId = null;
552
+ let cwd = null;
553
+ let model = "unknown";
554
+ let aiTitle = null;
555
+ let turns = 0;
556
+ let editTurns = 0;
557
+ let retryTurns = 0;
558
+ let currentHadEdit = false;
559
+ let currentTurnModel = null;
560
+ let subagentCalls = 0;
561
+ const subagentTypes = new Map();
562
+
563
+ function closeTurn() {
564
+ if (currentHadEdit) {
565
+ editTurns += 1;
566
+ const key = currentTurnModel || "unknown";
567
+ editTurnsByModel.set(key, (editTurnsByModel.get(key) || 0) + 1);
568
+ }
569
+ currentHadEdit = false;
570
+ }
571
+ let lastPromptFingerprint = null;
572
+
573
+ // A native path and a WSL path can expose the same logical session with a
574
+ // shared prefix and different tails. Scan every tail, but suppress records
575
+ // already present in an earlier root. Hashes stay in-memory only, preserving
576
+ // the metadata-only persistence contract.
577
+ const priorRecordHashes = new Set();
578
+ let scannedFiles = 0;
579
+ for (const currentFilePath of filePaths) {
580
+ const currentRecordHashes = new Set();
581
+ try {
582
+ const input = fs.createReadStream(currentFilePath, { encoding: "utf8" });
583
+ const lines = readline.createInterface({ input, crlfDelay: Infinity });
584
+ for await (const line of lines) {
585
+ if (filePaths.length > 1) {
586
+ const recordHash = crypto.createHash("sha256").update(line).digest("base64url");
587
+ if (priorRecordHashes.has(recordHash)) continue;
588
+ currentRecordHashes.add(recordHash);
589
+ }
590
+ let obj;
591
+ try { obj = JSON.parse(line); } catch { continue; }
592
+ const timingKey = claudeMessageDedupKey(obj);
593
+ const countedUsage = obj.type === "assistant" && obj.message && (!timingKey || !seenMessages.has(timingKey))
594
+ ? normalizeClaudeUsage(obj.message.usage) : null;
595
+ performanceCollector.consume(obj, timingKey, countedUsage, normalizeSessionModel(obj.message?.model) || model);
596
+ updateBounds(bounds, obj.timestamp || obj.message?.timestamp);
597
+ if (typeof obj.sessionId === "string" && obj.sessionId) {
598
+ rawSessionId = obj.sessionId;
599
+ observedSessionId = obj.sessionId;
600
+ }
601
+ if (typeof obj.cwd === "string" && obj.cwd) cwd = obj.cwd;
602
+ // Claude writes its own generated one-line summary as an "ai-title" record.
603
+ // It is agent-authored metadata (not the raw prompt body); keep the latest.
604
+ if (obj.type === "ai-title" && typeof obj.aiTitle === "string") {
605
+ const cleaned = cleanSessionTitle(obj.aiTitle);
606
+ if (cleaned) aiTitle = cleaned;
607
+ continue;
608
+ }
609
+ if (obj.type === "user") {
610
+ const prompt = extractClaudePrompt(obj);
611
+ if (!prompt) continue;
612
+ const fingerprint = promptFingerprint(prompt);
613
+ if (lastPromptFingerprint && fingerprint === lastPromptFingerprint) retryTurns += 1;
614
+ lastPromptFingerprint = fingerprint;
615
+ closeTurn();
616
+ turns += 1;
617
+ continue;
618
+ }
619
+ if (obj.type !== "assistant" || !obj.message) continue;
620
+ const dedupKey = claudeMessageDedupKey(obj);
621
+ if (dedupKey && seenMessages.has(dedupKey)) continue;
622
+ if (dedupKey) seenMessages.add(dedupKey);
623
+ // Claude writes internal summary/observer messages with model
624
+ // "<synthetic>". They are not a billable model and can appear after the
625
+ // real assistant messages in the same session. Keep the latest real
626
+ // model instead of letting that marker overwrite it.
627
+ const candidateModel = normalizeSessionModel(obj.message.model);
628
+ if (candidateModel) model = candidateModel;
629
+ currentTurnModel = model;
630
+ const usage = normalizeClaudeUsage(obj.message.usage);
631
+ addTotals(tokens, usage);
632
+ if (usage.total_tokens > 0) {
633
+ const modelUsage = modelUsageByModel.get(model) || { model, ...emptyTotals(), usage_events: 0 };
634
+ addTotals(modelUsage, usage);
635
+ modelUsage.usage_events += 1;
636
+ modelUsageByModel.set(model, modelUsage);
637
+ }
638
+ const content = Array.isArray(obj.message.content) ? obj.message.content : [];
639
+ for (const block of content) {
640
+ if (!block || block.type !== "tool_use") continue;
641
+ const name = String(block.name || "").toLowerCase();
642
+ if (EDIT_TOOLS.has(name)) currentHadEdit = true;
643
+ if (name === "agent" || name === "task") {
644
+ subagentCalls += 1;
645
+ const subtype = typeof block.input?.subagent_type === "string"
646
+ ? block.input.subagent_type.trim().slice(0, 64)
647
+ : "unspecified";
648
+ subagentTypes.set(subtype || "unspecified", (subagentTypes.get(subtype || "unspecified") || 0) + 1);
649
+ }
650
+ }
651
+ }
652
+ scannedFiles += 1;
653
+ } catch (error) {
654
+ if (!isRecoverableSessionReadError(error)) throw error;
655
+ } finally {
656
+ for (const recordHash of currentRecordHashes) priorRecordHashes.add(recordHash);
657
+ }
658
+ }
659
+ if (!scannedFiles) throw new Error("all grouped Claude session files failed during read");
660
+ closeTurn();
661
+ const performance = performanceCollector.finish();
662
+ return finalizeRecord({
663
+ version: SIDECAR_VERSION,
664
+ session_hash: sessionHash("claude", rawSessionId),
665
+ session_id: observedSessionId || null,
666
+ // Claude's own generated one-line title (the "ai-title" record). Agent-
667
+ // authored metadata, never the raw prompt body. Local-only: stripped in
668
+ // summarizeSessions before any cloud/CSV export. Null when Claude never
669
+ // wrote one — the UI then falls back to the project name.
670
+ title: aiTitle,
671
+ source: "claude",
672
+ ...sessionStorageUsage(filePaths),
673
+ project_key: projectKey(cwd, primaryFilePath),
674
+ project_ref: cwd || null,
675
+ model,
676
+ model_usage: [...modelUsageByModel.values()].map((row) => ({
677
+ ...row,
678
+ edit_turns: finite(editTurnsByModel.get(row.model)),
679
+ performance: performance.byModel.get(row.model) || normalizePerformance(),
680
+ })),
681
+ performance: performance.performance,
682
+ ...bounds,
683
+ turns,
684
+ edit_turns: editTurns,
685
+ retry_turns: retryTurns,
686
+ subagent_calls: subagentCalls,
687
+ subagent_types: Object.fromEntries([...subagentTypes.entries()].sort()),
688
+ tokens,
689
+ provenance: { source: "local-session-log", confidence: "observed", retry_confidence: "inferred", content_retained: false },
690
+ });
691
+ }
692
+
693
+ function createCodexDeliverySignalCollector() {
694
+ const bounds = emptyBounds();
695
+ let turns = 0;
696
+ let editTurns = 0;
697
+ let retryTurns = 0;
698
+ let currentTurnOpen = false;
699
+ let currentTurnKey = null;
700
+ let currentHadEdit = false;
701
+ let hasTurnContext = false;
702
+ let lastPromptFingerprint = null;
703
+ let subagentCalls = 0;
704
+ const subagentTypes = new Map();
705
+ // The model the open turn belongs to, as decided by codex-model-attribution.
706
+ // The parser hands it in rather than this collector re-reading
707
+ // turn_context.payload.model, so there stays exactly one authority on which
708
+ // model owns a turn - the same one that bills the turn's tokens.
709
+ let currentTurnModel = null;
710
+ const editTurnsByModel = new Map();
711
+
712
+ function closeTurn() {
713
+ if (currentTurnOpen && currentHadEdit) {
714
+ editTurns += 1;
715
+ const key = currentTurnModel || "unknown";
716
+ editTurnsByModel.set(key, (editTurnsByModel.get(key) || 0) + 1);
717
+ }
718
+ currentHadEdit = false;
719
+ }
720
+
721
+ function beginTurn(key, model) {
722
+ if (currentTurnOpen && key && currentTurnKey === key) return;
723
+ if (currentTurnOpen) closeTurn();
724
+ currentTurnOpen = true;
725
+ currentTurnKey = key || null;
726
+ currentTurnModel = model || null;
727
+ turns += 1;
728
+ }
729
+
730
+ function consume(obj, model = null) {
731
+ updateBounds(bounds, obj?.timestamp);
732
+ if (obj?.type === "turn_context") {
733
+ hasTurnContext = true;
734
+ beginTurn(String(obj.payload?.turn_id || obj.timestamp || turns + 1), model);
735
+ return;
736
+ }
737
+ // Between two turn_context rows the attributed model only moves when a
738
+ // model/rerouted event fires mid-turn. recordModelUsage() bills the rest of
739
+ // the turn's tokens to the new model, so the turn's edits have to move with
740
+ // them - otherwise one turn's tokens and its edit count land on two
741
+ // different rows and by_model.tokens_per_edit divides across models.
742
+ if (currentTurnOpen && model && model !== currentTurnModel) currentTurnModel = model;
743
+ const prompt = extractCodexPrompt(obj);
744
+ if (prompt) {
745
+ const fingerprint = promptFingerprint(prompt);
746
+ if (lastPromptFingerprint && fingerprint === lastPromptFingerprint) retryTurns += 1;
747
+ lastPromptFingerprint = fingerprint;
748
+ if (!hasTurnContext) beginTurn(String(obj.timestamp || turns + 1), model);
749
+ return;
750
+ }
751
+ if (obj?.type !== "response_item") return;
752
+ const toolNames = extractCodexSignalTools(obj.payload);
753
+ if (!toolNames.length) return;
754
+ if (!currentTurnOpen) beginTurn(String(obj.timestamp || turns + 1), model);
755
+ if (toolNames.some((name) => EDIT_TOOLS.has(name))) currentHadEdit = true;
756
+ for (const name of toolNames) {
757
+ if (!CODEX_SUBAGENT_TOOLS.has(name)) continue;
758
+ subagentCalls += 1;
759
+ const displayName = name === "multi_agent_v1__spawn_agent" ? "spawn_agent" : name;
760
+ subagentTypes.set(displayName, (subagentTypes.get(displayName) || 0) + 1);
761
+ }
762
+ }
763
+
764
+ function finish() {
765
+ closeTurn();
766
+ return {
767
+ bounds,
768
+ turns,
769
+ editTurns,
770
+ editTurnsByModel: Object.fromEntries(editTurnsByModel),
771
+ retryTurns,
772
+ subagentCalls,
773
+ subagentTypes: Object.fromEntries([...subagentTypes.entries()].sort()),
774
+ };
775
+ }
776
+
777
+ return { consume, finish };
778
+ }
779
+
780
+ async function scanCodexSession(filePath) {
781
+ const filePaths = readableSessionPaths(filePath);
782
+ const primaryFilePath = filePaths[0] || String(filePath || "");
783
+ const signalCollector = createCodexDeliverySignalCollector();
784
+ const performanceCollector = createCodexPerformanceCollector();
785
+ const usageBuckets = new Map();
786
+ const parsed = await parseCodexRolloutFile(filePaths, {
787
+ seenTokenEvents: new Set(),
788
+ collectBreakdowns: false,
789
+ collectModelUsage: true,
790
+ onObject(obj, model) {
791
+ signalCollector.consume(obj, model);
792
+ performanceCollector.consume(obj, model);
793
+ },
794
+ onUsage(event) {
795
+ if (event.origin !== "compaction") performanceCollector.consumeUsage(event);
796
+ if (!event.delta || event.delta.total_tokens <= 0) return;
797
+ const ms = Date.parse(event.timestamp);
798
+ if (!Number.isFinite(ms)) return;
799
+ // Minute buckets preserve every current IANA local-midnight boundary
800
+ // and every integer tz_offset_minutes accepted by the local API.
801
+ const timestamp = new Date(Math.floor(ms / 60_000) * 60_000).toISOString();
802
+ const key = `${timestamp}\u0000${event.model}`;
803
+ const bucket = usageBuckets.get(key) || { timestamp, model: event.model || "unknown", ...emptyTotals() };
804
+ addTotals(bucket, event.delta);
805
+ mergeUsageMetadata(bucket, event.delta);
806
+ usageBuckets.set(key, bucket);
807
+ },
808
+ });
809
+ const signals = signalCollector.finish();
810
+ const performance = performanceCollector.finish();
811
+ // The collector keyed edit turns by the model the parser handed it, so the
812
+ // keys are the same raw model ids parsed.modelUsage rows carry. A model whose
813
+ // edit turns produced no billable delta has no row to land on;
814
+ // modelUsageForAggregation() folds that residual into the busiest model so
815
+ // the by_model column still sums to edit_turns.
816
+ const editTurnsByModel = signals.editTurnsByModel || {};
817
+ const modelUsage = (parsed.modelUsage || []).map((row) => ({
818
+ ...row,
819
+ edit_turns: finite(editTurnsByModel[row.model]),
820
+ performance: performance.byModel.get(row.model) || normalizePerformance(),
821
+ }));
822
+ const parsedModel = normalizeSessionModel(parsed.model);
823
+ const provider = normalizeSessionModel(parsed.provider);
824
+ // Older Codex rollouts can omit turn_context.model. The shared parser then
825
+ // falls back to model_provider (for example "openai"), which is provenance
826
+ // rather than a model and must not become a model-table row.
827
+ const observedModels = (parsed.modelUsage || [])
828
+ .map((row) => normalizeSessionModel(row.model))
829
+ .filter(Boolean);
830
+ const model = observedModels.length > 1
831
+ ? "mixed"
832
+ : observedModels[0] || (
833
+ parsedModel && parsedModel.toLowerCase() !== provider?.toLowerCase()
834
+ ? parsedModel
835
+ : "unknown"
836
+ );
837
+ // Codex's own thread title from session_index.jsonl (Codex-authored
838
+ // metadata, keyed by session id). Null when Codex never named the thread —
839
+ // the UI then falls back to the project name.
840
+ const title = parsed.sessionId
841
+ ? filePaths.map(loadCodexTitleIndex).map((index) => index.get(parsed.sessionId)).find(Boolean) || null
842
+ : null;
843
+ return finalizeRecord({
844
+ version: SIDECAR_VERSION,
845
+ session_hash: sessionHash("codex", parsed.sessionId || primaryFilePath),
846
+ session_id: parsed.sessionId || null,
847
+ // Local-only lineage. Codex v2 normally writes forked_from_id; keep
848
+ // parent_thread_id as a compatibility fallback, but reject disagreement.
849
+ parent_session_id: parsed.forkedFromId || parsed.parentThreadId || null,
850
+ parent_link_conflict: Boolean(
851
+ parsed.forkedFromId
852
+ && parsed.parentThreadId
853
+ && parsed.forkedFromId !== parsed.parentThreadId
854
+ ),
855
+ forked_from_id: parsed.forkedFromId || null,
856
+ thread_source: typeof parsed.threadSource === "string" ? parsed.threadSource : null,
857
+ agent_nickname: typeof parsed.agentNickname === "string" ? parsed.agentNickname : null,
858
+ agent_role: typeof parsed.agentRole === "string" ? parsed.agentRole : null,
859
+ // Local-only: stripped in summarizeSessions before any cloud/CSV export.
860
+ title,
861
+ source: "codex",
862
+ ...sessionStorageUsage(filePaths),
863
+ project_key: projectKey(parsed.cwd, primaryFilePath),
864
+ project_ref: parsed.cwd || null,
865
+ model,
866
+ model_usage: modelUsage,
867
+ usage_buckets: [...usageBuckets.values()],
868
+ performance: performance.performance,
869
+ ...signals.bounds,
870
+ turns: signals.turns || finite(parsed.turnCount),
871
+ edit_turns: signals.editTurns,
872
+ retry_turns: signals.retryTurns,
873
+ subagent_calls: signals.subagentCalls,
874
+ subagent_types: signals.subagentTypes,
875
+ tokens: parsed.totals || emptyTotals(),
876
+ provenance: { source: "local-session-log", confidence: "observed", retry_confidence: "inferred", content_retained: false },
877
+ });
878
+ }
879
+
880
+ // Grok Build sessions live at:
881
+ // ~/.grok/sessions/<url-encoded-cwd>/<session-uuid>/updates.jsonl
882
+ // with sibling summary.json (id/cwd/title) and signals.json (aggregate
883
+ // counters). Billable tokens come only from turn_completed.usage — the same
884
+ // authority as the Grok usage parser — not from context-window totalTokens.
885
+ function resolveGrokHome(home = os.homedir(), env = process.env) {
886
+ if (typeof env.TOKENUSAGE_GROK_HOME === "string" && env.TOKENUSAGE_GROK_HOME.trim()) {
887
+ return path.resolve(env.TOKENUSAGE_GROK_HOME.trim());
888
+ }
889
+ if (typeof env.GROK_HOME === "string" && env.GROK_HOME.trim()) {
890
+ return path.resolve(env.GROK_HOME.trim());
891
+ }
892
+ return path.join(home, ".grok");
893
+ }
894
+
895
+ function grokSummaryPathFor(updatesPath) {
896
+ return path.join(path.dirname(updatesPath), "summary.json");
897
+ }
898
+
899
+ function grokSignalsPathFor(updatesPath) {
900
+ return path.join(path.dirname(updatesPath), "signals.json");
901
+ }
902
+
903
+ function readJsonFileSync(filePath) {
904
+ try {
905
+ return JSON.parse(fs.readFileSync(filePath, "utf8"));
906
+ } catch {
907
+ return null;
908
+ }
909
+ }
910
+
911
+ function grokTimestampIso(obj) {
912
+ const metaMs = Number(obj?.params?._meta?.agentTimestampMs);
913
+ if (Number.isFinite(metaMs) && metaMs > 0) return new Date(metaMs).toISOString();
914
+ const top = Number(obj?.timestamp);
915
+ if (!Number.isFinite(top) || top <= 0) return null;
916
+ // Grok writes unix seconds on the envelope; ms values are already > 1e12.
917
+ const ms = top > 1e12 ? top : top * 1000;
918
+ return new Date(ms).toISOString();
919
+ }
920
+
921
+ function pickGrokModel(usage, fallback) {
922
+ const modelUsage = usage?.modelUsage;
923
+ if (modelUsage && typeof modelUsage === "object") {
924
+ let bestName = null;
925
+ let bestTokens = -1;
926
+ for (const [name, entry] of Object.entries(modelUsage)) {
927
+ const normalized = normalizeSessionModel(name);
928
+ if (!normalized) continue;
929
+ const tokens = finite(entry?.totalTokens ?? entry?.total_tokens)
930
+ + finite(entry?.inputTokens ?? entry?.input_tokens)
931
+ + finite(entry?.outputTokens ?? entry?.output_tokens);
932
+ if (tokens >= bestTokens) {
933
+ bestTokens = tokens;
934
+ bestName = normalized;
935
+ }
936
+ }
937
+ if (bestName) return bestName;
938
+ }
939
+ return normalizeSessionModel(fallback) || "unknown";
940
+ }
941
+
942
+ function extractGrokUserPrompt(update) {
943
+ if (!update || update.sessionUpdate !== "user_message_chunk") return null;
944
+ const content = update.content;
945
+ if (typeof content === "string") {
946
+ const text = content.trim();
947
+ return text || null;
948
+ }
949
+ if (content && typeof content === "object") {
950
+ if (typeof content.text === "string") {
951
+ const text = content.text.trim();
952
+ return text || null;
953
+ }
954
+ }
955
+ return null;
956
+ }
957
+
958
+ function extractGrokToolName(update) {
959
+ if (!update || update.sessionUpdate !== "tool_call") return "";
960
+ const metaName = update._meta?.["x.ai/tool"]?.name;
961
+ return canonicalToolName(metaName || update.title || "");
962
+ }
963
+
964
+ async function listGrokSessionFiles(sessionsRoot) {
965
+ if (!fs.existsSync(sessionsRoot)) return [];
966
+ const found = [];
967
+ async function walk(dir, depth) {
968
+ if (depth > 6) return;
969
+ let entries;
970
+ try {
971
+ entries = await fsp.readdir(dir, { withFileTypes: true });
972
+ } catch {
973
+ return;
974
+ }
975
+ for (const entry of entries) {
976
+ if (!entry.isDirectory()) continue;
977
+ if (entry.name.startsWith(".")) continue;
978
+ const full = path.join(dir, entry.name);
979
+ const updatesPath = path.join(full, "updates.jsonl");
980
+ try {
981
+ const stat = await fsp.stat(updatesPath);
982
+ if (stat.isFile() && stat.size > 0) {
983
+ found.push(updatesPath);
984
+ continue;
985
+ }
986
+ } catch { /* not a session leaf */ }
987
+ await walk(full, depth + 1);
988
+ }
989
+ }
990
+ await walk(sessionsRoot, 0);
991
+ // Deterministic order so filesSignature is stable across readdir() shuffles.
992
+ found.sort((a, b) => a.localeCompare(b));
993
+ return found;
994
+ }
995
+
996
+ async function scanGrokSession(filePath) {
997
+ const summary = readJsonFileSync(grokSummaryPathFor(filePath)) || {};
998
+ const signals = readJsonFileSync(grokSignalsPathFor(filePath)) || {};
999
+ const tokens = emptyTotals();
1000
+ const bounds = emptyBounds();
1001
+ const dirName = path.basename(path.dirname(filePath));
1002
+ let observedSessionId = typeof summary?.info?.id === "string" && summary.info.id
1003
+ ? summary.info.id
1004
+ : (/^[0-9a-f]{8}-[0-9a-f-]{27,}$/i.test(dirName) ? dirName : null);
1005
+ let cwd = typeof summary?.info?.cwd === "string" && summary.info.cwd
1006
+ ? summary.info.cwd
1007
+ : null;
1008
+ // Prefer agent-authored generated_title over free-form session_summary when
1009
+ // both exist; both are Grok metadata, never the raw user prompt body.
1010
+ const title = cleanSessionTitle(summary.generated_title)
1011
+ || cleanSessionTitle(summary.session_summary)
1012
+ || null;
1013
+ let model = pickGrokModel(null, signals.primaryModelId || summary.current_model_id);
1014
+ let turns = 0;
1015
+ let editTurns = 0;
1016
+ let retryTurns = 0;
1017
+ let currentHadEdit = false;
1018
+ let subagentCalls = 0;
1019
+ const subagentTypes = new Map();
1020
+ let usageEvents = 0;
1021
+ let providerCostEvents = 0;
1022
+ let providerCostUsd = 0;
1023
+ let modelCalls = 0;
1024
+ let apiDurationMs = 0;
1025
+ let usageIsIncomplete = false;
1026
+ let costIsPartial = false;
1027
+ let lastPromptFingerprint = null;
1028
+ // Grok streams user_message_chunk pieces for one prompt. Accumulate until
1029
+ // turn_completed, then fingerprint the full prompt for retry detection.
1030
+ let openUserTurn = false;
1031
+ let userChunkBuffer = "";
1032
+
1033
+ function closeTurn() {
1034
+ if (currentHadEdit) editTurns += 1;
1035
+ currentHadEdit = false;
1036
+ if (userChunkBuffer) {
1037
+ const fingerprint = promptFingerprint(userChunkBuffer);
1038
+ if (lastPromptFingerprint && fingerprint === lastPromptFingerprint) retryTurns += 1;
1039
+ lastPromptFingerprint = fingerprint;
1040
+ }
1041
+ openUserTurn = false;
1042
+ userChunkBuffer = "";
1043
+ }
1044
+
1045
+ const input = fs.createReadStream(filePath, { encoding: "utf8" });
1046
+ const lines = readline.createInterface({ input, crlfDelay: Infinity });
1047
+ for await (const line of lines) {
1048
+ let obj;
1049
+ try { obj = JSON.parse(line); } catch { continue; }
1050
+ updateBounds(bounds, grokTimestampIso(obj));
1051
+ const params = obj.params && typeof obj.params === "object" ? obj.params : {};
1052
+ if (typeof params.sessionId === "string" && params.sessionId) {
1053
+ observedSessionId = params.sessionId;
1054
+ }
1055
+ const update = params.update && typeof params.update === "object" ? params.update : null;
1056
+ if (!update) continue;
1057
+ const sessionUpdate = update.sessionUpdate;
1058
+
1059
+ if (sessionUpdate === "user_message_chunk") {
1060
+ const piece = extractGrokUserPrompt(update);
1061
+ if (!piece) continue;
1062
+ // First non-empty chunk after a closed turn opens a new user turn;
1063
+ // later chunks only extend the fingerprint buffer.
1064
+ if (!openUserTurn) {
1065
+ turns += 1;
1066
+ openUserTurn = true;
1067
+ userChunkBuffer = piece;
1068
+ } else {
1069
+ userChunkBuffer += piece;
1070
+ }
1071
+ continue;
1072
+ }
1073
+
1074
+ if (sessionUpdate === "tool_call") {
1075
+ // Tools belong to the current user turn. After turn_completed closes a
1076
+ // turn, a tool-only follow-up must open a new anonymous turn — otherwise
1077
+ // edit_turns can exceed turns.
1078
+ if (!openUserTurn) {
1079
+ turns += 1;
1080
+ openUserTurn = true;
1081
+ }
1082
+ const name = extractGrokToolName(update);
1083
+ if (EDIT_TOOLS.has(name)) currentHadEdit = true;
1084
+ if (GROK_SUBAGENT_TOOLS.has(name)) {
1085
+ subagentCalls += 1;
1086
+ const display = name === "spawn_agent" ? "spawn_subagent" : name;
1087
+ subagentTypes.set(display, (subagentTypes.get(display) || 0) + 1);
1088
+ }
1089
+ continue;
1090
+ }
1091
+
1092
+ if (sessionUpdate === "turn_completed") {
1093
+ closeTurn();
1094
+ const usage = update.usage;
1095
+ const normalizedUsage = normalizeGrokUsage(usage);
1096
+ if (normalizedUsage) {
1097
+ usageEvents += 1;
1098
+ addTotals(tokens, normalizedUsage);
1099
+ modelCalls += finite(normalizedUsage.model_calls);
1100
+ apiDurationMs += finite(normalizedUsage.api_duration_ms);
1101
+ usageIsIncomplete ||= normalizedUsage.usage_is_incomplete;
1102
+ costIsPartial ||= normalizedUsage.cost_is_partial;
1103
+ if (normalizedUsage.total_cost_usd != null) {
1104
+ providerCostEvents += 1;
1105
+ providerCostUsd = Math.round(
1106
+ (providerCostUsd + normalizedUsage.total_cost_usd) * USD_TICKS_PER_USD,
1107
+ ) / USD_TICKS_PER_USD;
1108
+ }
1109
+ }
1110
+ const candidate = pickGrokModel(usage, model);
1111
+ if (candidate && candidate !== "unknown") model = candidate;
1112
+ continue;
1113
+ }
1114
+ }
1115
+ closeTurn();
1116
+
1117
+ // Prefer observed turn_completed totals. Never invent billable totals from
1118
+ // signals.contextTokensUsed (context-window occupancy is not API usage);
1119
+ // leave zeros so listSessionsForBrowser filters empty sessions out.
1120
+ if (turns === 0 && finite(signals.turnCount) > 0) {
1121
+ turns = finite(signals.turnCount);
1122
+ }
1123
+ if (!Number.isFinite(Date.parse(bounds.started_at || "")) && summary.created_at) {
1124
+ updateBounds(bounds, summary.created_at);
1125
+ }
1126
+ if (!Number.isFinite(Date.parse(bounds.ended_at || "")) && (summary.last_active_at || summary.updated_at)) {
1127
+ updateBounds(bounds, summary.last_active_at || summary.updated_at);
1128
+ }
1129
+ if ((!model || model === "unknown") && signals.primaryModelId) {
1130
+ model = normalizeSessionModel(signals.primaryModelId) || model;
1131
+ }
1132
+
1133
+ const hasCompleteProviderCost = usageEvents > 0
1134
+ && providerCostEvents === usageEvents
1135
+ && !usageIsIncomplete
1136
+ && !costIsPartial;
1137
+
1138
+ return finalizeRecord({
1139
+ version: SIDECAR_VERSION,
1140
+ session_hash: sessionHash("grok", observedSessionId || filePath),
1141
+ session_id: observedSessionId || null,
1142
+ // Local-only: stripped in summarizeSessions before any cloud/CSV export.
1143
+ title,
1144
+ source: "grok",
1145
+ ...sessionStorageUsage([filePath, grokSummaryPathFor(filePath), grokSignalsPathFor(filePath)]),
1146
+ project_key: projectKey(cwd, filePath),
1147
+ project_ref: cwd || null,
1148
+ model: model || "unknown",
1149
+ ...bounds,
1150
+ turns,
1151
+ edit_turns: editTurns,
1152
+ retry_turns: retryTurns,
1153
+ subagent_calls: subagentCalls,
1154
+ subagent_types: Object.fromEntries([...subagentTypes.entries()].sort()),
1155
+ tokens,
1156
+ usage_events: usageEvents,
1157
+ usage_precision: usageIsIncomplete ? "reported_incomplete" : (usageEvents > 0 ? "reported" : "unavailable"),
1158
+ usage_is_incomplete: usageIsIncomplete,
1159
+ cost_is_partial: costIsPartial,
1160
+ cost_source: hasCompleteProviderCost ? "provider_reported" : "model_pricing",
1161
+ provider_cost_usd: hasCompleteProviderCost ? providerCostUsd : null,
1162
+ model_calls: modelCalls,
1163
+ api_duration_ms: apiDurationMs,
1164
+ context_tokens_used: finite(signals.contextTokensUsed),
1165
+ context_window_tokens: finite(signals.contextWindowTokens),
1166
+ context_usage_percent: finite(signals.contextWindowUsage),
1167
+ tool_calls: finite(signals.toolCallCount),
1168
+ tool_failures: finite(signals.toolFailureCount),
1169
+ error_count: finite(signals.errorCount),
1170
+ compaction_count: finite(signals.compactionCount),
1171
+ provenance: {
1172
+ source: "local-session-log",
1173
+ confidence: usageIsIncomplete ? "partial" : "observed",
1174
+ retry_confidence: "inferred",
1175
+ content_retained: false,
1176
+ usage: usageEvents > 0 ? "turn_completed.usage" : "unavailable",
1177
+ cost: hasCompleteProviderCost ? "provider_reported" : "model_pricing",
1178
+ },
1179
+ });
1180
+ }
1181
+
1182
+ // Project and title metadata stay local. SQL projects only numeric usage and
1183
+ // identity fields; user/assistant bodies and tool arguments never enter JS.
1184
+ async function readOpencodeSessionInputs(dbPath) {
1185
+ const options = { label: "OpenCode", timeout: 30_000, maxBuffer: 50 * 1024 * 1024, readOnly: true, throwOnReadFailure: true };
1186
+ const query = (sql) => readSqliteJsonRowsAsync(dbPath, sql, options);
1187
+ const tables = new Set((await query("SELECT name FROM sqlite_master WHERE name IN ('session','session_v2','message','session_message')")).map((row) => row.name));
1188
+ const sessionRows = [];
1189
+ for (const table of ["session_v2", "session"]) {
1190
+ if (!tables.has(table)) continue;
1191
+ const columns = new Set((await query(`SELECT name FROM pragma_table_info('${table}')`)).map((row) => row.name));
1192
+ if (!columns.has("id")) continue;
1193
+ const selected = ["id", "parent_id", "directory", "title", "time_created", "time_updated"].filter((column) => columns.has(column));
1194
+ sessionRows.push(...await query(`SELECT ${selected.join(", ")} FROM ${table} ORDER BY id ASC`));
1195
+ }
1196
+ const messages = [];
1197
+ for (const table of ["message", "session_message"]) {
1198
+ if (!tables.has(table)) continue;
1199
+ const role = table === "session_message" ? "type" : "json_extract(data, '$.role')";
1200
+ messages.push(...await query(`SELECT id, session_id, time_created, time_updated, ${role} AS role,
1201
+ CASE WHEN ${role} = 'assistant' THEN json_object(
1202
+ 'tokens', json_extract(data, '$.tokens'),
1203
+ 'modelID', json_extract(data, '$.modelID'),
1204
+ 'providerID', json_extract(data, '$.providerID'),
1205
+ 'model', json_extract(data, '$.model'),
1206
+ 'time', json_extract(data, '$.time'),
1207
+ 'path', json_object('cwd', json_extract(data, '$.path.cwd'))
1208
+ ) END AS metadata
1209
+ FROM ${table} WHERE ${role} IN ('user', 'assistant') ORDER BY time_created ASC, id ASC`));
1210
+ }
1211
+ return { sessionRows, messages };
1212
+ }
1213
+
1214
+ async function scanOpencodeSessions(dbPaths) {
1215
+ const paths = [...new Set((Array.isArray(dbPaths) ? dbPaths : [dbPaths]).filter(Boolean))];
1216
+ const snapshots = [];
1217
+ const inputs = [];
1218
+ try {
1219
+ for (const dbPath of paths) {
1220
+ let effectivePath = dbPath;
1221
+ if (wsl.isUncPath(dbPath)) {
1222
+ try {
1223
+ const snapshot = wsl.snapshotSqliteDb(dbPath);
1224
+ snapshots.push(snapshot);
1225
+ effectivePath = snapshot.path;
1226
+ } catch { /* Direct read determines whether this mount supports SQLite. */ }
1227
+ }
1228
+ inputs.push(await readOpencodeSessionInputs(effectivePath));
1229
+ }
1230
+ const sessionRows = new Map();
1231
+ const messages = new Map();
1232
+ for (const input of inputs) {
1233
+ for (const row of input.sessionRows) if (!sessionRows.has(row.id)) sessionRows.set(row.id, row);
1234
+ for (const row of input.messages) {
1235
+ const key = `${row.session_id}\0${row.id}`;
1236
+ const previous = messages.get(key);
1237
+ if (!previous || Number(row.time_updated) >= Number(previous.time_updated)) messages.set(key, row);
1238
+ }
1239
+ }
1240
+ const groups = new Map();
1241
+ const ancestors = new Map();
1242
+ const ancestorsOf = (id) => {
1243
+ if (ancestors.has(id)) return ancestors.get(id);
1244
+ const known = [];
1245
+ const seen = new Set([id]);
1246
+ let current = sessionRows.get(id);
1247
+ while (current?.parent_id && sessionRows.has(current.parent_id)) {
1248
+ if (seen.has(current.parent_id)) {
1249
+ ancestors.set(id, []);
1250
+ return [];
1251
+ }
1252
+ seen.add(current.parent_id);
1253
+ known.push(current.parent_id);
1254
+ current = sessionRows.get(current.parent_id);
1255
+ }
1256
+ ancestors.set(id, known);
1257
+ return known;
1258
+ };
1259
+ const sortedMessages = [...messages.values()]
1260
+ .sort((a, b) => Number(a.time_created) - Number(b.time_created))
1261
+ .map((row) => {
1262
+ const data = row.metadata ? JSON.parse(row.metadata) : {};
1263
+ const delta = normalizeOpencodeTokens(data.tokens);
1264
+ const fingerprint = delta && deriveOpencodeMessageFingerprint({ msg: data, totals: delta, source: "opencode" });
1265
+ return { row, data, delta, fingerprint };
1266
+ });
1267
+ // A fork may sort before its original when message creation times tie.
1268
+ // Select a known ancestor before aggregating; unknown/cyclic lineage keeps
1269
+ // the existing first-observed owner and never invents a parent connection.
1270
+ const owners = new Map();
1271
+ for (const { row, fingerprint } of sortedMessages) {
1272
+ if (!fingerprint) continue;
1273
+ const owner = owners.get(fingerprint);
1274
+ if (!owner || ancestorsOf(owner).includes(row.session_id)) owners.set(fingerprint, row.session_id);
1275
+ }
1276
+ for (const { row, data, delta, fingerprint } of sortedMessages) {
1277
+ const sessionId = String(row.session_id || "").trim();
1278
+ if (!sessionId) continue;
1279
+ let group = groups.get(sessionId);
1280
+ if (!group) {
1281
+ group = { bounds: emptyBounds(), tokens: emptyTotals(), models: new Map(), buckets: new Map(), spans: [], turns: 0, calls: 0, cwd: null };
1282
+ groups.set(sessionId, group);
1283
+ }
1284
+ if (delta && delta.total_tokens > 0) {
1285
+ const owner = fingerprint && owners.get(fingerprint);
1286
+ if (owner && owner !== sessionId) continue;
1287
+ const model = normalizeSessionModel(normalizeOpencodeModelFields(data).modelId) || "unknown";
1288
+ addTotals(group.tokens, delta);
1289
+ const usage = group.models.get(model) || { model, ...emptyTotals(), usage_events: 0 };
1290
+ addTotals(usage, delta);
1291
+ usage.usage_events += 1;
1292
+ group.models.set(model, usage);
1293
+ group.calls += 1;
1294
+ const timestampMs = coerceEpochMs(data.time?.completed) || coerceEpochMs(data.time?.created) || coerceEpochMs(row.time_created);
1295
+ if (timestampMs) {
1296
+ const timestamp = new Date(Math.floor(timestampMs / 60_000) * 60_000).toISOString();
1297
+ const key = `${timestamp}\0${model}`;
1298
+ const bucket = group.buckets.get(key) || { timestamp, model, ...emptyTotals(), usage_events: 0 };
1299
+ addTotals(bucket, delta);
1300
+ bucket.usage_events += 1;
1301
+ group.buckets.set(key, bucket);
1302
+ }
1303
+ if (!group.cwd && typeof data.path?.cwd === "string") group.cwd = data.path.cwd.trim() || null;
1304
+ }
1305
+ if (row.role === "user") group.turns += 1;
1306
+ const start = coerceEpochMs(data.time?.created) || coerceEpochMs(row.time_created);
1307
+ // DB time_updated can reflect a migration months after the request.
1308
+ // User records are instants; only an explicit assistant completion proves
1309
+ // execution time. Incomplete requests contribute their start point alone.
1310
+ const completed = row.role === "assistant" ? coerceEpochMs(data.time?.completed) : 0;
1311
+ const end = completed >= start ? completed : start;
1312
+ if (start) updateBounds(group.bounds, new Date(start).toISOString());
1313
+ if (end) updateBounds(group.bounds, new Date(end).toISOString());
1314
+ if (start && end >= start) group.spans.push([start, end]);
1315
+ }
1316
+ const records = [];
1317
+ for (const [sessionId, group] of groups) {
1318
+ const row = sessionRows.get(sessionId) || {};
1319
+ const cwd = typeof row.directory === "string" && row.directory.trim() ? row.directory.trim() : group.cwd;
1320
+ const modelUsage = [...group.models.values()];
1321
+ let activeMs = 0;
1322
+ let interval = null;
1323
+ for (const span of group.spans.sort((a, b) => a[0] - b[0])) {
1324
+ if (!interval) interval = [...span];
1325
+ else if (span[0] <= interval[1] + IDLE_GAP_MS) interval[1] = Math.max(interval[1], span[1]);
1326
+ else { activeMs += interval[1] - interval[0]; interval = [...span]; }
1327
+ }
1328
+ if (interval) activeMs += interval[1] - interval[0];
1329
+ records.push(finalizeRecord({
1330
+ version: SIDECAR_VERSION,
1331
+ session_hash: sessionHash("opencode", sessionId), session_id: sessionId,
1332
+ parent_session_id: typeof row.parent_id === "string" && row.parent_id.trim() ? row.parent_id.trim() : null,
1333
+ title: cleanSessionTitle(row.title), source: "opencode",
1334
+ project_key: projectKey(cwd && cwd.replace(/\\/g, "/"), paths[0]), project_ref: cwd || null,
1335
+ model: modelUsage.length > 1 ? "mixed" : (modelUsage[0]?.model || "unknown"),
1336
+ model_usage: modelUsage, usage_buckets: [...group.buckets.values()],
1337
+ ...group.bounds, active_ms: activeMs, tokens: group.tokens,
1338
+ turns: group.turns, edit_turns: 0, retry_turns: 0,
1339
+ usage_events: group.calls, model_calls: group.calls,
1340
+ usage_precision: group.calls ? "reported" : "unavailable", cost_source: "model_pricing",
1341
+ provenance: { source: "local-session-log", confidence: "observed", retry_confidence: "unavailable", content_retained: false, usage: "opencode-db-metadata" },
1342
+ }));
1343
+ }
1344
+ return records;
1345
+ } finally {
1346
+ for (const snapshot of snapshots) snapshot.cleanup();
1347
+ }
1348
+ }
1349
+
1350
+ // ZCode (Z.ai's CLI, an OpenCode fork) keeps everything in one SQLite DB at
1351
+ // ~/.zcode/cli/db/db.sqlite: a `session` table (id/parent_id/directory/title),
1352
+ // a `model_usage` table (per-request counters) and OpenCode's legacy `message`
1353
+ // table (assistant messages with inclusive token snapshots). Billable tokens
1354
+ // come from readZcodeDbMessages() — the exact same reader, inclusive→disjoint
1355
+ // normalization and sub-agent provider blocklist the usage sync uses — so the
1356
+ // session browser and the usage card can never drift apart. The per-request
1357
+ // signal columns live only in model_usage, so they are read separately and
1358
+ // feed performance/counter estimates only, never token totals.
1359
+ function zcodeTableColumns(dbPath, table) {
1360
+ // throwOnReadFailure: a missing table answers pragma_table_info with an
1361
+ // empty row set (no error), so the only way to land in the reader's failure
1362
+ // path is a genuinely unreadable db — which must propagate, never read as
1363
+ // "no table" (see the throw in scanZcodeSessions below).
1364
+ const rows = readSqliteJsonRows(dbPath, `SELECT name FROM pragma_table_info('${table}')`, {
1365
+ label: "ZCode",
1366
+ timeout: 10_000,
1367
+ maxBuffer: 1024 * 1024,
1368
+ throwOnReadFailure: true,
1369
+ });
1370
+ return new Set((Array.isArray(rows) ? rows : []).map((row) => String(row?.name || "")));
1371
+ }
1372
+
1373
+ // Messages from readZcodeDbMessages already carry disjoint opencode-shaped
1374
+ // tokens ({ input, output, reasoning, cache.read, cache.write }); map them
1375
+ // onto the session pipeline's column names. tokenTotals() recomputes the sum.
1376
+ function zcodeMessageTotals(data) {
1377
+ const tokens = data?.tokens || {};
1378
+ const totals = tokenTotals({
1379
+ input_tokens: tokens.input,
1380
+ cached_input_tokens: tokens.cache?.read,
1381
+ cache_creation_input_tokens: tokens.cache?.write,
1382
+ output_tokens: tokens.output,
1383
+ reasoning_output_tokens: tokens.reasoning,
1384
+ });
1385
+ // The usage queue's total is input + output + cache_creation + cache_read +
1386
+ // reasoning_output (rollout.js addTotals); tokenTotals' generic total omits
1387
+ // reasoning. ZCode splits reasoning out of output, so fold it back in here or
1388
+ // the session browser undercounts every thinking request against the card.
1389
+ totals.total_tokens += totals.reasoning_output_tokens;
1390
+ return totals;
1391
+ }
1392
+
1393
+ const ZCODE_SIGNAL_REQUIRED_COLUMNS = [
1394
+ "session_id", "model_id", "provider_id", "status", "started_at", "id",
1395
+ "output_tokens", "duration_ms", "time_to_first_token_ms", "query_source",
1396
+ ];
1397
+
1398
+ // One db yields many session rows, so unlike the per-file scanners this scan
1399
+ // returns an array (the entries loop in buildSessionAnalyticsInternal handles
1400
+ // both shapes). Errors on the db as a whole propagate: the caller counts the
1401
+ // file as skipped instead of caching an empty inventory as "no sessions".
1402
+ //
1403
+ // WSL dbs arrive as UNC paths (\\wsl$\…), and SQLite over the Plan 9 bridge
1404
+ // cannot take the locks even a read needs ("database is locked"). The usage
1405
+ // readers snapshot such paths query-by-query; the scan runs several queries
1406
+ // plus readZcodeDbMessages against one db, so snapshot once here and run the
1407
+ // whole scan (metadata, signals, turns, tools, messages) against the local
1408
+ // copy — otherwise the metadata query succeeds while the message read fails
1409
+ // on the same database.
1410
+ async function scanZcodeSessions(dbPaths) {
1411
+ const paths = [...new Set((Array.isArray(dbPaths) ? dbPaths : [dbPaths]).filter(Boolean))];
1412
+ const snapshots = [];
1413
+ const inputs = [];
1414
+ try {
1415
+ for (const dbPath of paths) {
1416
+ let effectiveDbPath = dbPath;
1417
+ if (wsl.isUncPath(dbPath)) {
1418
+ try {
1419
+ const snapshot = wsl.snapshotSqliteDb(dbPath);
1420
+ snapshots.push(snapshot);
1421
+ effectiveDbPath = snapshot.path;
1422
+ } catch (_error) { /* Direct read decides whether this UNC server supports SQLite. */ }
1423
+ }
1424
+ inputs.push(readZcodeSessionInputs(effectiveDbPath));
1425
+ }
1426
+ return buildZcodeSessionRecords(inputs, paths[0]);
1427
+ } finally {
1428
+ for (const snapshot of snapshots) snapshot.cleanup();
1429
+ }
1430
+ }
1431
+
1432
+ /** Read metadata and numeric events from one database; real read failures propagate. */
1433
+ function readZcodeSessionInputs(dbPath) {
1434
+ const options = { label: "ZCode", timeout: 30_000, maxBuffer: 50 * 1024 * 1024, readOnly: true, throwOnReadFailure: true };
1435
+ const sessionColumns = zcodeTableColumns(dbPath, "session");
1436
+ if (!sessionColumns.has("id")) return { sessionRows: [], messages: [], requestRows: [], turnRows: [], toolRows: [] };
1437
+ const optionalColumns = ["parent_id", "directory", "title", "time_created", "time_updated"];
1438
+ const selectColumns = ["id", ...optionalColumns.filter((name) => sessionColumns.has(name))];
1439
+ const orderBy = sessionColumns.has("time_created") ? " ORDER BY time_created ASC, id ASC" : " ORDER BY id ASC";
1440
+ const sessionRows = readSqliteJsonRows(
1441
+ dbPath,
1442
+ `SELECT ${selectColumns.join(", ")} FROM session${orderBy}`,
1443
+ options,
1444
+ );
1445
+ const messages = readZcodeDbMessages(dbPath, { readOnly: true }, { propagateReadFailure: true });
1446
+ const modelUsageColumns = zcodeTableColumns(dbPath, "model_usage");
1447
+ const requestRows = ZCODE_SIGNAL_REQUIRED_COLUMNS.every((name) => modelUsageColumns.has(name))
1448
+ ? readSqliteJsonRows(dbPath, `SELECT id, session_id, model_id, status, started_at, output_tokens, duration_ms, time_to_first_token_ms, query_source
1449
+ FROM model_usage
1450
+ WHERE status IN ('completed', 'error')
1451
+ AND trim(provider_id) != ''
1452
+ AND provider_id NOT LIKE '%anthropic%'
1453
+ AND provider_id NOT LIKE '%openai%'
1454
+ AND provider_id NOT LIKE '%google%'
1455
+ ORDER BY started_at ASC, id ASC`, options)
1456
+ : [];
1457
+ const turnColumns = zcodeTableColumns(dbPath, "turn_usage");
1458
+ const turnRows = turnColumns.has("session_id")
1459
+ ? readSqliteJsonRows(dbPath, `SELECT session_id${turnColumns.has("turn_id") ? ", turn_id" : ""} FROM turn_usage`, options)
1460
+ : [];
1461
+ const toolColumns = zcodeTableColumns(dbPath, "tool_usage");
1462
+ const toolRows = ["session_id", "tool_name", "turn_id"].every((name) => toolColumns.has(name))
1463
+ ? readSqliteJsonRows(dbPath, "SELECT session_id, turn_id, tool_name FROM tool_usage", options)
1464
+ : [];
1465
+ return { sessionRows, messages, requestRows, turnRows, toolRows };
1466
+ }
1467
+
1468
+ /** Merge only shared event identities, retaining both installs' distinct tails. */
1469
+ function uniqueZcodeRows(rows, keyFor) {
1470
+ const seen = new Set();
1471
+ return rows.filter((row) => {
1472
+ const key = keyFor(row);
1473
+ if (!key) return true;
1474
+ if (seen.has(key)) return false;
1475
+ seen.add(key);
1476
+ return true;
1477
+ });
1478
+ }
1479
+
1480
+ function buildZcodeSessionRecords(inputs, displayPath) {
1481
+ const collect = (key) => inputs.flatMap((input) => input[key] || []);
1482
+ const eventKey = (row, sessionKey, idKey) => row?.[sessionKey] && row?.[idKey]
1483
+ ? `${row[sessionKey]}\u0000${row[idKey]}` : null;
1484
+ const sessionRows = uniqueZcodeRows(collect("sessionRows"), (row) => row?.id);
1485
+ const fingerprintOwners = new Map();
1486
+ const forkCopies = new Set();
1487
+ const messages = uniqueZcodeRows(collect("messages"), (row) => eventKey(row, "sessionID", "id"))
1488
+ .filter((message) => {
1489
+ // Use the ledger's existing narrow fork-copy contract, including both
1490
+ // timestamps, all token columns, model and provider. Never dedup two
1491
+ // separate turns within one session by counters alone.
1492
+ const fingerprint = deriveOpencodeMessageFingerprint({
1493
+ msg: message.data, totals: zcodeMessageTotals(message.data), source: "zcode",
1494
+ });
1495
+ const owner = fingerprint && fingerprintOwners.get(fingerprint);
1496
+ if (owner && owner !== message.sessionID) {
1497
+ forkCopies.add(eventKey(message, "sessionID", "id"));
1498
+ return false;
1499
+ }
1500
+ if (fingerprint) fingerprintOwners.set(fingerprint, message.sessionID);
1501
+ return true;
1502
+ });
1503
+ const requestRows = uniqueZcodeRows(collect("requestRows"), (row) => eventKey(row, "session_id", "id"))
1504
+ .filter((row) => !forkCopies.has(eventKey(row, "session_id", "id")));
1505
+ const turnRows = uniqueZcodeRows(collect("turnRows"), (row) => eventKey(row, "session_id", "turn_id"));
1506
+ const toolRows = collect("toolRows");
1507
+
1508
+ const messagesBySession = new Map();
1509
+ // propagateReadFailure: a failed native-usage query must abort the scan (the
1510
+ // caller counts the db as skipped) rather than silently degrade to the
1511
+ // legacy tables and cache a zero-token inventory for those sessions.
1512
+ for (const message of messages) {
1513
+ const sessionId = String(message?.sessionID || "").trim();
1514
+ if (!sessionId) continue;
1515
+ let group = messagesBySession.get(sessionId);
1516
+ if (!group) {
1517
+ group = [];
1518
+ messagesBySession.set(sessionId, group);
1519
+ }
1520
+ group.push(message);
1521
+ }
1522
+
1523
+ // Request-level signals (never token totals). Only completed requests feed
1524
+ // duration-based estimates; error rows count toward error_count alone. The
1525
+ // provider filter mirrors isZcodeNativeMessage's blocklist (see rollout.js):
1526
+ // rows ZCode orchestrated through claude/codex/gemini sub-agents already
1527
+ // appear as their own provider's sessions and must not skew signals either.
1528
+ const signalsBySession = new Map();
1529
+ for (const row of requestRows) {
1530
+ const sessionId = String(row?.session_id || "").trim();
1531
+ if (!sessionId) continue;
1532
+ let signals = signalsBySession.get(sessionId);
1533
+ if (!signals) {
1534
+ signals = {
1535
+ collector: createZcodePerformanceCollector(),
1536
+ apiDurationMs: 0,
1537
+ compactionCount: 0,
1538
+ errorCount: 0,
1539
+ // Request wall-clock extremes from model_usage. Messages only carry
1540
+ // startedAt (the reader maps it to timeUpdated), so without these the
1541
+ // last generation's duration never reaches ended_at and a session's
1542
+ // final request reports a zero-length span.
1543
+ firstRequestIso: null,
1544
+ lastRequestEndIso: null,
1545
+ // [startMs, endMs] per request for the active-time union below.
1546
+ activeSpans: [],
1547
+ };
1548
+ signalsBySession.set(sessionId, signals);
1549
+ }
1550
+ // Match readZcodeNativeUsageMessages: databases may store epoch seconds
1551
+ // or milliseconds, but request spans and message bounds must share units.
1552
+ const requestStartMs = coerceEpochMs(row?.started_at);
1553
+ if (requestStartMs > 0) {
1554
+ const startIso = new Date(requestStartMs).toISOString();
1555
+ if (!signals.firstRequestIso || startIso < signals.firstRequestIso) signals.firstRequestIso = startIso;
1556
+ // duration_ms only exists on completed rows; an error request still
1557
+ // occupied its start instant, so its end falls back to the start.
1558
+ const durationMs = row.status === "completed" ? finite(row.duration_ms) : 0;
1559
+ const endIso = new Date(requestStartMs + durationMs).toISOString();
1560
+ if (!signals.lastRequestEndIso || endIso > signals.lastRequestEndIso) signals.lastRequestEndIso = endIso;
1561
+ signals.activeSpans.push([requestStartMs, requestStartMs + durationMs]);
1562
+ }
1563
+ if (row.status === "error") {
1564
+ signals.errorCount += 1;
1565
+ continue;
1566
+ }
1567
+ if (row.query_source === "compact") signals.compactionCount += 1;
1568
+ signals.apiDurationMs += finite(row.duration_ms);
1569
+ signals.collector.consumeUsage({
1570
+ model: normalizeSessionModel(row.model_id) || "unknown",
1571
+ outputTokens: finite(row.output_tokens),
1572
+ durationMs: finite(row.duration_ms),
1573
+ timeToFirstTokenMs: typeof row.time_to_first_token_ms === "number" ? row.time_to_first_token_ms : undefined,
1574
+ });
1575
+ }
1576
+ const turnsBySession = new Map();
1577
+ for (const row of turnRows) {
1578
+ const sessionId = String(row?.session_id || "").trim();
1579
+ if (!sessionId) continue;
1580
+ turnsBySession.set(sessionId, (turnsBySession.get(sessionId) || 0) + 1);
1581
+ }
1582
+
1583
+ // ZCode writes Capitalized tool names (Edit/Write); EDIT_TOOLS is lowercase.
1584
+ // An edit turn is a turn that used an edit tool, matching the Grok definition.
1585
+ const editTurnsBySession = new Map();
1586
+ const editTurnIds = new Map();
1587
+ for (const row of toolRows) {
1588
+ if (!EDIT_TOOLS.has(String(row?.tool_name || "").toLowerCase())) continue;
1589
+ const sessionId = String(row?.session_id || "").trim();
1590
+ const turnId = String(row?.turn_id || "").trim();
1591
+ if (!sessionId || !turnId) continue;
1592
+ let turns = editTurnIds.get(sessionId);
1593
+ if (!turns) {
1594
+ turns = new Set();
1595
+ editTurnIds.set(sessionId, turns);
1596
+ }
1597
+ turns.add(turnId);
1598
+ }
1599
+ for (const [sessionId, turns] of editTurnIds) editTurnsBySession.set(sessionId, turns.size);
1600
+
1601
+ const records = [];
1602
+ for (const row of Array.isArray(sessionRows) ? sessionRows : []) {
1603
+ const sessionId = String(row?.id || "").trim();
1604
+ if (!sessionId) continue;
1605
+ const messages = messagesBySession.get(sessionId) || [];
1606
+ const tokens = emptyTotals();
1607
+ const modelUsageByModel = new Map();
1608
+ const bounds = emptyBounds();
1609
+ const usageBuckets = new Map();
1610
+ const messagePoints = [];
1611
+ let messageCwd = null;
1612
+ for (const message of messages) {
1613
+ const data = message?.data || {};
1614
+ // OpenCode v1 messages carry a flat modelID; v2 (session_message era)
1615
+ // nests it as model.id, and some forks wrote model as a plain string.
1616
+ // Resolve every shape through the shared normalizer so by-model
1617
+ // attribution and pricing match the usage sync on v2-layout databases.
1618
+ const model = normalizeSessionModel(normalizeOpencodeModelFields(data).modelId) || "unknown";
1619
+ const delta = zcodeMessageTotals(data);
1620
+ addTotals(tokens, delta);
1621
+ let usage = modelUsageByModel.get(model);
1622
+ if (!usage) {
1623
+ usage = { model, ...emptyTotals(), usage_events: 0 };
1624
+ modelUsageByModel.set(model, usage);
1625
+ }
1626
+ addTotals(usage, delta);
1627
+ usage.usage_events += 1;
1628
+ // Message timestamps are epoch-ms integers; updateBounds() only accepts
1629
+ // ISO strings and silently drops anything else.
1630
+ const timeUpdated = Number(message?.timeUpdated);
1631
+ if (Number.isFinite(timeUpdated) && timeUpdated > 0) {
1632
+ updateBounds(bounds, new Date(timeUpdated).toISOString());
1633
+ messagePoints.push(timeUpdated);
1634
+ // Minute buckets (same shape as the Codex scanner's) feed the from/to
1635
+ // day filter in scopeSessionUsage; without them a multi-day session
1636
+ // bills its whole lifetime to every day it touches.
1637
+ const timestamp = new Date(Math.floor(timeUpdated / 60_000) * 60_000).toISOString();
1638
+ const bucketKey = `${timestamp}\u0000${model}`;
1639
+ const bucket = usageBuckets.get(bucketKey) || { timestamp, model, ...emptyTotals(), usage_events: 0 };
1640
+ addTotals(bucket, delta);
1641
+ bucket.usage_events += 1;
1642
+ usageBuckets.set(bucketKey, bucket);
1643
+ }
1644
+ if (!messageCwd && typeof data.path?.cwd === "string" && data.path.cwd.trim()) {
1645
+ messageCwd = data.path.cwd.trim();
1646
+ }
1647
+ }
1648
+ // Sessions without any message (claude-import migrations the import did
1649
+ // not rebuild, sessions abandoned before the first reply) keep the row's
1650
+ // own wall-clock span; they end up with zero tokens and the browser's
1651
+ // existing total_tokens > 0 filter drops them from the listing.
1652
+ if (messages.length === 0) {
1653
+ const created = Number(row?.time_created);
1654
+ const updated = Number(row?.time_updated);
1655
+ if (Number.isFinite(created) && created > 0) updateBounds(bounds, new Date(created).toISOString());
1656
+ if (Number.isFinite(updated) && updated > 0) updateBounds(bounds, new Date(updated).toISOString());
1657
+ }
1658
+
1659
+ const signals = signalsBySession.get(sessionId) || null;
1660
+ if (signals) {
1661
+ // Widen the wall-clock span with model_usage request extremes: message
1662
+ // timestamps are request starts, so the final request's duration would
1663
+ // otherwise vanish from ended_at (a 10s request reads as a 0-length
1664
+ // span). Direct comparison instead of updateBounds() keeps active_ms
1665
+ // (idle-gap working time) driven by the interval union below.
1666
+ if (signals.firstRequestIso && (!bounds.started_at || signals.firstRequestIso < bounds.started_at)) {
1667
+ bounds.started_at = signals.firstRequestIso;
1668
+ }
1669
+ if (signals.lastRequestEndIso && (!bounds.ended_at || signals.lastRequestEndIso > bounds.ended_at)) {
1670
+ bounds.ended_at = signals.lastRequestEndIso;
1671
+ }
1672
+ }
1673
+ // Active time = the union of request execution intervals plus message
1674
+ // instants, with spans ≤ IDLE_GAP_MS apart bridged. updateBounds' gap
1675
+ // accumulator only measures message-start-to-message-start, which loses
1676
+ // the execution time of every request but the last one (two 10s requests
1677
+ // around a 1h pause must read 20s, not 10s); the union also collapses
1678
+ // parallel requests instead of counting them twice. Legacy-only sessions
1679
+ // contribute points alone, which degenerates to the same idle-gap span
1680
+ // the generic scanners produce.
1681
+ const spans = [...(signals ? signals.activeSpans : []), ...messagePoints.map((ms) => [ms, ms])]
1682
+ .filter(([startMs, endMs]) => Number.isFinite(startMs) && Number.isFinite(endMs))
1683
+ .sort((a, b) => a[0] - b[0]);
1684
+ let unionActiveMs = 0;
1685
+ let unionStart = null;
1686
+ let unionEnd = null;
1687
+ for (const [startMs, endMs] of spans) {
1688
+ if (unionStart === null) {
1689
+ unionStart = startMs;
1690
+ unionEnd = endMs;
1691
+ continue;
1692
+ }
1693
+ if (startMs <= unionEnd + IDLE_GAP_MS) {
1694
+ if (endMs > unionEnd) unionEnd = endMs;
1695
+ continue;
1696
+ }
1697
+ unionActiveMs += unionEnd - unionStart;
1698
+ unionStart = startMs;
1699
+ unionEnd = endMs;
1700
+ }
1701
+ if (unionStart !== null) unionActiveMs += unionEnd - unionStart;
1702
+ bounds.active_ms = unionActiveMs;
1703
+ const finished = signals ? signals.collector.finish() : { performance: normalizePerformance(), byModel: new Map() };
1704
+ const modelUsage = [...modelUsageByModel.values()].map((usage) => ({
1705
+ ...usage,
1706
+ performance: finished.byModel.get(usage.model) || normalizePerformance(),
1707
+ }));
1708
+ const cwd = typeof row?.directory === "string" && row.directory.trim() ? row.directory.trim() : messageCwd;
1709
+ records.push(finalizeRecord({
1710
+ version: SIDECAR_VERSION,
1711
+ session_hash: sessionHash("zcode", sessionId),
1712
+ session_id: sessionId,
1713
+ // Local-only lineage: ZCode's own parent_id (subagent/workflow children).
1714
+ parent_session_id: typeof row?.parent_id === "string" && row.parent_id.trim() ? row.parent_id.trim() : null,
1715
+ // Local-only: stripped in summarizeSessions before any cloud/CSV export.
1716
+ title: cleanSessionTitle(row?.title),
1717
+ source: "zcode",
1718
+ // A database copied between Windows and POSIX retains its original cwd.
1719
+ project_key: projectKey(cwd && cwd.replace(/\\/g, "/"), displayPath),
1720
+ project_ref: cwd || null,
1721
+ model: modelUsage.length > 1 ? "mixed" : (modelUsage[0]?.model || "unknown"),
1722
+ model_usage: modelUsage,
1723
+ usage_buckets: [...usageBuckets.values()],
1724
+ ...bounds,
1725
+ turns: turnsBySession.get(sessionId) || 0,
1726
+ edit_turns: editTurnsBySession.get(sessionId) || 0,
1727
+ // Provider/API retries are not repeated user requests. This numeric
1728
+ // metadata has no user-prompt repetition evidence.
1729
+ retry_turns: 0,
1730
+ tokens,
1731
+ usage_events: messages.length,
1732
+ usage_precision: messages.length > 0 ? "reported" : "unavailable",
1733
+ cost_source: "model_pricing",
1734
+ provider_cost_usd: null,
1735
+ model_calls: messages.length,
1736
+ api_duration_ms: signals ? signals.apiDurationMs : 0,
1737
+ error_count: signals ? signals.errorCount : 0,
1738
+ compaction_count: signals ? signals.compactionCount : 0,
1739
+ performance: finished.performance,
1740
+ provenance: {
1741
+ source: "local-session-log",
1742
+ confidence: "observed",
1743
+ retry_confidence: "unavailable",
1744
+ content_retained: false,
1745
+ usage: messages.length > 0 ? "zcode-db-messages" : "unavailable",
1746
+ },
1747
+ }));
1748
+ }
1749
+ return records;
1750
+ }
1751
+
1752
+ // Multi-root discovery: on Windows a native install and a WSL one both count.
1753
+ // `sync` already walks both Claude homes (src/commands/sync.js), so without this
1754
+ // the WSL work lands in the token totals but is invisible in the session browser
1755
+ // and its project list. TOKENUSAGE_WSL_MODE gates which sides are probed;
1756
+ // duplicated files synced between environments collapse via the Codex session-id
1757
+ // pass below and claudeMessageDedupKey downstream.
1758
+ function providerRoots(home, providerDir, env, deps = {}) {
1759
+ const platform = deps.platform || process.platform;
1760
+ const homedir = deps.homedir || os.homedir;
1761
+ const discoverWslHome = deps.discoverWslHome || wsl.discoverWslHome;
1762
+ const roots = [];
1763
+ if (platform !== "win32" || wsl.shouldProbeNative(env)) {
1764
+ const useProcessCodexHome = providerDir === ".codex"
1765
+ && path.resolve(home) === path.resolve(homedir())
1766
+ && typeof env?.CODEX_HOME === "string"
1767
+ && env.CODEX_HOME.trim();
1768
+ // Same normalization as sync / the cursor store (scan-roots.expandHome):
1769
+ // a relative CODEX_HOME is anchored to home, never to process.cwd(), so
1770
+ // the browser walks the exact root the cursors were keyed under.
1771
+ const nativeRoot = useProcessCodexHome
1772
+ ? expandHome(env.CODEX_HOME, home)
1773
+ : path.join(home, providerDir);
1774
+ roots.push(nativeRoot);
1775
+ }
1776
+ // Only the machine's own home has a WSL sibling worth probing.
1777
+ // discoverWslHome resolves \\wsl$ independently of `home`, so probing for an
1778
+ // injected home (tests, a custom HOME) would splice the machine's live WSL
1779
+ // sessions into what the caller expects to be an isolated tree.
1780
+ //
1781
+ // This defaults rather than hard-codes: the whole reason to thread a
1782
+ // non-default home is to scan a tree that is not os.homedir(), and such a
1783
+ // caller would otherwise lose WSL discovery silently, with nothing failing.
1784
+ // `probeWsl` is the deliberate opt-in for that case.
1785
+ const probeWsl = deps.probeWsl !== undefined
1786
+ ? Boolean(deps.probeWsl)
1787
+ : path.resolve(home) === path.resolve(homedir());
1788
+ if (platform === "win32" && probeWsl && wsl.shouldProbeWsl(env)) {
1789
+ const wslRoot = discoverWslHome(providerDir, { env });
1790
+ if (wslRoot) roots.push(wslRoot);
1791
+ }
1792
+ // Extra roots (#657), mirroring src/commands/sync.js: CLAUDE_CONFIG_DIR is
1793
+ // the spawning process's implicit Claude root (additive — ~/.claude stays
1794
+ // scanned), and config.scanRoots.<provider> arrives as deps.extraRoots from
1795
+ // discoverSessionFiles. Extras are realpath-deduped against the roots above
1796
+ // so one directory listed under two spellings is walked once.
1797
+ const extras = [];
1798
+ const useProcessClaudeConfigDir = providerDir === ".claude"
1799
+ && path.resolve(home) === path.resolve(homedir())
1800
+ && typeof env?.CLAUDE_CONFIG_DIR === "string"
1801
+ && env.CLAUDE_CONFIG_DIR.trim();
1802
+ if (useProcessClaudeConfigDir) extras.push(expandHome(env.CLAUDE_CONFIG_DIR, home));
1803
+ for (const extra of Array.isArray(deps.extraRoots) ? deps.extraRoots : []) {
1804
+ if (typeof extra === "string" && extra) extras.push(path.resolve(extra));
1805
+ }
1806
+ return appendUniqueDirs([...new Set(roots)], extras);
1807
+ }
1808
+
1809
+ // Group one logical session discovered under more than one root. A group is
1810
+ // scanned as a unit so identical prefixes count once while divergent tails are
1811
+ // both retained. Same-UUID siblings inside one Claude root stay separate: the
1812
+ // path alone cannot prove which one a file in another root mirrors.
1813
+ //
1814
+ // Codex gets this from its session-id pass below; Claude only ever had per-file
1815
+ // message dedup (`claudeMessageDedupKey` inside `scanClaudeSession`), which
1816
+ // cannot see a second copy of the same file under a different path spelling.
1817
+ // Every discovered path becomes its own row keyed by the resolved file path, so
1818
+ // a WSL `$HOME` pointing at the Windows profile — the same files reachable as
1819
+ // both `C:\Users\dev\.claude\...` and `\\wsl$\Ubuntu\home\dev\.claude\...` —
1820
+ // duplicated sessions in the browser, the project list and the CSV export.
1821
+ //
1822
+ // Cross-root only, on purpose: a single root is passed through verbatim, so
1823
+ // single-install machines are unaffected, and two same-named files inside one
1824
+ // tree stay distinct (unproven identity must not delete a session). A basename
1825
+ // without a session UUID never participates either.
1826
+ function groupClaudeFilesAcrossRoots(groups) {
1827
+ const rootGroups = (groups || []).filter((group) => Array.isArray(group) && group.length > 0);
1828
+ if (rootGroups.length <= 1) return [...new Set(rootGroups[0] || [])].map((filePath) => [filePath]);
1829
+ const sessionIdOf = (filePath) =>
1830
+ path.basename(filePath).match(/^([0-9a-f-]{36})\.jsonl$/i)?.[1] || null;
1831
+
1832
+ // A UUID appearing twice inside ONE root has no resolvable identity: nothing
1833
+ // in the paths says which sibling a copy in another root mirrors. Collapsing
1834
+ // by mtime there would evict a genuinely distinct transcript — and, when the
1835
+ // other root mirrors the sibling rather than the first file, keep that content
1836
+ // twice. Such UUIDs opt out of dedup entirely; an ambiguous duplicate is
1837
+ // cheap, a deleted session is not.
1838
+ const ambiguous = new Set();
1839
+ for (const group of rootGroups) {
1840
+ const seenHere = new Set();
1841
+ for (const filePath of group) {
1842
+ const id = sessionIdOf(filePath);
1843
+ if (!id) continue;
1844
+ if (seenHere.has(id)) ambiguous.add(id);
1845
+ seenHere.add(id);
1846
+ }
1847
+ }
1848
+
1849
+ const groupedBySession = new Map();
1850
+ for (const group of rootGroups) {
1851
+ for (const filePath of group) {
1852
+ const id = sessionIdOf(filePath);
1853
+ if (!id || ambiguous.has(id)) continue;
1854
+ if (!groupedBySession.has(id)) groupedBySession.set(id, []);
1855
+ const paths = groupedBySession.get(id);
1856
+ if (!paths.includes(filePath)) paths.push(filePath);
1857
+ }
1858
+ }
1859
+
1860
+ // Preserve root order and the first path as the representative cache key.
1861
+ const ordered = [];
1862
+ const emitted = new Set();
1863
+ for (const group of rootGroups) {
1864
+ for (const filePath of group) {
1865
+ const id = sessionIdOf(filePath);
1866
+ if (!id || ambiguous.has(id)) {
1867
+ if (!emitted.has(filePath)) {
1868
+ ordered.push([filePath]);
1869
+ emitted.add(filePath);
1870
+ }
1871
+ continue;
1872
+ }
1873
+ if (emitted.has(id)) continue;
1874
+ ordered.push(groupedBySession.get(id) || [filePath]);
1875
+ emitted.add(id);
1876
+ }
1877
+ }
1878
+ return ordered;
1879
+ }
1880
+
1881
+ function sameFileContent(filePaths) {
1882
+ if (!Array.isArray(filePaths) || filePaths.length <= 1) return true;
1883
+ try {
1884
+ const first = fs.readFileSync(filePaths[0]);
1885
+ return filePaths.slice(1).every((filePath) => {
1886
+ const candidate = fs.readFileSync(filePath);
1887
+ return candidate.length === first.length && candidate.equals(first);
1888
+ });
1889
+ } catch {
1890
+ return false;
1891
+ }
1892
+ }
1893
+
1894
+ // Compatibility helper used by focused discovery tests and callers that only
1895
+ // need a flat list. Only byte-identical mirrors collapse; divergent copies are
1896
+ // all returned so no transcript tail is discarded.
1897
+ function dedupeClaudeFilesAcrossRoots(groups) {
1898
+ const mtimeOf = (filePath) => {
1899
+ try { return fs.statSync(filePath).mtimeMs; } catch { return -Infinity; }
1900
+ };
1901
+ const out = [];
1902
+ for (const filePaths of groupClaudeFilesAcrossRoots(groups)) {
1903
+ if (filePaths.length <= 1 || !sameFileContent(filePaths)) {
1904
+ out.push(...filePaths);
1905
+ continue;
1906
+ }
1907
+ out.push(filePaths.reduce((winner, candidate) => (
1908
+ mtimeOf(candidate) > mtimeOf(winner) ? candidate : winner
1909
+ )));
1910
+ }
1911
+ return [...new Set(out)];
1912
+ }
1913
+
1914
+ function groupCodexFiles(filePaths) {
1915
+ const ordered = [];
1916
+ const bySession = new Map();
1917
+ for (const filePath of [...new Set(filePaths || [])]) {
1918
+ const id = path.basename(filePath).match(/([0-9a-f-]{36})\.jsonl(?:\.zstd?)?$/i)?.[1] || filePath;
1919
+ let group = bySession.get(id);
1920
+ if (!group) {
1921
+ group = [];
1922
+ bySession.set(id, group);
1923
+ ordered.push(group);
1924
+ }
1925
+ group.push(filePath);
1926
+ }
1927
+ return ordered;
1928
+ }
1929
+
1930
+ async function scanKimiSessions(filePaths) {
1931
+ const rows = await readKimiSessions(Array.isArray(filePaths) ? filePaths : [filePaths]);
1932
+ return rows.map(({ identity, files, ...row }) => finalizeRecord({
1933
+ ...row, version: SIDECAR_VERSION, source: "kimi", session_hash: sessionHash("kimi", identity),
1934
+ project_key: projectKey(row.project_ref, files[0]), ...sessionStorageUsage(files),
1935
+ }));
1936
+ }
1937
+
1938
+ async function discoverSessionFiles(home, env = process.env, deps = {}) {
1939
+ const grokHome = resolveGrokHome(home);
1940
+ // config.scanRoots (#657): read from the tracker config unless the caller
1941
+ // injects it (tests). A missing or malformed config yields no extras.
1942
+ const scanRootsConfig = deps.scanRootsConfig !== undefined
1943
+ ? normalizeScanRootsConfig(deps.scanRootsConfig)
1944
+ : await loadScanRootsConfig({ home });
1945
+ // expandHome resolves `~` and relative entries against `home` (never cwd);
1946
+ // only readable directories are walked, absence and stat errors alike.
1947
+ const extraRootsFor = (provider) => scanRootsConfig[provider]
1948
+ .map((root) => expandHome(root, home))
1949
+ .filter((root) => root && scanRootDirState(root).exists);
1950
+ const claudeRoots = providerRoots(home, ".claude", env, { ...deps, extraRoots: extraRootsFor("claude") });
1951
+ const codexRoots = providerRoots(home, ".codex", env, { ...deps, extraRoots: extraRootsFor("codex") });
1952
+ // Two distinct roots may share one projects/ dir through a symlink; dedupe
1953
+ // the derived projects dirs by realpath (as sync does) so the browser never
1954
+ // lists the same transcript twice under two spellings.
1955
+ const claudeProjectsDirs = dedupeDirsByRealpath(claudeRoots.map((r) => path.join(r, "projects")));
1956
+ // listClaudeProjectFiles / listRolloutFilesDeep turn a listing error into an
1957
+ // empty result, so a root whose projects/ (or sessions/) exists but cannot be
1958
+ // read would look like "no sessions" and get cached as such. Report those
1959
+ // directories as incomplete discovery instead; the caller decides not to
1960
+ // persist a partial inventory (sync defers its repair on the same state).
1961
+ const incomplete = [];
1962
+ for (const dir of [
1963
+ ...claudeProjectsDirs,
1964
+ ...codexRoots.map((r) => path.join(r, "sessions")),
1965
+ ]) {
1966
+ const state = scanRootDirState(dir);
1967
+ if (state.error !== null) incomplete.push({ path: dir, error: state.error });
1968
+ }
1969
+ const [claudeGroups, codexGroups, archivedGroups, grok] = await Promise.all([
1970
+ Promise.all(claudeProjectsDirs.map((dir) => listClaudeProjectFiles(dir))),
1971
+ Promise.all(codexRoots.map((r) => listRolloutFilesDeep(path.join(r, "sessions")))),
1972
+ Promise.all(codexRoots.map((r) => listRolloutFilesDeep(path.join(r, "archived_sessions")))),
1973
+ listGrokSessionFiles(path.join(grokHome, "sessions")),
1974
+ ]);
1975
+ const allClaude = groupClaudeFilesAcrossRoots(claudeGroups);
1976
+ const codex = [...new Set(codexGroups.flat())];
1977
+ const archived = [...new Set(archivedGroups.flat())];
1978
+ // Claude Memory stores thousands of background observer transcripts beside
1979
+ // real Claude Code sessions. They contain <synthetic>/haiku bookkeeping and
1980
+ // no user coding outcome, so scanning them both slows the card dramatically
1981
+ // and dilutes its efficiency metrics.
1982
+ const claude = allClaude.filter((filePaths) => !filePaths.some((filePath) => filePath
1983
+ .split(path.sep)
1984
+ .some((segment) => segment.endsWith(CLAUDE_MEM_OBSERVER_PROJECT_SUFFIX))));
1985
+ // ZCode has no sessions directory tree — one SQLite db per install. Resolve
1986
+ // it like the usage sync does (src/commands/sync.js): native candidate first
1987
+ // (ZCODE_HOME, home, win32 APPDATA fallback), then the WSL install when the
1988
+ // WSL mode probes it, picked with the same mode priority (default wsl-first)
1989
+ // so the browser reads the same install the usage card counts. "both"
1990
+ // preserves both paths; the scanner merges shared session/event identities.
1991
+ const zcodePlatform = deps.platform || process.platform;
1992
+ const zcodeNativeDbPath = (deps.resolveZcodeNativeDbPath || resolveZcodeNativeDbPath)({ home, env, platform: zcodePlatform });
1993
+ // Same WSL gate as providerRoots(): discoverWslHome resolves \\wsl$
1994
+ // independently of `home`, so a custom/injected home must not splice the
1995
+ // machine's live WSL db into an isolated scan. `probeWsl` is the deliberate
1996
+ // opt-in (defaults to true only for the machine's own home).
1997
+ const zcodeProbeWsl = deps.probeWsl !== undefined
1998
+ ? Boolean(deps.probeWsl)
1999
+ : path.resolve(home) === path.resolve((deps.homedir || os.homedir)());
2000
+ const zcodeWslHome = zcodePlatform === "win32" && zcodeProbeWsl && wsl.shouldProbeWsl(env)
2001
+ ? (deps.discoverWslHome || wsl.discoverWslHome)(".zcode", { env })
2002
+ : null;
2003
+ const zcodeExisting = (dbPath) => (dbPath && fs.existsSync(dbPath) ? dbPath : null);
2004
+ const zcodeWslDbPath = zcodeWslHome ? path.join(zcodeWslHome, "cli", "db", "db.sqlite") : null;
2005
+ const zcodeNativeExisting = zcodeExisting(zcodeNativeDbPath);
2006
+ const { cursors } = zcodePlatform === "win32"
2007
+ ? await readCursorStateSummary({ trackerDir: path.join(home, ".tokenusage", "tracker") })
2008
+ : {};
2009
+ const zcodePaths = resolveZcodeInstallPaths({
2010
+ nativeValue: zcodePlatform === "win32" ? zcodeNativeDbPath : zcodeNativeExisting,
2011
+ wslValue: zcodeWslDbPath,
2012
+ }, env, { platform: zcodePlatform, cursors });
2013
+ const zcode = [...new Set(Object.values(zcodePaths).filter(Boolean))];
2014
+ const opencodeNativeDir = env.OPENCODE_HOME || path.join(env.XDG_DATA_HOME || path.join(home, ".local", "share"), "opencode");
2015
+ const opencodeWslDir = zcodePlatform === "win32" && zcodeProbeWsl && wsl.shouldProbeWsl(env)
2016
+ ? (deps.discoverWslHome || wsl.discoverWslHome)(".local/share/opencode", { env }) : null;
2017
+ const opencodePaths = resolveInstallPaths({ nativeValue: opencodeNativeDir, wslValue: opencodeWslDir }, env, { platform: zcodePlatform });
2018
+ const opencode = [...new Set(Object.values(opencodePaths).filter(Boolean)
2019
+ .map((dir) => path.join(dir, "opencode.db")).filter((dbPath) => fs.existsSync(dbPath)))];
2020
+ const kimiRoots = [".kimi", ".kimi-code"].flatMap((directory) => {
2021
+ const roots = providerRoots(home, directory, env, deps);
2022
+ const override = env[directory === ".kimi" ? "KIMI_HOME" : "KIMI_CODE_HOME"];
2023
+ if (override && path.resolve(home) === path.resolve((deps.homedir || os.homedir)())) {
2024
+ const native = path.join(home, directory);
2025
+ return roots.map((root) => root === native ? expandHome(override, home) : root);
2026
+ }
2027
+ return roots;
2028
+ });
2029
+ const kimi = discoverKimiWireFiles(dedupeDirsByRealpath(kimiRoots), incomplete);
2030
+ return { claude, codex: groupCodexFiles([...codex, ...archived]), grok, zcode, opencode, kimi, incomplete };
2031
+ }
2032
+
2033
+ // Warn once per unreadable directory per process: the dashboard polls this
2034
+ // path, and a line per poll would flood the serve log.
2035
+ const warnedIncompleteDiscovery = new Set();
2036
+ function warnIncompleteDiscovery(incomplete) {
2037
+ for (const entry of incomplete) {
2038
+ if (warnedIncompleteDiscovery.has(entry.path)) continue;
2039
+ warnedIncompleteDiscovery.add(entry.path);
2040
+ if (!process.env.NODE_TEST_CONTEXT) {
2041
+ console.warn(`[session-analytics] session directory unreadable (${entry.error}), inventory incomplete: ${entry.path}`);
2042
+ }
2043
+ }
2044
+ }
2045
+
2046
+ function filesSignature(files) {
2047
+ const hash = crypto.createHash("sha256");
2048
+ for (const filePath of files) {
2049
+ try {
2050
+ const stat = fs.statSync(filePath);
2051
+ hash.update(`${filePath}\0${stat.size}\0${stat.mtimeMs}\n`);
2052
+ } catch { /* vanished during discovery */ }
2053
+ }
2054
+ return hash.digest("hex");
2055
+ }
2056
+
2057
+ function sessionFileCacheKey(source, filePath) {
2058
+ const filePaths = (Array.isArray(filePath) ? filePath : [filePath]).filter(Boolean);
2059
+ return crypto
2060
+ .createHash("sha256")
2061
+ .update(`${source}\0${filePaths.map((value) => path.resolve(value)).join("\0")}`)
2062
+ .digest("hex")
2063
+ .slice(0, 24);
2064
+ }
2065
+
2066
+ function sessionFileStatKey(filePath) {
2067
+ try {
2068
+ const stat = fs.statSync(filePath);
2069
+ return `${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
2070
+ } catch {
2071
+ return null;
2072
+ }
2073
+ }
2074
+
2075
+ // Codex records its own per-thread title (thread_name) in
2076
+ // ~/.codex/session_index.jsonl (`{ id, thread_name, updated_at }`). We read it
2077
+ // once per build and memoize by the index's stat so repeated scans are cheap.
2078
+ const codexTitleIndexCache = new Map();
2079
+
2080
+ function codexTitleIndexPathFor(filePath) {
2081
+ let current = path.dirname(path.resolve(filePath));
2082
+ while (true) {
2083
+ if (["sessions", "archived_sessions"].includes(path.basename(current))) {
2084
+ return path.join(path.dirname(current), "session_index.jsonl");
2085
+ }
2086
+ const parent = path.dirname(current);
2087
+ if (parent === current) return null;
2088
+ current = parent;
2089
+ }
2090
+ }
2091
+
2092
+ function loadCodexTitleIndex(filePath) {
2093
+ const indexPath = codexTitleIndexPathFor(filePath);
2094
+ if (!indexPath) return new Map();
2095
+ const statKey = sessionFileStatKey(indexPath);
2096
+ const cached = codexTitleIndexCache.get(indexPath);
2097
+ if (cached && cached.statKey === statKey) return cached.titles;
2098
+ const titles = new Map();
2099
+ if (statKey) {
2100
+ try {
2101
+ for (const line of fs.readFileSync(indexPath, "utf8").split("\n")) {
2102
+ if (!line.trim()) continue;
2103
+ let obj;
2104
+ try { obj = JSON.parse(line); } catch { continue; }
2105
+ const id = typeof obj?.id === "string" ? obj.id : null;
2106
+ const name = cleanSessionTitle(obj?.thread_name);
2107
+ if (id && name) titles.set(id, name);
2108
+ }
2109
+ } catch { /* no index yet */ }
2110
+ }
2111
+ codexTitleIndexCache.set(indexPath, { statKey, titles });
2112
+ return titles;
2113
+ }
2114
+
2115
+ // A Codex row also depends on session_index.jsonl, not just its rollout file.
2116
+ // Include that dependency in the incremental cache key so renaming a thread is
2117
+ // visible after the next refresh instead of leaving a stale title indefinitely.
2118
+ // Grok titles live in sibling summary.json (and signals can change without
2119
+ // touching updates.jsonl on some partial flushes).
2120
+ function analyticsEntryStatKey(source, filePath) {
2121
+ const filePaths = (Array.isArray(filePath) ? filePath : [filePath]).filter(Boolean);
2122
+ const sessionStats = filePaths.map((value) => sessionFileStatKey(value) || "missing");
2123
+ if (sessionStats.every((value) => value === "missing")) return null;
2124
+ const sessionStat = sessionStats.join("|");
2125
+ if (source === "codex") {
2126
+ const titleStats = filePaths.map((value) => (
2127
+ sessionFileStatKey(codexTitleIndexPathFor(value)) || "missing"
2128
+ ));
2129
+ return `${sessionStat}|title-index:${titleStats.join("|")}`;
2130
+ }
2131
+ if (source === "kimi") {
2132
+ return `${sessionStat}|metadata:${filesSignature(kimiSessionDependencies(filePaths))}`;
2133
+ }
2134
+ if (source === "grok") {
2135
+ const primary = filePaths[0];
2136
+ return `${sessionStat}|summary:${sessionFileStatKey(grokSummaryPathFor(primary)) || "missing"}|signals:${sessionFileStatKey(grokSignalsPathFor(primary)) || "missing"}`;
2137
+ }
2138
+ if (source === "zcode" || source === "opencode") {
2139
+ // A WAL-mode db can absorb writes without touching the main file's mtime,
2140
+ // so the sidecar files are part of the db's identity for cache checks.
2141
+ return `${sessionStat}|sidecars:${filePaths.map((filePath) =>
2142
+ `wal:${sessionFileStatKey(`${filePath}-wal`) || "missing"}|shm:${sessionFileStatKey(`${filePath}-shm`) || "missing"}`).join("|")}`;
2143
+ }
2144
+ return sessionStat;
2145
+ }
2146
+
2147
+ function readSidecar(sidecarPath) {
2148
+ try {
2149
+ return fs.readFileSync(sidecarPath, "utf8")
2150
+ .split("\n")
2151
+ .filter(Boolean)
2152
+ .map((line) => repriceSessionRecord(JSON.parse(line)));
2153
+ } catch { return []; }
2154
+ }
2155
+
2156
+ async function writeAtomic(filePath, content) {
2157
+ await fsp.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
2158
+ const temp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
2159
+ await fsp.writeFile(temp, content, { encoding: "utf8", mode: 0o600 });
2160
+ await fsp.rename(temp, filePath);
2161
+ }
2162
+
2163
+ async function buildSessionAnalyticsInternal({ home = os.homedir(), force = false, cacheTtlMs = 5 * 60_000 } = {}) {
2164
+ const sidecarPath = resolveSessionSidecarPath(home);
2165
+ const metaPath = `${sidecarPath}.meta.json`;
2166
+ // A lock/permission failure need not alter the database's stat signature.
2167
+ // Keep a separate durable invalidation marker while preserving the complete
2168
+ // sidecar and metadata. TTL, signature and per-file reuse must all retry it.
2169
+ const incompleteZcodePath = `${metaPath}.zcode-incomplete`;
2170
+ const retryZcodeScan = fs.existsSync(incompleteZcodePath);
2171
+ const incompleteOpencodePath = `${metaPath}.opencode-incomplete`;
2172
+ const retryOpencodeScan = fs.existsSync(incompleteOpencodePath);
2173
+ const incompleteKimiPath = `${metaPath}.kimi-incomplete`;
2174
+ const retryKimiScan = fs.existsSync(incompleteKimiPath);
2175
+ let previousMeta = null;
2176
+ if (!force) {
2177
+ try {
2178
+ previousMeta = JSON.parse(fs.readFileSync(metaPath, "utf8"));
2179
+ const checkedAt = Date.parse(previousMeta.checked_at || previousMeta.generated_at || "");
2180
+ if (
2181
+ !retryZcodeScan && !retryOpencodeScan && !retryKimiScan && previousMeta.version === SIDECAR_VERSION &&
2182
+ Number.isFinite(checkedAt) &&
2183
+ Date.now() - checkedAt < Math.max(0, Number(cacheTtlMs) || 0)
2184
+ ) {
2185
+ return readSidecar(sidecarPath);
2186
+ }
2187
+ } catch { /* first run */ }
2188
+ }
2189
+ const discovered = await discoverSessionFiles(home);
2190
+ // Incomplete discovery (an unreadable projects/ or sessions/ dir): never let
2191
+ // a partial inventory replace a complete snapshot. Serve the last complete
2192
+ // sidecar when there is one; otherwise build from what is readable but do
2193
+ // not persist it, so the next refresh tries again.
2194
+ const incompleteDirs = Array.isArray(discovered.incomplete) ? discovered.incomplete : [];
2195
+ if (incompleteDirs.length > 0) {
2196
+ warnIncompleteDiscovery(incompleteDirs);
2197
+ if (!force && previousMeta?.version === SIDECAR_VERSION) {
2198
+ const cached = readSidecar(sidecarPath);
2199
+ Object.defineProperty(cached, "incompleteDirs", { value: incompleteDirs, enumerable: false });
2200
+ return cached;
2201
+ }
2202
+ }
2203
+ // Codex thread titles are stored separately from rollout files. Include the
2204
+ // index in the overall signature so an index-only rename reaches the
2205
+ // per-file dependency check below on the next refresh. Grok titles/metadata
2206
+ // live in sibling summary.json / signals.json next to updates.jsonl.
2207
+ const signature = filesSignature([
2208
+ ...discovered.claude.flat(),
2209
+ ...discovered.codex.flat(),
2210
+ ...discovered.codex.flat().map(codexTitleIndexPathFor).filter(Boolean),
2211
+ ...discovered.kimi,
2212
+ ...kimiSessionDependencies(discovered.kimi),
2213
+ ...discovered.grok,
2214
+ ...discovered.grok.map(grokSummaryPathFor),
2215
+ ...discovered.grok.map(grokSignalsPathFor),
2216
+ // db + its WAL sidecars: the trio is one logical file for change detection.
2217
+ ...[...(discovered.zcode || []), ...(discovered.opencode || [])].flatMap((dbPath) => [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]),
2218
+ ]);
2219
+ if (!force && !retryZcodeScan && !retryOpencodeScan && !retryKimiScan && previousMeta?.version === SIDECAR_VERSION && previousMeta.signature === signature) {
2220
+ await writeAtomic(metaPath, `${JSON.stringify({ ...previousMeta, checked_at: new Date().toISOString() })}\n`);
2221
+ return readSidecar(sidecarPath);
2222
+ }
2223
+
2224
+ const previousRows = !force && previousMeta?.version === SIDECAR_VERSION
2225
+ ? readSidecar(sidecarPath)
2226
+ : [];
2227
+ const previousRowsByFile = new Map(previousRows
2228
+ .filter((row) => typeof row?._cache_key === "string")
2229
+ .map((row) => [row._cache_key, row]));
2230
+ const previousFiles = previousMeta?.version === SIDECAR_VERSION && previousMeta.files
2231
+ ? previousMeta.files
2232
+ : {};
2233
+ const nextFiles = {};
2234
+ const sessions = [];
2235
+ const entries = [
2236
+ ...discovered.claude.map((filePaths) => ({ source: "claude", filePath: filePaths, scan: scanClaudeSession })),
2237
+ ...discovered.codex.map((filePaths) => ({ source: "codex", filePath: filePaths, scan: scanCodexSession })),
2238
+ ...discovered.grok.map((filePath) => ({ source: "grok", filePath, scan: scanGrokSession })),
2239
+ ...(discovered.zcode.length ? [{ source: "zcode", filePath: discovered.zcode, scan: scanZcodeSessions }] : []),
2240
+ ...(discovered.opencode.length ? [{ source: "opencode", filePath: discovered.opencode, scan: scanOpencodeSessions }] : []),
2241
+ ...(discovered.kimi.length ? [{ source: "kimi", filePath: discovered.kimi, scan: scanKimiSessions }] : []),
2242
+ ];
2243
+ // Files we could not turn into a row (permission denied, half-written line,
2244
+ // vanished mid-scan). Swallowing these silently made sessions disappear with
2245
+ // no signal at all; count them so the API can say so.
2246
+ let skippedFiles = 0;
2247
+ let incompleteZcodeScan = false;
2248
+ let incompleteOpencodeScan = false;
2249
+ let incompleteKimiScan = false;
2250
+ for (const entry of entries) {
2251
+ const cacheKey = sessionFileCacheKey(entry.source, entry.filePath);
2252
+ const statKey = analyticsEntryStatKey(entry.source, entry.filePath);
2253
+ if (!statKey) {
2254
+ skippedFiles += 1;
2255
+ if (entry.source === "zcode") incompleteZcodeScan = true;
2256
+ if (entry.source === "opencode") incompleteOpencodeScan = true;
2257
+ if (entry.source === "kimi") incompleteKimiScan = true;
2258
+ continue;
2259
+ }
2260
+ let rows = null;
2261
+ if (!force && !(entry.source === "zcode" && retryZcodeScan) && !(entry.source === "opencode" && retryOpencodeScan) && !(entry.source === "kimi" && retryKimiScan) && previousFiles[cacheKey]?.stat_key === statKey) {
2262
+ if (entry.source === "zcode" || entry.source === "opencode" || entry.source === "kimi") {
2263
+ // One db scans to many cached rows; recover them all from the previous
2264
+ // pass. An empty recovery means the sidecar lost its rows — rescan.
2265
+ const cached = previousRows.filter((row) => row?.source === entry.source);
2266
+ rows = cached.length ? cached : null;
2267
+ } else {
2268
+ const row = previousRowsByFile.get(cacheKey) || null;
2269
+ rows = row ? [row] : null;
2270
+ }
2271
+ }
2272
+ if (!rows) {
2273
+ try {
2274
+ const scanned = await entry.scan(entry.filePath);
2275
+ rows = Array.isArray(scanned) ? scanned.filter(Boolean) : (scanned ? [scanned] : []);
2276
+ } catch (error) {
2277
+ // One active/partial session must not poison the sidecar, but do not
2278
+ // pretend it never existed either.
2279
+ skippedFiles += 1;
2280
+ if (entry.source === "zcode") incompleteZcodeScan = true;
2281
+ if (entry.source === "opencode") incompleteOpencodeScan = true;
2282
+ if (entry.source === "kimi") incompleteKimiScan = true;
2283
+ if (!process.env.NODE_TEST_CONTEXT) {
2284
+ console.warn(`[session-analytics] skipped ${entry.source} session file: ${error?.message || error}`);
2285
+ }
2286
+ rows = [];
2287
+ }
2288
+ }
2289
+ for (const row of rows) {
2290
+ repriceSessionRecord(row);
2291
+ // A one-way file hash enables incremental reuse without persisting or
2292
+ // exposing the user's local session path. ZCode's rows all share one db,
2293
+ // so key each by the db path plus its session id; a bare session id as a
2294
+ // separate path element would be path.resolve()d against the process cwd
2295
+ // and never match across runs.
2296
+ row._cache_key = (entry.source === "zcode" || entry.source === "opencode" || entry.source === "kimi") && (row.session_id || row.session_hash)
2297
+ ? `${cacheKey}#${sessionHash(entry.source, row.session_id || row.session_hash)}`
2298
+ : cacheKey;
2299
+ sessions.push(row);
2300
+ }
2301
+ if (rows.length > 0) nextFiles[cacheKey] = { stat_key: statKey };
2302
+ }
2303
+ if (incompleteZcodeScan) {
2304
+ await writeAtomic(incompleteZcodePath, "1\n");
2305
+ // ZCode databases form one deduplicated inventory. If any read fails, retain its last
2306
+ // complete rows even on a forced refresh; skippedFiles still reports that
2307
+ // these rows could not be refreshed. Older cache schemas must be rebuilt.
2308
+ sessions.push(...readSidecar(sidecarPath).filter((row) =>
2309
+ row.source === "zcode" && row.version === SIDECAR_VERSION));
2310
+ }
2311
+ if (incompleteOpencodeScan) {
2312
+ await writeAtomic(incompleteOpencodePath, "1\n");
2313
+ sessions.push(...readSidecar(sidecarPath).filter((row) =>
2314
+ row.source === "opencode" && row.version === SIDECAR_VERSION));
2315
+ }
2316
+ if (incompleteKimiScan) {
2317
+ await writeAtomic(incompleteKimiPath, "1\n");
2318
+ sessions.push(...readSidecar(sidecarPath).filter((row) => row.source === "kimi" && row.version === SIDECAR_VERSION));
2319
+ }
2320
+ sessions.sort((a, b) => String(b.ended_at || "").localeCompare(String(a.ended_at || "")));
2321
+ // A failed database scan is an incomplete inventory. Keep the last complete
2322
+ // snapshot and signature so an unchanged database is retried next build.
2323
+ if (incompleteDirs.length === 0 && !incompleteZcodeScan && !incompleteOpencodeScan && !incompleteKimiScan) {
2324
+ const content = sessions.map(serializeSessionRecord).join("\n") + (sessions.length ? "\n" : "");
2325
+ await writeAtomic(sidecarPath, content);
2326
+ const generatedAt = new Date().toISOString();
2327
+ await writeAtomic(metaPath, `${JSON.stringify({
2328
+ version: SIDECAR_VERSION,
2329
+ signature,
2330
+ generated_at: generatedAt,
2331
+ checked_at: generatedAt,
2332
+ files: nextFiles,
2333
+ })}\n`);
2334
+ await fsp.rm(incompleteZcodePath, { force: true });
2335
+ await fsp.rm(incompleteOpencodePath, { force: true });
2336
+ await fsp.rm(incompleteKimiPath, { force: true });
2337
+ }
2338
+ // Non-enumerable so the array still behaves exactly like a plain row list
2339
+ // for every existing caller (map/filter/JSON of the rows is unaffected).
2340
+ Object.defineProperty(sessions, "skippedFiles", { value: skippedFiles, enumerable: false });
2341
+ Object.defineProperty(sessions, "incompleteDirs", { value: incompleteDirs, enumerable: false });
2342
+ return sessions;
2343
+ }
2344
+
2345
+ // A cold scan walks every local Claude/Codex/Grok session file. Period switches
2346
+ // can issue overlapping requests while that scan is still running; share the
2347
+ // promise per home so those requests wait for one scan instead of multiplying
2348
+ // the disk work and racing the atomic sidecar write.
2349
+ const sessionAnalyticsBuilds = new Map();
2350
+
2351
+ function buildSessionAnalytics(options = {}) {
2352
+ const normalizedOptions = options && typeof options === "object" ? options : {};
2353
+ const home = path.resolve(String(normalizedOptions.home || os.homedir()));
2354
+ const force = Boolean(normalizedOptions.force);
2355
+ const existing = sessionAnalyticsBuilds.get(home);
2356
+ // Joining an in-flight build is only correct when that build is at least as
2357
+ // thorough as what this caller asked for. A refresh that landed while a plain
2358
+ // build was running used to be handed the un-refreshed result: the spinner
2359
+ // stopped and nothing had actually been re-scanned. Chain instead of joining
2360
+ // — never run two scans at once, they race the atomic sidecar write.
2361
+ if (existing && (!force || existing.force)) return existing.promise;
2362
+
2363
+ const run = () => buildSessionAnalyticsInternal({ ...normalizedOptions, home, force });
2364
+ const promise = existing ? existing.promise.then(run, run) : run();
2365
+ const entry = { promise, force: force || Boolean(existing?.force) };
2366
+ sessionAnalyticsBuilds.set(home, entry);
2367
+ const clear = () => {
2368
+ if (sessionAnalyticsBuilds.get(home) === entry) sessionAnalyticsBuilds.delete(home);
2369
+ };
2370
+ promise.then(clear, clear);
2371
+ return promise;
2372
+ }
2373
+
2374
+ // Does a session overlap the [from, to] day window? Testing started_at alone
2375
+ // dropped every session that began before the window and ended inside it —
2376
+ // exactly the long/resumed ones, which also sort to the top because the sort
2377
+ // key is ended_at. On real data a 7-day window lost 6 sessions, the largest
2378
+ // 224M tokens. Treat the window as an interval intersection instead.
2379
+ function sessionUsageDay(timestamp, { timeZone, offsetMinutes } = {}) {
2380
+ const date = new Date(timestamp);
2381
+ if (!Number.isFinite(date.getTime())) return "";
2382
+ if (timeZone) {
2383
+ try {
2384
+ const parts = new Intl.DateTimeFormat("en-CA", { timeZone, year: "numeric", month: "2-digit", day: "2-digit" }).formatToParts(date);
2385
+ const part = (name) => parts.find((p) => p.type === name)?.value;
2386
+ return `${part("year")}-${part("month")}-${part("day")}`;
2387
+ } catch { /* fall back to the caller's offset or UTC */ }
2388
+ }
2389
+ return new Date(date.getTime() + (Number.isFinite(offsetMinutes) ? offsetMinutes * 60_000 : 0)).toISOString().slice(0, 10);
2390
+ }
2391
+
2392
+ function withinDayRange(row, from, to, context) {
2393
+ const startDay = sessionUsageDay(row?.started_at || row?.ended_at || "", context);
2394
+ const endDay = sessionUsageDay(row?.ended_at || row?.started_at || "", context);
2395
+ if (from && (!endDay || endDay < from)) return false;
2396
+ if (to && (!startDay || startDay > to)) return false;
2397
+ return true;
2398
+ }
2399
+
2400
+ function scopeSessionUsage(row, from, to, context) {
2401
+ if ((!from && !to) || !Array.isArray(row.usage_buckets)) return { ...row };
2402
+ const buckets = row.usage_buckets.filter((bucket) => {
2403
+ const day = sessionUsageDay(bucket.timestamp, context);
2404
+ return (!from || day >= from) && (!to || day <= to);
2405
+ });
2406
+ const tokens = emptyTotals();
2407
+ const byModel = new Map();
2408
+ for (const bucket of buckets) {
2409
+ addTotals(tokens, bucket);
2410
+ const model = byModel.get(bucket.model) || { model: bucket.model, ...emptyTotals(), usage_events: 0 };
2411
+ addTotals(model, bucket);
2412
+ mergeUsageMetadata(model, bucket);
2413
+ if (!bucket.usage_events) model.usage_events += 1;
2414
+ byModel.set(bucket.model, model);
2415
+ }
2416
+ return repriceSessionRecord({ ...row, tokens, total_tokens: tokens.total_tokens,
2417
+ model_usage: [...byModel.values()], usage_buckets: buckets, cost_usd: 0,
2418
+ lifetime_total_tokens: row.total_tokens, lifetime_cost_usd: row.cost_usd });
2419
+ }
2420
+
2421
+ function summarizeSessions(sessions, { from = "", to = "", includeSessions = true, timeZone, offsetMinutes } = {}) {
2422
+ const context = { timeZone, offsetMinutes };
2423
+ const filtered = annotateThreadUsage((sessions || [])
2424
+ .filter((row) => withinDayRange(row, from, to, context))
2425
+ // Efficiency is a session-lifetime metric: both tokens and edit turns
2426
+ // must describe that same population. The browser scopes consumption
2427
+ // separately; do not divide in-range tokens by lifetime edit counts here.
2428
+ .map((row) => ({ ...row })));
2429
+ const byModel = new Map();
2430
+ const subagents = new Map();
2431
+ const totals = {
2432
+ sessions: 0,
2433
+ productive_sessions: 0,
2434
+ one_shot_sessions: 0,
2435
+ edit_turns: 0,
2436
+ retries: 0,
2437
+ total_tokens: 0,
2438
+ cost_usd: 0,
2439
+ performance: normalizePerformance(),
2440
+ edit_tokens: 0,
2441
+ edit_cost_usd: 0,
2442
+ };
2443
+ for (const row of filtered) {
2444
+ totals.sessions += 1;
2445
+ if (row.productive) totals.productive_sessions += 1;
2446
+ if (row.first_pass ?? row.one_shot) totals.one_shot_sessions += 1;
2447
+ totals.edit_turns += finite(row.edit_turns);
2448
+ totals.retries += finite(row.retry_turns);
2449
+ totals.total_tokens += finite(row.total_tokens);
2450
+ totals.cost_usd += finite(row.cost_usd);
2451
+ totals.performance = mergePerformance(totals.performance, row.performance);
2452
+ if (row.productive) {
2453
+ totals.edit_tokens += finite(row.total_tokens);
2454
+ totals.edit_cost_usd += finite(row.cost_usd);
2455
+ }
2456
+
2457
+ // One session contributes a row to EVERY model it used, so per-model
2458
+ // `sessions` counts "sessions that touched this model" and the column does
2459
+ // NOT sum to summary.sessions (a session that switched models mid-thread
2460
+ // is counted once per model). Token, cost, edit_turn and edit_token columns
2461
+ // DO sum exactly - only the session headcount overlaps. Read the session
2462
+ // total from summary.sessions / session_count, never by summing this column;
2463
+ // test/session-analytics.test.js locks both halves of that contract.
2464
+ const usageRows = modelUsageForAggregation(row);
2465
+ const primaryModel = usageRows[0]?.model || "unknown";
2466
+ for (const usage of usageRows) {
2467
+ const key = usage.model || "unknown";
2468
+ const agg = byModel.get(key) || {
2469
+ model: key,
2470
+ sessions: 0,
2471
+ productive_sessions: 0,
2472
+ one_shot_sessions: 0,
2473
+ edit_turns: 0,
2474
+ retries: 0,
2475
+ total_tokens: 0,
2476
+ cost_usd: 0,
2477
+ performance: normalizePerformance(),
2478
+ edit_tokens: 0,
2479
+ edit_cost_usd: 0,
2480
+ usage_events: 0,
2481
+ rerouted_usage_events: 0,
2482
+ long_context_usage_events: 0,
2483
+ model_attribution: "selected",
2484
+ };
2485
+ agg.sessions += 1;
2486
+ if (row.productive) agg.productive_sessions += 1;
2487
+ if (row.first_pass ?? row.one_shot) agg.one_shot_sessions += 1;
2488
+ agg.total_tokens += finite(usage.total_tokens);
2489
+ agg.cost_usd += finite(usage.cost_usd);
2490
+ agg.performance = mergePerformance(agg.performance, usage.performance);
2491
+ agg.usage_events += finite(usage.usage_events);
2492
+ agg.rerouted_usage_events += finite(usage.rerouted_usage_events);
2493
+ agg.long_context_usage_events += finite(usage.long_context_usage_events);
2494
+ if (usage.model_attribution === "effective") agg.model_attribution = "effective";
2495
+ // Numerator and denominator of tokens_per_edit / cost_per_edit must come
2496
+ // from the same population, so both are per model: an edit turn is a
2497
+ // turn, and turn_context names the model that owns it. Giving one model
2498
+ // the whole session's edit_turns but only its own slice of the tokens
2499
+ // understated the ratio and broke sum(edit_tokens) == summary.edit_tokens.
2500
+ agg.edit_turns += finite(usage.edit_turns);
2501
+ if (row.productive) {
2502
+ agg.edit_tokens += finite(usage.total_tokens);
2503
+ agg.edit_cost_usd += finite(usage.cost_usd);
2504
+ }
2505
+ // Retries are deliberately NOT split. A retry is detected from the user
2506
+ // prompt, and user_message / turn_context ordering is not stable in Codex
2507
+ // rollouts (1332 one way vs 1139 the other across 400 local files), so a
2508
+ // per-model retry would name the wrong turn about as often as the right
2509
+ // one. Attributing them to the busiest model keeps the column summing to
2510
+ // summary.retries without claiming a precision the log cannot support.
2511
+ if (key === primaryModel) agg.retries += finite(row.retry_turns);
2512
+ byModel.set(key, agg);
2513
+ }
2514
+ if ((row.source === "codex" || row.source === "zcode" || row.source === "opencode") && row.parent_session_hash) {
2515
+ const name = row.agent_role || row.agent_nickname || "subagent";
2516
+ const sub = subagents.get(name) || {
2517
+ name,
2518
+ calls: 0,
2519
+ sessions: 0,
2520
+ total_tokens: 0,
2521
+ cost_usd: 0,
2522
+ attribution: "observed-child-session",
2523
+ };
2524
+ sub.calls += 1;
2525
+ sub.sessions += 1;
2526
+ sub.total_tokens += finite(row.total_tokens);
2527
+ sub.cost_usd += finite(row.cost_usd);
2528
+ subagents.set(name, sub);
2529
+ continue;
2530
+ }
2531
+ // Codex and ZCode children are first-class rows. A spawn call in the parent is
2532
+ // a control-plane event, not token usage, so do not mix in an estimate.
2533
+ if (row.source === "codex" || row.source === "zcode" || row.source === "opencode") continue;
2534
+ for (const [name, calls] of Object.entries(row.subagent_types || {})) {
2535
+ const sub = subagents.get(name) || { name, calls: 0, sessions: 0, total_tokens: 0, cost_usd: 0 };
2536
+ sub.calls += finite(calls);
2537
+ sub.sessions += 1;
2538
+ // Token allocation is an explicit estimate because vendor logs do not
2539
+ // consistently expose child usage separately.
2540
+ const share = Math.min(1, finite(calls) / Math.max(1, finite(row.turns)));
2541
+ sub.total_tokens += finite(row.total_tokens) * share;
2542
+ sub.cost_usd += finite(row.cost_usd) * share;
2543
+ subagents.set(name, sub);
2544
+ }
2545
+ }
2546
+ const by_model = [...byModel.values()].map((row) => ({
2547
+ ...row,
2548
+ productive_rate: row.sessions ? row.productive_sessions / row.sessions : null,
2549
+ one_shot_rate: row.productive_sessions ? row.one_shot_sessions / row.productive_sessions : null,
2550
+ edit_sessions: row.productive_sessions,
2551
+ first_pass_sessions: row.one_shot_sessions,
2552
+ edit_session_rate: row.sessions ? row.productive_sessions / row.sessions : null,
2553
+ first_pass_rate: row.productive_sessions ? row.one_shot_sessions / row.productive_sessions : null,
2554
+ tokens_per_edit: row.edit_turns ? row.edit_tokens / row.edit_turns : null,
2555
+ cost_per_edit: row.edit_turns ? row.edit_cost_usd / row.edit_turns : null,
2556
+ })).sort((a, b) => b.edit_turns - a.edit_turns || b.productive_sessions - a.productive_sessions || b.sessions - a.sessions);
2557
+ return {
2558
+ available: filtered.length > 0,
2559
+ // Local filesystem paths and raw session ids are required internally for
2560
+ // Git attribution and the local-only session browser, but never leave the
2561
+ // Node process through API/CSV payloads.
2562
+ sessions: includeSessions
2563
+ ? filtered.map(({
2564
+ project_ref: _projectRef,
2565
+ session_id: _sessionId,
2566
+ parent_session_id: _parentSessionId,
2567
+ forked_from_id: _forkedFromId,
2568
+ parent_session_hash: _parentSessionHash,
2569
+ root_session_hash: _rootSessionHash,
2570
+ agent_nickname: _agentNickname,
2571
+ agent_role: _agentRole,
2572
+ thread_source: _threadSource,
2573
+ parent_link_conflict: _parentLinkConflict,
2574
+ orphaned_subagent: _orphanedSubagent,
2575
+ title: _title,
2576
+ _cache_key: _cacheKey,
2577
+ ...row
2578
+ }) => row)
2579
+ : [],
2580
+ session_count: filtered.length,
2581
+ summary: {
2582
+ ...totals,
2583
+ productive_rate: totals.sessions ? totals.productive_sessions / totals.sessions : null,
2584
+ one_shot_rate: totals.productive_sessions ? totals.one_shot_sessions / totals.productive_sessions : null,
2585
+ edit_sessions: totals.productive_sessions,
2586
+ first_pass_sessions: totals.one_shot_sessions,
2587
+ edit_session_rate: totals.sessions ? totals.productive_sessions / totals.sessions : null,
2588
+ first_pass_rate: totals.productive_sessions ? totals.one_shot_sessions / totals.productive_sessions : null,
2589
+ tokens_per_edit: totals.edit_turns ? totals.edit_tokens / totals.edit_turns : null,
2590
+ cost_per_edit: totals.edit_turns ? totals.edit_cost_usd / totals.edit_turns : null,
2591
+ },
2592
+ by_model,
2593
+ subagents: [...subagents.values()].sort((a, b) => b.calls - a.calls),
2594
+ provenance: {
2595
+ source: "local-session-log",
2596
+ confidence: "observed",
2597
+ privacy: "metadata-only",
2598
+ methodology: "edit-turn-v2",
2599
+ edit_turn: "user turn containing an observed edit tool",
2600
+ first_pass: "exactly one edit turn and no repeated user request",
2601
+ },
2602
+ };
2603
+ }
2604
+
2605
+ // Build the resume command a user can run to continue a past session. The
2606
+ // session id is a vendor-generated UUID and never contains user prose.
2607
+ function resumeCommandFor(source, sessionId) {
2608
+ const id = typeof sessionId === "string" ? sessionId.trim() : "";
2609
+ // Session ids come from local log files, which can be edited by other local
2610
+ // processes. Only emit an unquoted shell token so copying the suggested
2611
+ // command can never smuggle whitespace, flags, or shell metacharacters into
2612
+ // the user's terminal. Claude also has a small set of legacy non-UUID ids,
2613
+ // so keep the accepted alphabet broader than UUID while still shell-safe.
2614
+ if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(id)) return null;
2615
+ if (source === "claude") return `claude --resume ${id}`;
2616
+ if (source === "codex") return `codex resume ${id}`;
2617
+ if (source === "opencode") return `opencode --session ${id}`;
2618
+ if (source === "kimi") return `kimi --session ${id}`;
2619
+ // Grok Build: `grok --resume <session-id>` (also accepts a title). The
2620
+ // command must still be run from the session's project_ref cwd.
2621
+ if (source === "grok") return `grok --resume ${id}`;
2622
+ return null;
2623
+ }
2624
+
2625
+ function toSessionBrowserRow(row) {
2626
+ const tokens = row.tokens && typeof row.tokens === "object" ? row.tokens : {};
2627
+ return {
2628
+ session_hash: row.session_hash,
2629
+ session_id: row.session_id || null,
2630
+ parent_session_id: row.parent_session_id || null,
2631
+ parent_session_hash: row.parent_session_hash || null,
2632
+ root_session_hash: row.root_session_hash || row.session_hash,
2633
+ thread_kind: row.parent_session_id ? "subagent" : "root",
2634
+ agent_nickname: row.agent_nickname || null,
2635
+ agent_role: row.agent_role || null,
2636
+ orphaned_subagent: Boolean(row.orphaned_subagent),
2637
+ parent_link_conflict: Boolean(row.parent_link_conflict),
2638
+ title: row.title || null,
2639
+ source: row.source,
2640
+ ...(Number.isFinite(row.session_store_bytes) ? {
2641
+ session_store_bytes: row.session_store_bytes,
2642
+ session_store_metric: row.session_store_metric,
2643
+ bytes_per_1k_tokens: (row.lifetime_total_tokens ?? row.total_tokens) > 0
2644
+ ? row.session_store_bytes * 1000 / (row.lifetime_total_tokens ?? row.total_tokens) : null,
2645
+ } : {}),
2646
+ project_key: row.project_key,
2647
+ // project_ref (the local cwd) only ever travels over the local API so the
2648
+ // browser can show where a session ran and compose a resume command.
2649
+ project_ref: row.project_ref || null,
2650
+ model: row.model,
2651
+ model_usage: modelUsageForAggregation(row),
2652
+ ...(Array.isArray(row.usage_buckets) ? { usage_buckets: row.usage_buckets } : {}),
2653
+ performance: normalizePerformance(row.performance),
2654
+ started_at: row.started_at || null,
2655
+ ended_at: row.ended_at || null,
2656
+ duration_ms: finite(row.duration_ms),
2657
+ turns: finite(row.turns),
2658
+ edit_turns: finite(row.edit_turns),
2659
+ retry_turns: finite(row.retry_turns),
2660
+ subagent_calls: finite(row.subagent_calls),
2661
+ input_tokens: finite(tokens.input_tokens),
2662
+ cached_input_tokens: finite(tokens.cached_input_tokens),
2663
+ cache_creation_input_tokens: finite(tokens.cache_creation_input_tokens),
2664
+ output_tokens: finite(tokens.output_tokens),
2665
+ reasoning_output_tokens: finite(tokens.reasoning_output_tokens),
2666
+ direct_subagent_count: finite(row.direct_subagent_count),
2667
+ descendant_subagent_count: finite(row.descendant_subagent_count),
2668
+ own_total_tokens: finite(row.total_tokens),
2669
+ subagent_total_tokens: finite(row.subagent_total_tokens),
2670
+ combined_total_tokens: finite(row.combined_total_tokens || row.total_tokens),
2671
+ total_tokens: finite(row.total_tokens),
2672
+ own_cost_usd: finite(row.cost_usd),
2673
+ subagent_cost_usd: finite(row.subagent_cost_usd),
2674
+ combined_cost_usd: finite(row.combined_cost_usd || row.cost_usd),
2675
+ cost_usd: finite(row.cost_usd),
2676
+ cost_source: row.cost_source || null,
2677
+ usage_precision: row.usage_precision || null,
2678
+ usage_is_incomplete: Boolean(row.usage_is_incomplete),
2679
+ cost_is_partial: Boolean(row.cost_is_partial),
2680
+ usage_events: finite(row.usage_events),
2681
+ model_calls: finite(row.model_calls),
2682
+ api_duration_ms: finite(row.api_duration_ms),
2683
+ context_tokens_used: finite(row.context_tokens_used),
2684
+ context_window_tokens: finite(row.context_window_tokens),
2685
+ context_usage_percent: finite(row.context_usage_percent),
2686
+ tool_calls: finite(row.tool_calls),
2687
+ tool_failures: finite(row.tool_failures),
2688
+ error_count: finite(row.error_count),
2689
+ compaction_count: finite(row.compaction_count),
2690
+ productive: Boolean(row.productive),
2691
+ first_pass: Boolean(row.first_pass ?? row.one_shot),
2692
+ resume_command: resumeCommandFor(row.source, row.session_id),
2693
+ };
2694
+ }
2695
+
2696
+ // Claude writes several on-disk files for one logical session (resumes and
2697
+ // sub-agent sidechains) that all carry the same session id, so scanning yields
2698
+ // multiple rows sharing an identical session_hash. Merge those fragments into
2699
+ // one resumable session for the browser: sum the (non-overlapping) per-file
2700
+ // token/turn counts, span the timestamps, and keep the agent-authored title.
2701
+ // This also gives the UI a stable, unique key per row.
2702
+ function mergeSessionFragments(rows) {
2703
+ const byHash = new Map();
2704
+ for (const row of rows || []) {
2705
+ const key = row.session_hash;
2706
+ const cur = byHash.get(key);
2707
+ if (!cur) {
2708
+ byHash.set(key, {
2709
+ ...row,
2710
+ tokens: row.tokens && typeof row.tokens === "object" ? { ...row.tokens } : emptyTotals(),
2711
+ model_usage: normalizeModelUsageRows(row.model_usage),
2712
+ performance: normalizePerformance(row.performance),
2713
+ _repr_tokens: finite(row.total_tokens),
2714
+ });
2715
+ continue;
2716
+ }
2717
+ cur.turns = finite(cur.turns) + finite(row.turns);
2718
+ cur.edit_turns = finite(cur.edit_turns) + finite(row.edit_turns);
2719
+ cur.retry_turns = finite(cur.retry_turns) + finite(row.retry_turns);
2720
+ cur.performance = mergePerformance(cur.performance, row.performance);
2721
+ cur.subagent_calls = finite(cur.subagent_calls) + finite(row.subagent_calls);
2722
+ addTotals(cur.tokens, row.tokens);
2723
+ if (Array.isArray(row.usage_buckets)) {
2724
+ cur.usage_buckets = [...(cur.usage_buckets || []), ...row.usage_buckets];
2725
+ }
2726
+ cur.model_usage = normalizeModelUsageRows([
2727
+ ...(cur.model_usage || []),
2728
+ ...(row.model_usage || []),
2729
+ ]);
2730
+ cur.total_tokens = finite(cur.total_tokens) + finite(row.total_tokens);
2731
+ if (Number.isFinite(row.session_store_bytes)) cur.session_store_bytes = finite(cur.session_store_bytes) + row.session_store_bytes;
2732
+ cur.cost_usd = finite(cur.cost_usd) + finite(row.cost_usd);
2733
+ cur.provider_cost_usd = finite(cur.provider_cost_usd) + finite(row.provider_cost_usd);
2734
+ cur.usage_events = finite(cur.usage_events) + finite(row.usage_events);
2735
+ cur.model_calls = finite(cur.model_calls) + finite(row.model_calls);
2736
+ cur.api_duration_ms = finite(cur.api_duration_ms) + finite(row.api_duration_ms);
2737
+ cur.tool_calls = finite(cur.tool_calls) + finite(row.tool_calls);
2738
+ cur.tool_failures = finite(cur.tool_failures) + finite(row.tool_failures);
2739
+ cur.error_count = finite(cur.error_count) + finite(row.error_count);
2740
+ cur.compaction_count = finite(cur.compaction_count) + finite(row.compaction_count);
2741
+ cur.context_tokens_used = Math.max(finite(cur.context_tokens_used), finite(row.context_tokens_used));
2742
+ cur.context_window_tokens = Math.max(finite(cur.context_window_tokens), finite(row.context_window_tokens));
2743
+ cur.context_usage_percent = Math.max(finite(cur.context_usage_percent), finite(row.context_usage_percent));
2744
+ cur.usage_is_incomplete = Boolean(cur.usage_is_incomplete) || Boolean(row.usage_is_incomplete);
2745
+ cur.cost_is_partial = Boolean(cur.cost_is_partial) || Boolean(row.cost_is_partial);
2746
+ if (cur.usage_precision !== row.usage_precision) cur.usage_precision = "mixed";
2747
+ if (cur.cost_source !== row.cost_source) cur.cost_source = "mixed";
2748
+ cur.productive = Boolean(cur.productive) || Boolean(row.productive);
2749
+ cur.active_ms = finite(cur.active_ms) + finite(row.active_ms);
2750
+ if (!cur.title && row.title) cur.title = row.title;
2751
+ if (!cur.parent_session_id && row.parent_session_id) cur.parent_session_id = row.parent_session_id;
2752
+ if (cur.parent_session_id && row.parent_session_id && cur.parent_session_id !== row.parent_session_id) {
2753
+ cur.parent_session_id = null;
2754
+ cur.parent_link_conflict = true;
2755
+ }
2756
+ if (!cur.forked_from_id && row.forked_from_id) cur.forked_from_id = row.forked_from_id;
2757
+ if (!cur.agent_nickname && row.agent_nickname) cur.agent_nickname = row.agent_nickname;
2758
+ if (!cur.agent_role && row.agent_role) cur.agent_role = row.agent_role;
2759
+ // Legacy records (including Claude) have no per-model usage, so retain
2760
+ // their busiest-fragment model as a display label. Codex model_usage is
2761
+ // merged independently and overrides this representative during repricing.
2762
+ if (finite(row.total_tokens) > finite(cur._repr_tokens)) {
2763
+ cur._repr_tokens = finite(row.total_tokens);
2764
+ if (row.model && row.model !== "unknown") cur.model = row.model;
2765
+ // Project needs its own guard: a subagent running in a git worktree has
2766
+ // that throwaway directory as its cwd, so the busiest fragment can label
2767
+ // the whole session with a temp name like "agent-a3cb8089a11d3471a" and
2768
+ // point project_ref at a directory that no longer exists. Only let a
2769
+ // worktree fragment name the session when nothing better is available.
2770
+ if (!isWorktreeRef(row.project_ref) || isWorktreeRef(cur.project_ref)) {
2771
+ cur.project_key = row.project_key;
2772
+ cur.project_ref = row.project_ref;
2773
+ }
2774
+ }
2775
+ if (row.started_at && (!cur.started_at || row.started_at < cur.started_at)) cur.started_at = row.started_at;
2776
+ if (row.ended_at && (!cur.ended_at || row.ended_at > cur.ended_at)) cur.ended_at = row.ended_at;
2777
+ }
2778
+ const merged = [];
2779
+ for (const row of byHash.values()) {
2780
+ delete row._repr_tokens;
2781
+ // Active time is additive across fragments (see IDLE_GAP_MS); the
2782
+ // wall-clock span between first and last line is not.
2783
+ row.duration_ms = finite(row.active_ms);
2784
+ row.first_pass = finite(row.edit_turns) === 1 && finite(row.retry_turns) === 0;
2785
+ row.one_shot = row.first_pass;
2786
+ // Only a complete per-model breakdown can reprice merged usage safely.
2787
+ // Claude fragments may use different models: their summed cost is exact,
2788
+ // while charging all tokens at the representative model changes that sum.
2789
+ if (row.model_usage.length > 0) repriceSessionRecord(row);
2790
+ else row.cost_per_edit = row.edit_turns > 0 ? finite(row.cost_usd) / row.edit_turns : null;
2791
+ merged.push(row);
2792
+ }
2793
+ return merged;
2794
+ }
2795
+
2796
+ // Attach exact Codex/ZCode parent→child usage without changing the
2797
+ // authoritative per-session total_tokens field. Combined fields are derived
2798
+ // views only, so summing total_tokens across all rows still equals the global
2799
+ // usage ledger. ZCode joins the same lineage pass: its subagent/workflow
2800
+ // children carry parent_session_id from the session table, so the browser can
2801
+ // nest them under their parent and count them as its subagents.
2802
+ function annotateThreadUsage(rows) {
2803
+ const byId = new Map();
2804
+ const childrenById = new Map();
2805
+ const linkedParentById = new Map();
2806
+ const identity = (row, id = row.session_id) => `${row.source}\u0000${id}`;
2807
+
2808
+ for (const row of rows || []) {
2809
+ if ((row?.source !== "codex" && row?.source !== "zcode" && row?.source !== "opencode") || typeof row.session_id !== "string" || !row.session_id) continue;
2810
+ const existing = byId.get(identity(row));
2811
+ if (existing && existing !== row) {
2812
+ existing.parent_link_conflict = true;
2813
+ row.parent_link_conflict = true;
2814
+ continue;
2815
+ }
2816
+ byId.set(identity(row), row);
2817
+ }
2818
+
2819
+ function hasParentCycle(start) {
2820
+ const seen = new Set();
2821
+ let current = start;
2822
+ while (current?.parent_session_id && byId.has(identity(current, current.parent_session_id))) {
2823
+ if (seen.has(identity(current)) || current.parent_session_id === current.session_id) return true;
2824
+ seen.add(identity(current));
2825
+ current = byId.get(identity(current, current.parent_session_id));
2826
+ }
2827
+ return false;
2828
+ }
2829
+
2830
+ for (const row of byId.values()) {
2831
+ const parentId = typeof row.parent_session_id === "string" ? row.parent_session_id.trim() : "";
2832
+ if (!parentId) continue;
2833
+ const parentKey = identity(row, parentId);
2834
+ if (row.parent_link_conflict || hasParentCycle(row)) {
2835
+ row.parent_link_conflict = true;
2836
+ continue;
2837
+ }
2838
+ if (!byId.has(parentKey)) {
2839
+ row.orphaned_subagent = true;
2840
+ continue;
2841
+ }
2842
+ const children = childrenById.get(parentKey) || [];
2843
+ children.push(row);
2844
+ childrenById.set(parentKey, children);
2845
+ linkedParentById.set(identity(row), parentKey);
2846
+ }
2847
+
2848
+ const memo = new Map();
2849
+ function aggregate(row, visiting = new Set()) {
2850
+ if (memo.has(identity(row))) return memo.get(identity(row));
2851
+ if (visiting.has(identity(row))) {
2852
+ row.parent_link_conflict = true;
2853
+ return { count: 0, tokens: 0, cost: 0 };
2854
+ }
2855
+ const nextVisiting = new Set(visiting);
2856
+ nextVisiting.add(identity(row));
2857
+ let count = 0;
2858
+ let tokens = 0;
2859
+ let cost = 0;
2860
+ for (const child of childrenById.get(identity(row)) || []) {
2861
+ const nested = aggregate(child, nextVisiting);
2862
+ count += 1 + nested.count;
2863
+ tokens += finite(child.total_tokens) + nested.tokens;
2864
+ cost += finite(child.cost_usd) + nested.cost;
2865
+ }
2866
+ const result = { count, tokens, cost };
2867
+ memo.set(identity(row), result);
2868
+ return result;
2869
+ }
2870
+
2871
+ function rootFor(row) {
2872
+ const seen = new Set([identity(row)]);
2873
+ let current = row;
2874
+ while (current && linkedParentById.has(identity(current))) {
2875
+ const linkedParentId = linkedParentById.get(identity(current));
2876
+ if (seen.has(linkedParentId)) {
2877
+ row.parent_link_conflict = true;
2878
+ break;
2879
+ }
2880
+ seen.add(linkedParentId);
2881
+ current = byId.get(linkedParentId);
2882
+ }
2883
+ return current || row;
2884
+ }
2885
+
2886
+ for (const row of rows || []) {
2887
+ const threadAware = (row.source === "codex" || row.source === "zcode" || row.source === "opencode")
2888
+ && typeof row.session_id === "string" && row.session_id;
2889
+ row.own_total_tokens = finite(row.total_tokens);
2890
+ row.own_cost_usd = finite(row.cost_usd);
2891
+ row.direct_subagent_count = threadAware
2892
+ ? (childrenById.get(identity(row)) || []).length
2893
+ : 0;
2894
+ const nested = threadAware
2895
+ ? aggregate(row)
2896
+ : { count: 0, tokens: 0, cost: 0 };
2897
+ row.descendant_subagent_count = nested.count;
2898
+ row.subagent_total_tokens = nested.tokens;
2899
+ row.subagent_cost_usd = nested.cost;
2900
+ row.combined_total_tokens = finite(row.total_tokens) + nested.tokens;
2901
+ row.combined_cost_usd = finite(row.cost_usd) + nested.cost;
2902
+ if (threadAware) {
2903
+ const parent = byId.get(linkedParentById.get(identity(row)));
2904
+ row.parent_session_hash = parent?.session_hash || null;
2905
+ row.root_session_hash = rootFor(row).session_hash || row.session_hash;
2906
+ }
2907
+ }
2908
+ return rows;
2909
+ }
2910
+
2911
+ // Local-only session list for the dashboard session browser. Unlike
2912
+ // summarizeSessions (cloud/CSV safe), this retains session_id + project_ref so
2913
+ // the UI can offer one-click resume. Callers must only expose it over the
2914
+ // local API.
2915
+ function listSessionsForBrowser(sessions, { from = "", to = "", limit = 0, timeZone, offsetMinutes } = {}) {
2916
+ const context = { timeZone, offsetMinutes };
2917
+ const filtered = annotateThreadUsage(mergeSessionFragments(sessions)
2918
+ // Only sessions that actually spent tokens are worth listing. This drops
2919
+ // two kinds of noise: non-session logs under ~/.claude/projects
2920
+ // (skill-injections.jsonl, journal.jsonl, …), and sessions abandoned before
2921
+ // the model replied. Both render as "unknown · 0 tokens · $0.00" rows with
2922
+ // no model, no cost and nothing to analyze.
2923
+ .filter((row) => finite(row.total_tokens) > 0)
2924
+ .filter((row) => withinDayRange(row, from, to, context))
2925
+ .map((row) => scopeSessionUsage(row, from, to, context))
2926
+ .filter((row) => !Array.isArray(row.usage_buckets) || finite(row.total_tokens) > 0));
2927
+ filtered.sort((a, b) => String(b.ended_at || "").localeCompare(String(a.ended_at || "")));
2928
+ const cap = Number(limit) > 0 ? Number(limit) : 0;
2929
+ const limited = cap > 0 ? filtered.slice(0, cap) : filtered;
2930
+ return {
2931
+ available: filtered.length > 0,
2932
+ session_count: filtered.length,
2933
+ returned_count: limited.length,
2934
+ skipped_files: finite(sessions?.skippedFiles),
2935
+ sessions: limited.map(toSessionBrowserRow),
2936
+ provenance: {
2937
+ source: "local-session-log",
2938
+ confidence: "observed",
2939
+ privacy: "metadata-only",
2940
+ scope: "local-only",
2941
+ },
2942
+ };
2943
+ }
2944
+
2945
+ function sessionsToCsv(rows) {
2946
+ const columns = ["session_hash", "source", "project_key", "model", "model_usage_json", "started_at", "ended_at", "duration_ms", "turns", "edit_turns", "retry_turns", "subagent_calls", "total_tokens", "cost_usd", "productive", "first_pass", "one_shot"];
2947
+ const escape = (value) => `"${String(value ?? "").replaceAll('"', '""')}"`;
2948
+ const valueFor = (row, key) => key === "model_usage_json"
2949
+ ? JSON.stringify(row.model_usage || [])
2950
+ : row[key];
2951
+ return [columns.join(","), ...(rows || []).map((row) => columns.map((key) => escape(valueFor(row, key))).join(","))].join("\n") + "\n";
2952
+ }
2953
+
2954
+ module.exports = {
2955
+ resolveSessionSidecarPath,
2956
+ sessionHash,
2957
+ scanClaudeSession,
2958
+ scanCodexSession,
2959
+ scanGrokSession,
2960
+ scanZcodeSessions,
2961
+ scanOpencodeSessions,
2962
+ scanKimiSessions,
2963
+ buildSessionAnalytics,
2964
+ summarizeSessions,
2965
+ listSessionsForBrowser,
2966
+ resumeCommandFor,
2967
+ sessionsToCsv,
2968
+ providerRoots,
2969
+ discoverSessionFiles,
2970
+ dedupeClaudeFilesAcrossRoots,
2971
+ analyticsEntryStatKey,
2972
+ };