agentel 0.2.6 → 0.3.0

package/src/archive.js

@@ -4,11 +4,12 @@ const crypto = require("crypto");
 const fs = require("fs");
 const path = require("path");
 const { loadConfig } = require("./config");
-const { normalizeSessionEvents } = require("./canonical-events");
+const { memoryPathInfo, normalizeSessionEvents } = require("./canonical-events");
 const { parserVersionForSource } = require("./parser-versions");
 const { canonicalRepo } = require("./repo");
 const { loadRedactionConfig, loadEnvValues, mergeSummaries, redactText, styleRedactionMarkersForMarkdown } = require("./redaction");
 const { ensureBaseDirs, ensureDir, paths, readJson, writeJson } = require("./paths");
+const sessionStore = require("./session-store");
 
 const SHARED_RAW_SOURCE_CACHE = new Map();
 const ESTIMATED_TOKEN_CHARS = 4;
@@ -21,12 +22,20 @@ const CURSOR_ESTIMATED_TOKEN_RATES = {
   unknown: { inputPerAssistantTurn: 6900, outputPerAssistantTurn: 270 },
   default: { inputPerAssistantTurn: 8400, outputPerAssistantTurn: 230 }
 };
+const ARCHIVE_SCHEMA_VERSION = 6;
+const SESSION_LIST_INDEX_VERSION = 1;
+const OUTPUT_TOKEN_WORK_VERSION = 1;
+const SESSION_OUTCOMES_VERSION = 2;
 
 function archiveRoot(env = process.env) {
   const cfg = loadConfig(env);
   return path.join(cfg.storage.root || paths(env).data, "agentlog");
 }
 
+function sessionListIndexPath(env = process.env) {
+  return path.join(archiveRoot(env), "indexes", "sessions", "sessions.json");
+}
+
 function objectPathForSession(session, env = process.env) {
   const started = new Date(session.startedAt || Date.now());
   const year = String(started.getUTCFullYear()).padStart(4, "0");
@@ -107,9 +116,10 @@ function writeSession(input, env = process.env) {
 
   const session = {
     version: 1,
-    archiveSchemaVersion: 2,
+    archiveSchemaVersion: ARCHIVE_SCHEMA_VERSION,
     sessionId,
     provider,
+    device: archiveDeviceMetadata(cfg.device),
     scopeCanonical: input.scopeCanonical || "",
     repoCanonical,
     repoSource: input.scopeCanonical ? "scope" : repoInfo.source,
@@ -168,6 +178,19 @@ function writeSession(input, env = process.env) {
     }
   );
   session.eventCount = events.length;
+  const toolUsage = collectSessionToolUsage(events);
+  if (toolUsage.callCount) session.toolUsage = toolUsage;
+  const outputTokenWork = computeOutputTokenWork(archivedMessages);
+  if (outputTokenWork && outputTokenWork.totalTokens) session.outputTokenWork = outputTokenWork;
+  const outcomes = collectSessionOutcomes(events);
+  if (outcomes && (outcomes.editToolCalls || outcomes.filesTouched || outcomes.knowledgeCaptures || outcomes.memoryReads || outcomes.memoryWrites || outcomes.memoryLoads)) session.outcomes = outcomes;
+  const artifactsPath = path.join(dir, `session=${sessionId}.artifacts`);
+  const artifacts = captureSessionArtifacts(events, artifactsPath, cfg);
+  if (artifacts.length) {
+    session.artifactsPath = artifactsPath;
+    session.artifacts = artifacts;
+    session.artifactCount = artifacts.length;
+  }
   removeStaleSessionCopies(session, metadataPath, env, { replaceSourcePathCopies: input.replaceSourcePathCopies !== false });
   const rawFiles = copyRawFiles(input, rawPath, env);
   if (rawFiles.length) {
@@ -206,44 +229,166 @@ function writeSession(input, env = process.env) {
     );
   }
 
-  touchManifest(session, { conversationPath, metadataPath, transcriptPath, eventPath, viewPath, rawPath: session.rawPath || "" }, env);
-  return { session, conversationPath, metadataPath, transcriptPath, eventPath, viewPath, rawPath: session.rawPath || "" };
+  touchManifest(session, { conversationPath, metadataPath, transcriptPath, eventPath, viewPath, rawPath: session.rawPath || "", artifactsPath: session.artifactsPath || "" }, env);
+  updateSessionListIndexAfterWrite(session, metadataPath, env, {
+    replaceSourcePathCopies: input.replaceSourcePathCopies !== false
+  });
+  invalidateSessionsSnapshotCache();
+  return { session, conversationPath, metadataPath, transcriptPath, eventPath, viewPath, rawPath: session.rawPath || "", artifactsPath: session.artifactsPath || "" };
+}
+
+function archiveDeviceMetadata(device = {}) {
+  return {
+    id: String(device.id || ""),
+    name: String(device.name || ""),
+    slug: String(device.slug || "")
+  };
 }
 
 function removeStaleSessionCopies(session, metadataPath, env = process.env, options = {}) {
   const root = path.join(archiveRoot(env), "sessions");
   const replaceSourcePathCopies = options.replaceSourcePathCopies !== false;
+  if (_sessionsIndex.completeRootKey === root) {
+    for (const [file, cached] of [..._sessionsIndex.byPath.entries()]) {
+      if (path.resolve(file) === path.resolve(metadataPath)) continue;
+      const metadata = cached?.session;
+      if (!staleSessionMatches(metadata, session, replaceSourcePathCopies)) continue;
+      removeSessionArchiveFiles(metadata, file);
+      forgetSessionIndexPath(file);
+    }
+    return;
+  }
+  _sessionsIndex.byPath.clear();
+  _sessionsIndex.byId.clear();
   walk(root, (file) => {
     if (!file.endsWith(".metadata.json") || path.resolve(file) === path.resolve(metadataPath)) return;
+    const stat = safeStat(file);
+    if (!stat) return;
     const metadata = readJson(file, null);
-    if (!metadata || metadata.provider !== session.provider) return;
-    const sameSession = metadata.sessionId === session.sessionId;
-    const sameSource = replaceSourcePathCopies && session.sourcePath && metadata.sourcePath === session.sourcePath;
-    if (!sameSession && !sameSource) return;
-    safeUnlink(metadata.conversationPath || file.replace(/\.metadata\.json$/, ".conversation.md"));
-    safeUnlink(metadata.transcriptPath || file.replace(/\.metadata\.json$/, ".transcript.jsonl"));
-    safeUnlink(metadata.eventPath || file.replace(/\.metadata\.json$/, ".events.jsonl"));
-    safeUnlink(metadata.viewPath || file.replace(/\.metadata\.json$/, ".view.json"));
-    safeRm(metadata.rawPath || file.replace(/\.metadata\.json$/, ".raw"));
-    safeUnlink(file);
+    if (!metadata) return;
+    const hydrated = hydrateSessionMetadata(file, metadata);
+    if (!staleSessionMatches(hydrated, session, replaceSourcePathCopies)) {
+      rememberSessionIndexEntry(sessionListEntry(hydrated, file, stat));
+      return;
+    }
+    removeSessionArchiveFiles(hydrated, file);
   });
+  _sessionsIndex.completeRootKey = root;
 }
 
-function deleteSessionArchive(session, env = process.env) {
-  if (!session || typeof session !== "object") return false;
-  const metadataPath = session.metadataPath || "";
+function staleSessionMatches(metadata, session, replaceSourcePathCopies) {
+  if (!metadata || metadata.provider !== session.provider) return false;
+  if (metadata.sessionId === session.sessionId) return true;
+  return Boolean(replaceSourcePathCopies && session.sourcePath && metadata.sourcePath === session.sourcePath);
+}
+
+function removeSessionArchiveFiles(session, metadataPath) {
   safeUnlink(session.conversationPath || metadataPath.replace(/\.metadata\.json$/, ".conversation.md"));
   safeUnlink(session.transcriptPath || metadataPath.replace(/\.metadata\.json$/, ".transcript.jsonl"));
   safeUnlink(session.eventPath || metadataPath.replace(/\.metadata\.json$/, ".events.jsonl"));
   safeUnlink(session.viewPath || metadataPath.replace(/\.metadata\.json$/, ".view.json"));
   safeRm(session.rawPath || metadataPath.replace(/\.metadata\.json$/, ".raw"));
+  safeRm(session.artifactsPath || metadataPath.replace(/\.metadata\.json$/, ".artifacts"));
   safeUnlink(metadataPath);
+}
+
+function deleteSessionArchive(session, env = process.env) {
+  if (!session || typeof session !== "object") return false;
+  const metadataPath = session.metadataPath || "";
+  removeSessionArchiveFiles(session, metadataPath);
   if (session.provider && session.sessionId) {
     safeUnlink(path.join(paths(env).revealCache, session.provider, `${session.sessionId}.jsonl`));
   }
+  forgetSessionIndexPath(metadataPath);
+  removeSessionFromListIndex(session, env);
+  invalidateSessionsSnapshotCache();
   return true;
 }
 
+const ARTIFACT_PATH_RE = /(?:\/private)?\/(?:tmp|var\/folders)\/[A-Za-z0-9@%+=:,.~_/-]+\.(?:png|jpe?g|gif|webp|svg|pdf)\b/gi;
+
+function collectArtifactPathRefs(events) {
+  const refs = new Set();
+  for (const event of Array.isArray(events) ? events : []) {
+    const body = event?.body;
+    if (!body) continue;
+    const text = JSON.stringify(body);
+    if (!text || (!text.includes("/tmp/") && !text.includes("/var/folders/"))) continue;
+    let match;
+    ARTIFACT_PATH_RE.lastIndex = 0;
+    while ((match = ARTIFACT_PATH_RE.exec(text))) refs.add(match[0]);
+  }
+  return [...refs];
+}
+
+/**
+ * Copy ephemeral files referenced by tool calls (screenshots and PDFs in
+ * temp directories) into the session archive before the OS deletes them.
+ * Files are content-addressed (sha256-prefixed names) because agents reuse
+ * paths like /tmp/screenshot.png across calls and sessions with different
+ * content. Previously captured artifacts are kept across re-archives even
+ * when the source files are gone or the setting is later disabled.
+ */
+function captureSessionArtifacts(events, artifactsPath, cfg) {
+  const settings = cfg?.artifacts || {};
+  const manifestFile = path.join(artifactsPath, "artifacts.json");
+  const previous = readJson(manifestFile, null);
+  const entries = new Map();
+  let sessionBytes = 0;
+  if (previous && Array.isArray(previous.artifacts)) {
+    for (const item of previous.artifacts) {
+      if (!item || typeof item.name !== "string" || !item.name) continue;
+      entries.set(item.name, item);
+      sessionBytes += Number(item.bytes) || 0;
+    }
+  }
+  if (!settings.enabled) return [...entries.values()];
+  const maxFileBytes = Number(settings.maxFileBytes) > 0 ? Number(settings.maxFileBytes) : 25 * 1024 * 1024;
+  const maxSessionBytes = Number(settings.maxSessionBytes) > 0 ? Number(settings.maxSessionBytes) : 100 * 1024 * 1024;
+  const knownPaths = new Set([...entries.values()].map((item) => `${item.originalPath}:${item.sha256}`));
+  let added = false;
+  for (const ref of collectArtifactPathRefs(events)) {
+    const stat = safeStat(ref);
+    if (!stat || !stat.isFile() || stat.size <= 0 || stat.size > maxFileBytes) continue;
+    if (sessionBytes + stat.size > maxSessionBytes) continue;
+    let content;
+    try {
+      content = fs.readFileSync(ref);
+    } catch {
+      continue;
+    }
+    const sha256 = crypto.createHash("sha256").update(content).digest("hex");
+    if (knownPaths.has(`${ref}:${sha256}`)) continue;
+    const name = `${sha256.slice(0, 16)}${path.extname(ref).toLowerCase()}`;
+    const existing = entries.get(name);
+    if (existing) {
+      knownPaths.add(`${ref}:${sha256}`);
+      continue;
+    }
+    try {
+      ensureDir(artifactsPath);
+      fs.writeFileSync(path.join(artifactsPath, name), content, { mode: 0o600 });
+    } catch {
+      continue;
+    }
+    entries.set(name, {
+      name,
+      originalPath: ref,
+      bytes: content.length,
+      sha256,
+      capturedAt: new Date().toISOString()
+    });
+    knownPaths.add(`${ref}:${sha256}`);
+    sessionBytes += content.length;
+    added = true;
+  }
+  if (added || (entries.size && !previous)) {
+    ensureDir(artifactsPath);
+    writeJson(manifestFile, { version: 1, artifacts: [...entries.values()] });
+  }
+  return [...entries.values()];
+}
+
 function copyRawFiles(input, rawPath, env = process.env) {
   const files = rawSourceFiles(input);
   const references = rawReferences(input);
@@ -406,7 +551,20 @@ function safeRawFilename(value) {
 }
 
 function fileSha256(file) {
-  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+  // Hash in fixed-size chunks; raw session sources can be hundreds of MB and
+  // readFileSync would hold the whole file in memory just to hash it.
+  const hash = crypto.createHash("sha256");
+  const fd = fs.openSync(file, "r");
+  try {
+    const buffer = Buffer.allocUnsafe(1024 * 1024);
+    let bytes = 0;
+    while ((bytes = fs.readSync(fd, buffer, 0, buffer.length, null)) > 0) {
+      hash.update(buffer.subarray(0, bytes));
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  return hash.digest("hex");
 }
 
 function safeUnlink(file) {
@@ -452,6 +610,8 @@ function hasStructuredMetadata(metadata) {
     (Array.isArray(metadata?.toolCalls) && metadata.toolCalls.length) ||
       metadata?.toolResult ||
       metadata?.eventType ||
+      (Array.isArray(metadata?.attachments) && metadata.attachments.length) ||
+      (Array.isArray(metadata?.assetPointers) && metadata.assetPointers.length) ||
       metadata?.parserVersion
   );
 }
@@ -528,7 +688,8 @@ function decodeSegment(value) {
 
 const _sessionsIndex = {
   byPath: new Map(),
-  byId: new Map()
+  byId: new Map(),
+  completeRootKey: ""
 };
 
 function hydrateSessionMetadata(file, metadata) {
@@ -541,10 +702,59 @@ function hydrateSessionMetadata(file, metadata) {
   return { ...metadata, conversationPath, metadataPath: file, transcriptPath, eventPath, viewPath, rawPath };
 }
 
+// TTL cache for the archive snapshot. The web viewer fires several
+// list-derived endpoints while users move between history/stats/projects; keep
+// the hydrated metadata snapshot warm long enough for that browsing session to
+// feel instant. Import/write paths in this process invalidate explicitly via
+// `invalidateSessionsSnapshotCache()`.
+const SNAPSHOT_CACHE_TTL_MS = 15000;
+const _snapshotCache = {
+  rootKey: "",
+  snapshot: null,
+  takenAtMs: 0
+};
+
 function listSessions(env = process.env) {
+  return listSessionsSnapshot(env).sessions;
+}
+
+function cachedListSessionsSnapshot(env = process.env) {
+  const rootKey = path.join(archiveRoot(env), "sessions");
+  const now = Date.now();
+  if (
+    _snapshotCache.snapshot &&
+    _snapshotCache.rootKey === rootKey &&
+    now - _snapshotCache.takenAtMs < SNAPSHOT_CACHE_TTL_MS
+  ) {
+    return _snapshotCache.snapshot;
+  }
+  const snapshot = listSessionsSnapshot(env);
+  _snapshotCache.rootKey = rootKey;
+  _snapshotCache.snapshot = snapshot;
+  _snapshotCache.takenAtMs = now;
+  return snapshot;
+}
+
+function invalidateSessionsSnapshotCache() {
+  _snapshotCache.rootKey = "";
+  _snapshotCache.snapshot = null;
+  _snapshotCache.takenAtMs = 0;
+}
+
+function listSessionsSnapshot(env = process.env) {
+  return readSessionListIndex(env) || rebuildSessionListIndex(env);
+}
+
+/**
+ * Walk the archive once and return both the hydrated session list and a
+ * fingerprint summarizing the snapshot. The result is persisted as a derived
+ * session-list index so steady-state web reads can avoid using the filesystem
+ * as a query engine.
+ */
+function rebuildSessionListIndex(env = process.env) {
   const root = path.join(archiveRoot(env), "sessions");
   const seen = new Set();
-  const sessions = [];
+  const entries = [];
   walk(root, (file) => {
     if (!file.endsWith(".metadata.json")) return;
     seen.add(file);
@@ -552,15 +762,14 @@ function listSessions(env = process.env) {
     try { stat = fs.statSync(file); } catch { return; }
     const cached = _sessionsIndex.byPath.get(file);
     if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
-      sessions.push(cached.session);
+      entries.push(sessionListEntry(cached.session, file, stat));
       return;
     }
     const metadata = readJson(file, null);
     if (!metadata) return;
     const session = hydrateSessionMetadata(file, metadata);
-    _sessionsIndex.byPath.set(file, { mtimeMs: stat.mtimeMs, size: stat.size, session });
-    if (session.sessionId) _sessionsIndex.byId.set(session.sessionId, file);
-    sessions.push(session);
+    rememberSessionIndexEntry(sessionListEntry(session, file, stat));
+    entries.push(sessionListEntry(session, file, stat));
   });
   for (const key of [..._sessionsIndex.byPath.keys()]) {
     if (!seen.has(key)) {
@@ -569,7 +778,341 @@ function listSessions(env = process.env) {
       _sessionsIndex.byPath.delete(key);
     }
   }
-  return sessions.sort((a, b) => String(b.startedAt).localeCompare(String(a.startedAt)));
+  _sessionsIndex.completeRootKey = root;
+  const snapshot = snapshotFromSessionListEntries(entries);
+  writeSessionListIndex(snapshot, env);
+  return snapshot;
+}
+
+function readSessionListIndex(env = process.env) {
+  const root = archiveRoot(env);
+  // Fast path: SQLite store. Indexed reads, sub-millisecond. Stat-validate
+  // each row against the on-disk metadata.json file — if anything drifted
+  // (mtime/size differ, or the file is gone) we treat the cache as stale
+  // and let the caller rebuild from a filesystem walk. The stat-check is
+  // bounded I/O (~50-80ms for 4k files) and only runs on cold reads outside
+  // the snapshot TTL.
+  const fromSqlite = sessionStore.readAllSessions(root);
+  if (fromSqlite && fromSqlite.length) {
+    const entries = fromSqlite.map(normalizeSessionListEntry).filter(Boolean);
+    if (entries.length && sessionListEntriesMatchDisk(entries) && sessionListEntriesCoverManifest(entries, root)) {
+      const fingerprint = sessionListFingerprint(entries);
+      replaceSessionMemoryIndex(entries, path.join(root, "sessions"));
+      return snapshotFromSessionListEntries(entries, { fingerprint, fromIndex: true });
+    }
+    return null;
+  }
+  // One-time migration: legacy JSON index. If present and valid, hydrate the
+  // SQLite store from it so subsequent reads take the fast path. The JSON
+  // file is left in place but no longer written.
+  const file = sessionListIndexPath(env);
+  let payload = null;
+  try {
+    payload = readJson(file, null);
+  } catch {
+    return null;
+  }
+  if (!payload || payload.version !== SESSION_LIST_INDEX_VERSION || payload.archiveRoot !== root) return null;
+  const entries = Array.isArray(payload.entries) ? payload.entries.map(normalizeSessionListEntry).filter(Boolean) : [];
+  if (entries.length !== Number(payload.count || 0)) return null;
+  const fingerprint = sessionListFingerprint(entries);
+  if (payload.fingerprint && payload.fingerprint !== fingerprint) return null;
+  if (!sessionListEntriesMatchDisk(entries) || !sessionListEntriesCoverManifest(entries, root)) return null;
+  // Best-effort migrate; if SQLite is unavailable we still serve from memory.
+  sessionStore.replaceAllSessions(entries, root);
+  replaceSessionMemoryIndex(entries, path.join(root, "sessions"));
+  return snapshotFromSessionListEntries(entries, {
+    fingerprint,
+    generatedAt: payload.generatedAt || "",
+    fromIndex: true
+  });
+}
+
+function writeSessionListIndex(snapshot, env = process.env) {
+  const entries = Array.isArray(snapshot?.entries) ? snapshot.entries.map(normalizeSessionListEntry).filter(Boolean) : [];
+  const next = snapshotFromSessionListEntries(entries);
+  const root = archiveRoot(env);
+  // Bulk replace in the SQLite store. Used after filesystem rebuild.
+  if (sessionStore.replaceAllSessions(next.entries, root)) return true;
+  // Fallback: write the legacy JSON file so a setup without better-sqlite3
+  // still has a persistent session index.
+  try {
+    writeJson(sessionListIndexPath(env), {
+      version: SESSION_LIST_INDEX_VERSION,
+      archiveRoot: root,
+      generatedAt: new Date().toISOString(),
+      fingerprint: next.fingerprint,
+      count: next.count,
+      maxMtimeMs: next.maxMtimeMs,
+      entries: next.entries
+    }, { pretty: false });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function snapshotFromSessionListEntries(entries, options = {}) {
+  const normalized = (Array.isArray(entries) ? entries : []).map(normalizeSessionListEntry).filter(Boolean);
+  normalized.sort((a, b) => String(b.session.startedAt).localeCompare(String(a.session.startedAt)));
+  const sessions = normalized.map((entry) => entry.session);
+  return {
+    sessions,
+    entries: normalized,
+    fingerprint: options.fingerprint || sessionListFingerprint(normalized),
+    count: normalized.length,
+    maxMtimeMs: normalized.reduce((max, entry) => Math.max(max, entry.mtimeMs || 0), 0),
+    generatedAt: options.generatedAt || "",
+    fromIndex: Boolean(options.fromIndex)
+  };
+}
+
+/**
+ * Returns true iff every entry's stored (mtime, size) still matches the
+ * current on-disk metadata.json. Out-of-band file edits (manual changes,
+ * file restores from backup) invalidate via mtime/size drift. Missing
+ * files also invalidate (the rebuild path will drop them).
+ *
+ * Intentionally returns false on the first mismatch — the cache is only
+ * useful if it's wholly accurate; partial freshness still requires a walk.
+ */
+function sessionListEntriesMatchDisk(entries) {
+  for (const entry of entries) {
+    if (!entry?.metadataPath) return false;
+    const stat = safeStat(entry.metadataPath);
+    if (!stat) return false;
+    if (Math.trunc(stat.mtimeMs) !== Math.trunc(entry.mtimeMs)) return false;
+    if (Number(stat.size) !== Number(entry.size)) return false;
+  }
+  return true;
+}
+
+function sessionListEntriesCoverManifest(entries, root) {
+  const manifest = readJson(path.join(root, "sessions", "manifest.json"), null);
+  if (!manifest || !Array.isArray(manifest.sessions) || !manifest.sessions.length) return true;
+
+  const indexedPaths = new Set(
+    entries
+      .map((entry) => entry?.metadataPath || "")
+      .filter(Boolean)
+      .map((file) => path.resolve(file))
+  );
+  let liveManifestPathCount = 0;
+  for (const item of manifest.sessions) {
+    const metadataPath = item?.metadataPath || "";
+    if (!metadataPath || !safeStat(metadataPath)) continue;
+    liveManifestPathCount += 1;
+    if (!indexedPaths.has(path.resolve(metadataPath))) return false;
+  }
+  return liveManifestPathCount <= entries.length;
+}
+
+function sessionListFingerprint(entries) {
+  const rows = (Array.isArray(entries) ? entries : []).map(normalizeSessionListEntry).filter(Boolean);
+  if (!rows.length) return "0-0-0";
+  let mtimeXor = 0n;
+  let sizeXor = 0n;
+  const hash = crypto.createHash("sha1");
+  for (const entry of [...rows].sort((a, b) => a.metadataPath.localeCompare(b.metadataPath))) {
+    const mtime = Math.trunc(entry.mtimeMs || 0);
+    const size = Math.trunc(entry.size || 0);
+    mtimeXor ^= BigInt(mtime);
+    sizeXor ^= BigInt(size);
+    hash.update(entry.metadataPath).update("\0").update(String(mtime)).update("\0").update(String(size)).update("\0");
+  }
+  return `${rows.length.toString(36)}-${mtimeXor.toString(16)}-${sizeXor.toString(16)}-${hash.digest("base64url").slice(0, 16)}`;
+}
+
+function sessionListEntry(session, metadataPath, stat) {
+  return normalizeSessionListEntry({
+    metadataPath,
+    mtimeMs: stat?.mtimeMs || 0,
+    size: stat?.size || 0,
+    session
+  });
+}
+
+function normalizeSessionListEntry(entry) {
+  if (!entry || typeof entry !== "object" || !entry.session || typeof entry.session !== "object") return null;
+  const metadataPath = entry.metadataPath || entry.session.metadataPath || "";
+  if (!metadataPath) return null;
+  const session = hydrateSessionListIndexMetadata(metadataPath, entry.session);
+  return {
+    metadataPath,
+    mtimeMs: Number(entry.mtimeMs || 0),
+    size: Number(entry.size || 0),
+    session
+  };
+}
+
+function hydrateSessionListIndexMetadata(file, metadata) {
+  return {
+    ...metadata,
+    conversationPath: metadata.conversationPath || file.replace(/\.metadata\.json$/, ".conversation.md"),
+    metadataPath: file,
+    transcriptPath: metadata.transcriptPath || file.replace(/\.metadata\.json$/, ".transcript.jsonl"),
+    eventPath: metadata.eventPath || file.replace(/\.metadata\.json$/, ".events.jsonl"),
+    viewPath: metadata.viewPath || file.replace(/\.metadata\.json$/, ".view.json"),
+    rawPath: metadata.rawPath || ""
+  };
+}
+
+function rememberSessionIndexEntry(entry) {
+  const normalized = normalizeSessionListEntry(entry);
+  if (!normalized) return;
+  _sessionsIndex.byPath.set(normalized.metadataPath, {
+    mtimeMs: normalized.mtimeMs,
+    size: normalized.size,
+    session: normalized.session
+  });
+  if (normalized.session.sessionId) _sessionsIndex.byId.set(normalized.session.sessionId, normalized.metadataPath);
+}
+
+function replaceSessionMemoryIndex(entries, rootKey = "") {
+  _sessionsIndex.byPath.clear();
+  _sessionsIndex.byId.clear();
+  _sessionsIndex.completeRootKey = rootKey;
+  for (const entry of entries) rememberSessionIndexEntry(entry);
+}
+
+function forgetSessionIndexPath(metadataPath) {
+  if (!metadataPath) return;
+  const existing = _sessionsIndex.byPath.get(metadataPath);
+  if (existing?.session?.sessionId) _sessionsIndex.byId.delete(existing.session.sessionId);
+  _sessionsIndex.byPath.delete(metadataPath);
+}
+
+function updateSessionListIndexAfterWrite(session, metadataPath, env = process.env, options = {}) {
+  const stat = safeStat(metadataPath);
+  if (!stat) return;
+  const sourcePath = session.sourcePath || "";
+  const replaceSourcePathCopies = options.replaceSourcePathCopies !== false;
+  const resolvedMetadataPath = path.resolve(metadataPath);
+  const supersededSessionIds = new Set();
+  const supersededMetadataPaths = new Set();
+  for (const [file, cached] of [..._sessionsIndex.byPath.entries()]) {
+    const existing = cached?.session || {};
+    if (path.resolve(file) === resolvedMetadataPath) {
+      forgetSessionIndexPath(file);
+      // When the same metadata file is being rewritten under a *different*
+      // session id (e.g. a re-import that recomputed stableSessionId after
+      // a parser change), the prior row keyed on existing.sessionId would
+      // otherwise stay orphaned in SQLite — the upsert below inserts under
+      // the new id and the per-metadata-path delete is skipped because the
+      // path matches the incoming entry. Capture the old session id here
+      // so the SQLite delete loop evicts it explicitly.
+      if (existing.sessionId && existing.sessionId !== session.sessionId) {
+        supersededSessionIds.add(existing.sessionId);
+      }
+      supersededMetadataPaths.add(file);
+      continue;
+    }
+    if (existing.sessionId && existing.sessionId === session.sessionId) {
+      forgetSessionIndexPath(file);
+      if (existing.sessionId) supersededSessionIds.add(existing.sessionId);
+      supersededMetadataPaths.add(file);
+      continue;
+    }
+    if (replaceSourcePathCopies && sourcePath && existing.provider === session.provider && existing.sourcePath === sourcePath) {
+      forgetSessionIndexPath(file);
+      if (existing.sessionId) supersededSessionIds.add(existing.sessionId);
+      supersededMetadataPaths.add(file);
+    }
+  }
+  const nextEntry = sessionListEntry(session, metadataPath, stat);
+  rememberSessionIndexEntry(nextEntry);
+  // Fast path: incremental SQLite upsert + targeted deletes for superseded
+  // rows. Avoids reading the whole index just to add one row. Includes a
+  // SQL-level delete for (provider, sourcePath) since the in-memory loop
+  // above only knows about entries currently cached in this process — rows
+  // from prior process lifetimes still live in the SQLite store and would
+  // otherwise survive.
+  const root = archiveRoot(env);
+  if (sessionStore.storeAvailable(root)) {
+    for (const id of supersededSessionIds) {
+      if (id && id !== session.sessionId) sessionStore.deleteSession({ sessionId: id }, root);
+    }
+    for (const file of supersededMetadataPaths) {
+      if (file && path.resolve(file) !== resolvedMetadataPath) sessionStore.deleteSession({ metadataPath: file }, root);
+    }
+    if (replaceSourcePathCopies && sourcePath) {
+      sessionStore.deleteSameSourceSessions({
+        provider: session.provider || "",
+        sourcePath,
+        keepSessionId: session.sessionId || ""
+      }, root);
+    }
+    sessionStore.upsertSession(nextEntry, root);
+    return;
+  }
+  // Legacy JSON fallback for setups without better-sqlite3.
+  const indexPath = sessionListIndexPath(env);
+  if (!fs.existsSync(indexPath)) return;
+  let payload = null;
+  try {
+    payload = readJson(indexPath, null);
+  } catch {
+    return;
+  }
+  if (
+    !payload ||
+    payload.version !== SESSION_LIST_INDEX_VERSION ||
+    payload.archiveRoot !== archiveRoot(env) ||
+    !Array.isArray(payload.entries)
+  ) {
+    return;
+  }
+  const entries = payload.entries
+    .map(normalizeSessionListEntry)
+    .filter(Boolean)
+    .filter((entry) => {
+      const existing = entry.session || {};
+      if (path.resolve(entry.metadataPath) === resolvedMetadataPath) return false;
+      if (existing.sessionId && existing.sessionId === session.sessionId) return false;
+      if (replaceSourcePathCopies && sourcePath && existing.provider === session.provider && existing.sourcePath === sourcePath) return false;
+      return true;
+    });
+  entries.push(nextEntry);
+  writeSessionListIndex({ entries }, env);
+}
+
+function removeSessionFromListIndex(session, env = process.env) {
+  const root = archiveRoot(env);
+  // Fast path: targeted SQLite delete.
+  if (sessionStore.storeAvailable(root)) {
+    sessionStore.deleteSession({
+      sessionId: session.sessionId || "",
+      metadataPath: session.metadataPath || ""
+    }, root);
+    return;
+  }
+  const indexPath = sessionListIndexPath(env);
+  if (!fs.existsSync(indexPath)) return;
+  let payload = null;
+  try {
+    payload = readJson(indexPath, null);
+  } catch {
+    return;
+  }
+  if (
+    !payload ||
+    payload.version !== SESSION_LIST_INDEX_VERSION ||
+    payload.archiveRoot !== archiveRoot(env) ||
+    !Array.isArray(payload.entries)
+  ) {
+    return;
+  }
+  const metadataPath = session.metadataPath || "";
+  const resolvedMetadataPath = metadataPath ? path.resolve(metadataPath) : "";
+  const entries = payload.entries
+    .map(normalizeSessionListEntry)
+    .filter(Boolean)
+    .filter((entry) => {
+      if (resolvedMetadataPath && path.resolve(entry.metadataPath) === resolvedMetadataPath) return false;
+      if (session.sessionId && entry.session.sessionId === session.sessionId) return false;
+      return true;
+    });
+  writeSessionListIndex({ entries }, env);
 }
 
 function findSessionById(sessionId, env = process.env) {
@@ -603,8 +1146,13 @@ function computeSessionUsage(messages) {
   let inputTokens = 0;
   let outputTokens = 0;
   let cacheInputTokens = 0;
+  let cacheCreationInputTokens = 0;
+  let cacheReadInputTokens = 0;
+  let countedCacheInputTokens = 0;
   let reasoningOutputTokens = 0;
+  let countedReasoningOutputTokens = 0;
   let toolUsePromptTokens = 0;
+  let costUsd = 0;
   let maxUndifferentiatedTotalTokens = 0;
   let totalInputTokens = 0;
   let totalOutputTokens = 0;
@@ -638,8 +1186,24 @@ function computeSessionUsage(messages) {
       any = true;
     }
     if (summary.cacheInputTokens > 0) cacheInputTokens += summary.cacheInputTokens;
+    if (summary.cacheCreationInputTokens > 0) cacheCreationInputTokens += summary.cacheCreationInputTokens;
+    if (summary.cacheReadInputTokens > 0) cacheReadInputTokens += summary.cacheReadInputTokens;
+    if (summary.countedCacheInputTokens > 0) countedCacheInputTokens += summary.countedCacheInputTokens;
     if (summary.reasoningOutputTokens > 0) reasoningOutputTokens += summary.reasoningOutputTokens;
+    if (summary.countedReasoningOutputTokens > 0) countedReasoningOutputTokens += summary.countedReasoningOutputTokens;
     if (summary.toolUsePromptTokens > 0) toolUsePromptTokens += summary.toolUsePromptTokens;
+    const messageCostUsd = positiveCostNumber(firstUsageNumber(
+      usage.costUsd,
+      usage.costUSD,
+      usage.cost_usd,
+      usage.totalCostUsd,
+      usage.total_cost_usd,
+      message.metadata?.costUsd,
+      message.metadata?.costUSD,
+      message.metadata?.cost_usd,
+      message.metadata?.cost
+    ));
+    if (messageCostUsd > 0) costUsd += messageCostUsd;
     if (!summary.hasSplitTokens && !summary.hasExtraTokens && summary.hasTotalTokens) {
       maxUndifferentiatedTotalTokens = Math.max(maxUndifferentiatedTotalTokens, summary.totalTokens);
     }
@@ -648,17 +1212,17 @@ function computeSessionUsage(messages) {
   }
   if (Number.isFinite(totalInputTokens) && totalInputTokens > 0) any = true;
   if (Number.isFinite(totalOutputTokens) && totalOutputTokens > 0) any = true;
-  if (reasoningOutputTokens > 0 || toolUsePromptTokens > 0) any = true;
+  if (cacheInputTokens > 0 || reasoningOutputTokens > 0 || toolUsePromptTokens > 0) any = true;
   if (!any && maxUndifferentiatedTotalTokens > 0) {
     inputTokens = maxUndifferentiatedTotalTokens;
     any = true;
   }
   const cumulativeTokens = totalInputTokens + totalOutputTokens;
-  const splitTotalTokens = inputTokens + outputTokens + reasoningOutputTokens + toolUsePromptTokens;
+  const splitTotalTokens = inputTokens + outputTokens + countedCacheInputTokens + countedReasoningOutputTokens + toolUsePromptTokens;
   const finalTotalTokens = splitTotalTokens || cumulativeTokens || maxUndifferentiatedTotalTokens;
   if (!any && finalTotalTokens === 0) return null;
   const result = {
-    inputTokens: inputTokens || totalInputTokens || (!outputTokens && !reasoningOutputTokens && !toolUsePromptTokens && maxUndifferentiatedTotalTokens ? maxUndifferentiatedTotalTokens : 0),
+    inputTokens: inputTokens || totalInputTokens || (!outputTokens && !cacheInputTokens && !reasoningOutputTokens && !toolUsePromptTokens && maxUndifferentiatedTotalTokens ? maxUndifferentiatedTotalTokens : 0),
     outputTokens: outputTokens || totalOutputTokens,
     cacheInputTokens,
     reasoningOutputTokens,
@@ -667,13 +1231,411 @@ function computeSessionUsage(messages) {
     totalInputTokens: totalInputTokens || inputTokens,
     totalOutputTokens: totalOutputTokens || outputTokens
   };
+  if (cacheCreationInputTokens > 0) result.cacheCreationInputTokens = cacheCreationInputTokens;
+  if (cacheReadInputTokens > 0) result.cacheReadInputTokens = cacheReadInputTokens;
+  if (reasoningOutputTokens > 0 && countedReasoningOutputTokens === 0) result.reasoningOutputTokensIncludedInOutput = true;
+  if (cacheInputTokens > 0 && countedCacheInputTokens === 0) result.cacheInputTokensIncludedInInput = true;
   if (estimatedUsageCount > 0 && actualUsageCount === 0) {
     result.estimated = true;
     if (estimationMethods.size === 1) result.estimationMethod = Array.from(estimationMethods)[0];
   }
+  if (costUsd > 0) {
+    result.costUsd = Number(costUsd.toFixed(8));
+    result.currency = "USD";
+    result.costSource = "provider-usage";
+    result.costEstimated = false;
+  }
   return result;
 }
 
+function computeOutputTokenWork(messages) {
+  let textTokens = 0;
+  let toolUseTokens = 0;
+  let reasoningTokens = 0;
+  let unknownTokens = 0;
+  let messageCount = 0;
+  let mixedMessageCount = 0;
+  let estimatedUsageCount = 0;
+  let actualUsageCount = 0;
+  const seenUsageRequests = new Set();
+  for (const message of messages || []) {
+    if (String(message?.role || "").toLowerCase() !== "assistant") continue;
+    const usage = message?.metadata?.usage;
+    if (!usage || typeof usage !== "object") continue;
+    const requestId = String(message.metadata?.requestId || "").trim();
+    if (requestId) {
+      if (seenUsageRequests.has(requestId)) continue;
+      seenUsageRequests.add(requestId);
+    }
+    const summary = usageTokenSummary(usage);
+    if (!summary.hasAny) continue;
+    const output = positiveTokenNumber(summary.outputTokens);
+    const reasoning = positiveTokenNumber(summary.reasoningOutputTokens);
+    if (output <= 0 && reasoning <= 0) continue;
+    messageCount++;
+    if (summary.estimated) estimatedUsageCount++;
+    else actualUsageCount++;
+
+    if (reasoning > 0) reasoningTokens += reasoning;
+    const nonReasoningOutput = Math.max(0, output - (summary.reasoningOutputTokensIncludedInOutput ? reasoning : 0));
+    if (nonReasoningOutput <= 0) continue;
+    const kind = outputTokenWorkKind(message);
+    if (kind === "text") textTokens += nonReasoningOutput;
+    else if (kind === "toolUse") toolUseTokens += nonReasoningOutput;
+    else if (kind === "reasoning") reasoningTokens += nonReasoningOutput;
+    else {
+      unknownTokens += nonReasoningOutput;
+      if (kind === "mixed") mixedMessageCount++;
+    }
+  }
+  const totalTokens = textTokens + toolUseTokens + reasoningTokens + unknownTokens;
+  if (!totalTokens) return null;
+  const knownTokens = textTokens + toolUseTokens + reasoningTokens;
+  const result = {
+    version: OUTPUT_TOKEN_WORK_VERSION,
+    textTokens,
+    toolUseTokens,
+    reasoningTokens,
+    unknownTokens,
+    totalTokens,
+    knownTokens,
+    coverage: Number((knownTokens / totalTokens).toFixed(4)),
+    messageCount
+  };
+  if (mixedMessageCount) result.mixedMessageCount = mixedMessageCount;
+  if (estimatedUsageCount > 0 && actualUsageCount === 0) result.estimated = true;
+  return result;
+}
+
+function outputTokenWorkKind(message) {
+  const metadata = message?.metadata || {};
+  const summaryKind = String(metadata.summaryKind || metadata.summary_kind || "").toLowerCase();
+  if (metadata.supplementary && /^(thinking|reasoning)$/.test(summaryKind)) return "reasoning";
+  if (metadata.supplementary) return "unknown";
+  const hasText = String(message?.content || "").trim().length > 0;
+  const hasTools = Array.isArray(metadata.toolCalls) && metadata.toolCalls.length > 0;
+  if (hasText && hasTools) return "mixed";
+  if (hasTools) return "toolUse";
+  if (hasText) return "text";
+  return "unknown";
+}
+
+function collectSessionOutcomes(events) {
+  let editToolCalls = 0;
+  let knowledgeCaptures = 0;
+  let memoryReads = 0;
+  let memoryWrites = 0;
+  let memoryLoads = 0;
+  const touchedFiles = new Set();
+  const editCallsByEventId = new Map();
+  for (const event of Array.isArray(events) ? events : []) {
+    const kind = String(event?.kind || "");
+    if (kind === "memory.read") {
+      memoryReads++;
+      continue;
+    }
+    if (kind === "memory.write") {
+      memoryWrites++;
+      continue;
+    }
+    if (kind === "memory.loaded") {
+      memoryLoads++;
+      continue;
+    }
+    if (kind === "tool.called") {
+      const call = event?.body?.toolCall || {};
+      const indexed = event?.indexed || {};
+      const rawName = firstStringValue(indexed.toolName, call.name, call.displayName, indexed.title, "tool");
+      const category = normalizeToolUsageCategory(firstStringValue(indexed.toolCategory, call.category, call.rawCategory), rawName);
+      if (category !== "edit") continue;
+      editToolCalls++;
+      const paths = collectToolCallPathCandidates(call, indexed);
+      let capturedKnowledge = false;
+      for (const candidate of paths) {
+        const normalized = normalizeOutcomePath(candidate);
+        if (!normalized) continue;
+        touchedFiles.add(normalized);
+        if (isKnowledgeCapturePath(normalized)) capturedKnowledge = true;
+      }
+      if (event.eventId) editCallsByEventId.set(event.eventId, { capturedKnowledge });
+      continue;
+    }
+    if (kind === "tool.completed") {
+      const parentEventId = String(event.parentEventId || "");
+      const pending = parentEventId ? editCallsByEventId.get(parentEventId) : null;
+      if (!pending || !pending.capturedKnowledge) continue;
+      const status = String(event?.indexed?.status || event?.body?.toolResult?.status || "").toLowerCase();
+      if (status.includes("error") || status.includes("fail")) continue;
+      knowledgeCaptures++;
+    }
+  }
+  return {
+    version: SESSION_OUTCOMES_VERSION,
+    editToolCalls,
+    filesTouched: touchedFiles.size,
+    knowledgeCaptures,
+    memoryReads,
+    memoryWrites,
+    memoryLoads
+  };
+}
+
+const OUTCOME_PATH_ARGUMENT_KEYS = new Set([
+  "path",
+  "paths",
+  "file",
+  "files",
+  "filename",
+  "filenames",
+  "file_path",
+  "filepath",
+  "relative_path",
+  "relativeworkspacepath",
+  "relative_workspace_path",
+  "target",
+  "target_path",
+  "source_path",
+  "destination_path"
+]);
+
+function collectToolCallPathCandidates(call, indexed = {}) {
+  const paths = [];
+  appendOutcomePath(paths, call?.target);
+  appendOutcomePath(paths, indexed?.target);
+  collectPathValues(call?.arguments, "", 0, paths);
+  collectPathValues(call?.input, "", 0, paths);
+  return Array.from(new Set(paths.map(normalizeOutcomePath).filter(Boolean)));
+}
+
+function collectPathValues(value, key = "", depth = 0, out = []) {
+  if (value == null || depth > 5) return out;
+  if (typeof value === "string") {
+    if (isOutcomePathKey(key)) appendOutcomePath(out, value);
+    return out;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectPathValues(item, key, depth + 1, out);
+    return out;
+  }
+  if (typeof value !== "object") return out;
+  for (const [childKey, childValue] of Object.entries(value)) {
+    collectPathValues(childValue, childKey, depth + 1, out);
+  }
+  return out;
+}
+
+function isOutcomePathKey(key) {
+  const normalized = String(key || "").replace(/[^a-z0-9]+/gi, "_").replace(/^_+|_+$/g, "").toLowerCase();
+  return OUTCOME_PATH_ARGUMENT_KEYS.has(normalized);
+}
+
+function appendOutcomePath(out, value) {
+  if (typeof value !== "string") return;
+  const normalized = normalizeOutcomePath(value);
+  if (normalized) out.push(normalized);
+}
+
+function normalizeOutcomePath(value) {
+  const text = String(value || "").trim();
+  if (!text || text.length > 4096) return "";
+  return text.replace(/\\/g, "/").replace(/\/+/g, "/");
+}
+
+function isKnowledgeCapturePath(value) {
+  const normalized = normalizeOutcomePath(value).toLowerCase();
+  if (!normalized) return false;
+  if (memoryPathInfo(normalized)) return true;
+  const base = path.basename(normalized);
+  if (["agents.md", "claude.md", "gemini.md", "skill.md", ".cursorrules", ".windsurfrules", "rules.md", "memory.md"].includes(base)) return true;
+  if (/\/\.(agents|codex|claude)\/skills\//.test(normalized)) return true;
+  if (/\/\.cursor\/rules\//.test(normalized) || /\/\.windsurf\/rules\//.test(normalized)) return true;
+  if (/\/skills\/[^/]+\/skill\.md$/.test(normalized)) return true;
+  if (/\b(adr|adrs|decision|decisions|plan|plans|planning|rfc|rfcs|roadmap|project-rules)\b/.test(normalized) && /\.(md|mdx|rst|txt|adoc|org)$/i.test(base)) return true;
+  return false;
+}
+
+function collectSessionToolUsage(events) {
+  const byTool = new Map();
+  const byCategory = new Map();
+  const bySkill = new Map();
+  const byMcpServer = new Map();
+  const skillByCallId = new Map();
+  let callCount = 0;
+  let completedCount = 0;
+  let errorCount = 0;
+  for (const event of Array.isArray(events) ? events : []) {
+    const kind = String(event?.kind || "");
+    if (kind !== "tool.called" && kind !== "tool.completed") continue;
+    const call = event?.body?.toolCall || {};
+    const result = event?.body?.toolResult || {};
+    const indexed = event?.indexed || {};
+    const rawName = firstStringValue(
+      indexed.toolName,
+      call.name,
+      call.displayName,
+      result.name,
+      result.kind,
+      indexed.title,
+      "tool"
+    );
+    const toolName = normalizeToolUsageName(rawName);
+    const toolLabel = firstStringValue(call.displayName, indexed.title, result.kind, rawName, toolName);
+    const category = normalizeToolUsageCategory(firstStringValue(indexed.toolCategory, call.category, result.category, call.rawCategory, result.rawCategory), toolName);
+    const status = String(indexed.status || call.status || result.status || "").toLowerCase();
+    const callId = firstStringValue(call.id, result.id);
+    const mcpServer = mcpServerFromToolUsage(toolName, category);
+    if (kind === "tool.called") {
+      callCount++;
+      const tool = byTool.get(toolName) || { tool_name: toolName, tool_label: toolLabel, tool_category: category, calls: 0, completed: 0, errors: 0 };
+      tool.calls += 1;
+      tool.tool_label = tool.tool_label || toolLabel;
+      tool.tool_category = tool.tool_category || category;
+      byTool.set(toolName, tool);
+      const categoryEntry = byCategory.get(category) || { tool_category: category, calls: 0, completed: 0, errors: 0 };
+      categoryEntry.calls += 1;
+      byCategory.set(category, categoryEntry);
+      const skill = skillFromToolCall(toolName, call);
+      if (skill) {
+        if (callId) skillByCallId.set(callId, skill);
+        const skillEntry = bySkill.get(skill.skill_name) || { skill_name: skill.skill_name, skill_label: skill.skill_label, calls: 0, completed: 0, errors: 0 };
+        skillEntry.calls += 1;
+        bySkill.set(skill.skill_name, skillEntry);
+      }
+      if (mcpServer) {
+        const serverEntry = byMcpServer.get(mcpServer.server_name) || { server_name: mcpServer.server_name, server_label: mcpServer.server_label, calls: 0, completed: 0, errors: 0 };
+        serverEntry.calls += 1;
+        byMcpServer.set(mcpServer.server_name, serverEntry);
+      }
+    } else if (kind === "tool.completed") {
+      completedCount++;
+      const failed = status.includes("error") || status.includes("fail");
+      if (failed) errorCount++;
+      const tool = byTool.get(toolName) || { tool_name: toolName, tool_label: toolLabel, tool_category: category, calls: 0, completed: 0, errors: 0 };
+      tool.completed += 1;
+      if (failed) tool.errors += 1;
+      byTool.set(toolName, tool);
+      const categoryEntry = byCategory.get(category) || { tool_category: category, calls: 0, completed: 0, errors: 0 };
+      categoryEntry.completed += 1;
+      if (failed) categoryEntry.errors += 1;
+      byCategory.set(category, categoryEntry);
+      const skill = callId ? skillByCallId.get(callId) : null;
+      if (skill) {
+        const skillEntry = bySkill.get(skill.skill_name) || { skill_name: skill.skill_name, skill_label: skill.skill_label, calls: 0, completed: 0, errors: 0 };
+        skillEntry.completed += 1;
+        if (failed) skillEntry.errors += 1;
+        bySkill.set(skill.skill_name, skillEntry);
+      }
+      if (mcpServer) {
+        const serverEntry = byMcpServer.get(mcpServer.server_name) || { server_name: mcpServer.server_name, server_label: mcpServer.server_label, calls: 0, completed: 0, errors: 0 };
+        serverEntry.completed += 1;
+        if (failed) serverEntry.errors += 1;
+        byMcpServer.set(mcpServer.server_name, serverEntry);
+      }
+    }
+  }
+  return {
+    callCount,
+    completedCount,
+    errorCount,
+    byTool: Array.from(byTool.values()).sort((a, b) => b.calls - a.calls || String(a.tool_label).localeCompare(String(b.tool_label))),
+    byCategory: Array.from(byCategory.values()).sort((a, b) => b.calls - a.calls || String(a.tool_category).localeCompare(String(b.tool_category))),
+    bySkill: Array.from(bySkill.values()).sort((a, b) => b.calls - a.calls || String(a.skill_label).localeCompare(String(b.skill_label))),
+    // Some providers only record MCP results (claude.ai connectors, older
+    // Codex apps), so treat completions as a floor for call counts.
+    byMcpServer: Array.from(byMcpServer.values())
+      .map((entry) => ({ ...entry, calls: Math.max(entry.calls, entry.completed) }))
+      .sort((a, b) => b.calls - a.calls || String(a.server_label).localeCompare(String(b.server_label)))
+  };
+}
+
+function firstStringValue(...values) {
+  for (const value of values) {
+    if (typeof value !== "string") continue;
+    const text = value.trim();
+    if (text) return text;
+  }
+  return "";
+}
+
+function normalizeToolUsageName(value) {
+  return String(value || "tool").trim().toLowerCase().replace(/[^a-z0-9._:-]+/g, "_").replace(/^_+|_+$/g, "") || "tool";
+}
+
+const SKILL_TOOL_NAMES = new Set(["skill", "load_skill", "read_skill", "slashcommand", "slash_command"]);
+// Matches skill loads done through file reads (Codex shells out to read
+// <skills root>/<name>/SKILL.md; other agents use Read-style tools).
+const SKILL_FILE_PATH_RE = /[\/\\]skills[\/\\]([A-Za-z0-9._-]+)[\/\\]SKILL\.md/i;
+
+function skillFromToolCall(toolName, call) {
+  if (SKILL_TOOL_NAMES.has(toolName)) {
+    const args = call?.arguments && typeof call.arguments === "object" && !Array.isArray(call.arguments) ? call.arguments : {};
+    const raw = firstStringValue(args.skill, args.skill_name, args.skillName, args.name, args.command).replace(/^\/+/, "").trim();
+    const named = normalizedSkillUsage(raw);
+    if (named) return named;
+  }
+  const candidates = [call?.argument, call?.rawInputSummary, call?.inputPreview, call?.target];
+  const args = call?.arguments;
+  if (args && typeof args === "object" && !Array.isArray(args)) {
+    for (const value of Object.values(args)) {
+      if (typeof value === "string") candidates.push(value);
+    }
+  }
+  for (const text of candidates) {
+    if (typeof text !== "string" || !text.includes("SKILL.md")) continue;
+    const match = SKILL_FILE_PATH_RE.exec(text);
+    if (match) return normalizedSkillUsage(match[1]);
+  }
+  return null;
+}
+
+function normalizedSkillUsage(raw) {
+  const label = String(raw || "").trim();
+  if (!label) return null;
+  const name = label.toLowerCase().replace(/[^a-z0-9._:-]+/g, "_").replace(/^_+|_+$/g, "");
+  if (!name) return null;
+  return { skill_name: name, skill_label: label };
+}
+
+const MCP_GENERIC_TOOL_NAMES = new Set([
+  "mcp",
+  "mcp_tool",
+  "mcp_tool_call",
+  "call_mcp_tool",
+  "list_mcp_resources",
+  "list_mcp_resource_templates",
+  "read_mcp_resource"
+]);
+
+// Connector prefixes used by hosted MCP tool names like "github_fetch_file"
+// (claude.ai connectors, Codex apps) where the server name is not encoded.
+const MCP_CONNECTOR_PREFIX_RE = /^(github|gmail|gcal|gdrive|google_calendar|google_drive|slack|linear|notion|asana|jira|figma|stripe|vercel|supabase|sentry|atlassian)_./;
+
+function mcpServerFromToolUsage(toolName, category) {
+  if (/^mcp__/.test(toolName)) {
+    const server = toolName.split("__").filter(Boolean)[1] || "";
+    return server ? { server_name: server, server_label: server } : null;
+  }
+  if (category !== "mcp") return null;
+  if (!toolName || MCP_GENERIC_TOOL_NAMES.has(toolName) || /^mcp[_-]*$/.test(toolName)) return null;
+  const prefix = MCP_CONNECTOR_PREFIX_RE.exec(toolName);
+  if (prefix) return { server_name: prefix[1], server_label: prefix[1] };
+  return { server_name: toolName, server_label: toolName };
+}
+
+function normalizeToolUsageCategory(category, name) {
+  const raw = String(category || "").trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  if (raw) return raw;
+  const key = normalizeToolUsageName(name);
+  if (key.includes("search") || key.includes("grep") || key.includes("glob")) return "search";
+  if (key.includes("web") || key.includes("browser") || key.includes("url")) return "web";
+  if (key.includes("read") || key.includes("list")) return "read";
+  if (key.includes("edit") || key.includes("write") || key.includes("patch")) return "edit";
+  if (key.includes("bash") || key.includes("shell") || key.includes("command") || key.includes("exec")) return "shell";
+  if (key.includes("task") || key.includes("todo") || key.includes("agent")) return "task";
+  if (key.includes("mcp")) return "mcp";
+  return "tool";
+}
+
 function estimateSessionUsage(messages, options = {}) {
   const provider = String(options.provider || "").toLowerCase();
   if (provider === "cursor") return estimateCursorSessionUsage(messages, options);
@@ -804,6 +1766,7 @@ function messageTokenEstimate(message) {
 function usageTokenSummary(usage) {
   if (!usage || typeof usage !== "object") return emptyUsageTokenSummary();
   const estimated = usage.estimated === true || usage.estimated === "true";
+  const authoritativeTotalTokens = usage.authoritativeTotalTokens === true || usage.authoritative_total_tokens === true;
   const estimationMethod = typeof usage.estimationMethod === "string" && usage.estimationMethod.trim()
     ? usage.estimationMethod.trim()
     : typeof usage.estimation_method === "string" && usage.estimation_method.trim()
@@ -860,36 +1823,59 @@ function usageTokenSummary(usage) {
     usage.total_token_count,
     usage.total
   ));
-  const cacheInputTokens = sumPositiveTokenNumbers(
-    firstUsageNumber(usage.cacheInputTokens, usage.cache_input_tokens),
-    firstUsageNumber(usage.cacheCreationInputTokens, usage.cache_creation_input_tokens),
+  const cacheCreationInputTokens = positiveTokenNumber(firstUsageNumber(usage.cacheCreationInputTokens, usage.cache_creation_input_tokens));
+  const cacheReadInputTokens = sumPositiveTokenNumbers(
     firstUsageNumber(usage.cacheReadInputTokens, usage.cache_read_input_tokens),
-    firstUsageNumber(usage.cacheReadTokens, usage.cache_read_tokens),
+    firstUsageNumber(usage.cacheReadTokens, usage.cache_read_tokens)
+  );
+  const explicitCacheInputTokens = positiveTokenNumber(firstUsageNumber(usage.cacheInputTokens, usage.cache_input_tokens));
+  const otherCacheInputTokens = sumPositiveTokenNumbers(
     firstUsageNumber(usage.cachedContentTokenCount, usage.cached_content_token_count),
     firstUsageNumber(usage.cachedTokens, usage.cached_tokens, usage.cacheTokens, usage.cache_tokens, usage.cached)
   );
+  const cacheInputTokens = explicitCacheInputTokens || (cacheCreationInputTokens + cacheReadInputTokens + otherCacheInputTokens);
+  const cacheInputTokensIncludedInInput =
+    usage.cacheInputTokensIncludedInInput === true ||
+    usage.cache_input_tokens_included_in_input === true ||
+    usage.cacheReadTokensIncludedInInput === true ||
+    usage.cache_read_tokens_included_in_input === true;
+  const countedCacheInputTokens = cacheInputTokensIncludedInInput ? 0 : cacheInputTokens;
   const reasoningOutputTokens = sumPositiveTokenNumbers(
     firstUsageNumber(usage.reasoningOutputTokens, usage.reasoning_output_tokens),
     firstUsageNumber(usage.thoughtsTokens, usage.thoughts_tokens, usage.thoughtsTokenCount, usage.thoughts_token_count),
     firstUsageNumber(usage.reasoningTokens, usage.reasoning_tokens, usage.reasoningTokenCount, usage.reasoning_token_count)
   );
+  const reasoningOutputTokensIncludedInOutput =
+    usage.reasoningOutputTokensIncludedInOutput === true ||
+    usage.reasoning_output_tokens_included_in_output === true ||
+    usage.reasoningTokensIncludedInOutput === true ||
+    usage.reasoning_tokens_included_in_output === true;
+  const countedReasoningOutputTokens = reasoningOutputTokensIncludedInOutput ? 0 : reasoningOutputTokens;
   const toolUsePromptTokens = sumPositiveTokenNumbers(
     firstUsageNumber(usage.toolUsePromptTokens, usage.tool_use_prompt_tokens, usage.toolUsePromptTokenCount, usage.tool_use_prompt_token_count)
   );
-  const extraTokens = cacheInputTokens + reasoningOutputTokens + toolUsePromptTokens;
+  const extraTokens = countedCacheInputTokens + countedReasoningOutputTokens + toolUsePromptTokens;
   const splitTokens = inputTokens + outputTokens;
   const cumulativeTokens = totalInputTokens + totalOutputTokens;
   const categoryTokens = splitTokens + extraTokens;
-  const totalTokens = explicitTotalTokens || categoryTokens
-    ? Math.max(explicitTotalTokens, categoryTokens)
-    : cumulativeTokens;
+  const totalTokens = authoritativeTotalTokens && explicitTotalTokens
+    ? explicitTotalTokens
+    : explicitTotalTokens || categoryTokens
+      ? Math.max(explicitTotalTokens, categoryTokens)
+      : cumulativeTokens;
   return {
     inputTokens,
     outputTokens,
     totalInputTokens,
     totalOutputTokens,
     cacheInputTokens,
+    cacheCreationInputTokens,
+    cacheReadInputTokens,
+    countedCacheInputTokens,
+    cacheInputTokensIncludedInInput,
     reasoningOutputTokens,
+    countedReasoningOutputTokens,
+    reasoningOutputTokensIncludedInOutput,
     toolUsePromptTokens,
     extraTokens,
     totalTokens,
@@ -898,6 +1884,7 @@ function usageTokenSummary(usage) {
     hasExtraTokens: extraTokens > 0,
     hasTotalTokens: explicitTotalTokens > 0,
     hasCumulativeTokens: cumulativeTokens > 0,
+    authoritativeTotalTokens,
     estimated,
     estimationMethod
   };
@@ -910,7 +1897,13 @@ function emptyUsageTokenSummary() {
     totalInputTokens: 0,
     totalOutputTokens: 0,
     cacheInputTokens: 0,
+    cacheCreationInputTokens: 0,
+    cacheReadInputTokens: 0,
+    countedCacheInputTokens: 0,
+    cacheInputTokensIncludedInInput: false,
     reasoningOutputTokens: 0,
+    countedReasoningOutputTokens: 0,
+    reasoningOutputTokensIncludedInOutput: false,
     toolUsePromptTokens: 0,
     extraTokens: 0,
     totalTokens: 0,
@@ -919,6 +1912,7 @@ function emptyUsageTokenSummary() {
     hasExtraTokens: false,
     hasTotalTokens: false,
     hasCumulativeTokens: false,
+    authoritativeTotalTokens: false,
     estimated: false,
     estimationMethod: ""
   };
@@ -938,6 +1932,11 @@ function positiveTokenNumber(value) {
   return Number.isFinite(number) && number > 0 ? number : 0;
 }
 
+function positiveCostNumber(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : 0;
+}
+
 function sumPositiveTokenNumbers(...values) {
   return values.reduce((sum, value) => sum + positiveTokenNumber(value), 0);
 }
@@ -951,9 +1950,15 @@ function sessionSummaryUsage(sessionSummary) {
     firstUsageNumber(usage.cacheInputTokens, usage.cache_input_tokens),
     firstUsageNumber(usage.cacheReadTokens, usage.cache_read_tokens)
   );
-  const totalTokens = positiveTokenNumber(firstUsageNumber(usage.totalTokens, usage.total_tokens, usage.totalTokenCount, usage.total_token_count)) || inputTokens + outputTokens;
+  const cacheInputTokensIncludedInInput =
+    usage.cacheInputTokensIncludedInInput === true ||
+    usage.cache_input_tokens_included_in_input === true ||
+    usage.cacheReadTokensIncludedInInput === true ||
+    usage.cache_read_tokens_included_in_input === true;
+  const countedCacheInputTokens = cacheInputTokensIncludedInInput ? 0 : cacheInputTokens;
+  const totalTokens = positiveTokenNumber(firstUsageNumber(usage.totalTokens, usage.total_tokens, usage.totalTokenCount, usage.total_token_count)) || inputTokens + outputTokens + countedCacheInputTokens;
   if (!inputTokens && !outputTokens && !cacheInputTokens && !totalTokens) return null;
-  return {
+  const result = {
     inputTokens,
     outputTokens,
     cacheInputTokens,
@@ -963,28 +1968,58 @@ function sessionSummaryUsage(sessionSummary) {
     totalInputTokens: inputTokens,
     totalOutputTokens: outputTokens
   };
+  if (usage.authoritativeTotalTokens === true || usage.authoritative_total_tokens === true) result.authoritativeTotalTokens = true;
+  if (cacheInputTokensIncludedInInput) result.cacheInputTokensIncludedInInput = true;
+  return result;
 }
 
 function mergeSessionUsage(primary, secondary) {
   if (!primary && !secondary) return null;
   if (!primary) return secondary;
   if (!secondary) return primary;
+  const totalTokens = secondary.authoritativeTotalTokens
+    ? (secondary.totalTokens || 0)
+    : primary.authoritativeTotalTokens
+      ? (primary.totalTokens || 0)
+      : Math.max(primary.totalTokens || 0, secondary.totalTokens || 0);
   const result = {
     inputTokens: primary.inputTokens || secondary.inputTokens || 0,
     outputTokens: primary.outputTokens || secondary.outputTokens || 0,
     cacheInputTokens: primary.cacheInputTokens || secondary.cacheInputTokens || 0,
     reasoningOutputTokens: primary.reasoningOutputTokens || secondary.reasoningOutputTokens || 0,
     toolUsePromptTokens: primary.toolUsePromptTokens || secondary.toolUsePromptTokens || 0,
-    totalTokens: Math.max(primary.totalTokens || 0, secondary.totalTokens || 0),
+    totalTokens,
     totalInputTokens: primary.totalInputTokens || secondary.totalInputTokens || primary.inputTokens || secondary.inputTokens || 0,
     totalOutputTokens: primary.totalOutputTokens || secondary.totalOutputTokens || primary.outputTokens || secondary.outputTokens || 0
   };
+  if (primary.authoritativeTotalTokens || secondary.authoritativeTotalTokens) {
+    result.authoritativeTotalTokens = true;
+  }
+  if (primary.cacheInputTokensIncludedInInput || secondary.cacheInputTokensIncludedInInput) {
+    result.cacheInputTokensIncludedInInput = true;
+  }
+  if (primary.cacheCreationInputTokens || secondary.cacheCreationInputTokens) {
+    result.cacheCreationInputTokens = primary.cacheCreationInputTokens || secondary.cacheCreationInputTokens || 0;
+  }
+  if (primary.cacheReadInputTokens || secondary.cacheReadInputTokens) {
+    result.cacheReadInputTokens = primary.cacheReadInputTokens || secondary.cacheReadInputTokens || 0;
+  }
+  if (primary.reasoningOutputTokensIncludedInOutput || secondary.reasoningOutputTokensIncludedInOutput) {
+    result.reasoningOutputTokensIncludedInOutput = true;
+  }
   if (primary.estimated && secondary.estimated) {
     result.estimated = true;
     if (primary.estimationMethod && primary.estimationMethod === secondary.estimationMethod) {
       result.estimationMethod = primary.estimationMethod;
     }
   }
+  const costUsd = positiveCostNumber(primary.costUsd) || positiveCostNumber(secondary.costUsd);
+  if (costUsd) {
+    result.costUsd = costUsd;
+    result.currency = primary.currency || secondary.currency || "USD";
+    result.costSource = primary.costSource || secondary.costSource || "provider-usage";
+    result.costEstimated = Boolean(primary.costEstimated && secondary.costEstimated);
+  }
   return result;
 }
 
@@ -1047,7 +2082,7 @@ function readEvents(sessionOrPath) {
 function ensureConversationMarkdown(session, env = process.env) {
   const conversationPath = session.conversationPath || session.metadataPath?.replace(/\.metadata\.json$/, ".conversation.md");
   if (!conversationPath) return "";
-  if (fs.existsSync(conversationPath)) return conversationPath;
+  if (fs.existsSync(conversationPath) && !conversationMarkdownNeedsRefresh(conversationPath, session)) return conversationPath;
   const messages = readTranscript(session.transcriptPath);
   if (!messages.length) return "";
   const events = readEvents(session);
@@ -1060,7 +2095,25 @@ function ensureConversationMarkdown(session, env = process.env) {
   return conversationPath;
 }
 
-const VIEW_SCHEMA_VERSION = 3;
+function conversationMarkdownNeedsRefresh(file, session) {
+  let text = "";
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return false;
+  }
+  if (!conversationRenderVersionMatches(text)) return true;
+  if (session?.provider !== "chatgpt" && session?.sourceType !== "chatgpt-export") return false;
+  return /\uE200[A-Za-z_]*cite\uE202[^\uE201]+\uE201/.test(text);
+}
+
+const VIEW_SCHEMA_VERSION = 9;
+const CONVERSATION_RENDER_VERSION = 2;
+
+function conversationRenderVersionMatches(text) {
+  const match = /^conversation_render_version:\s*"?([^"\n]+)"?\s*$/m.exec(String(text || ""));
+  return Boolean(match && Number(match[1]) === CONVERSATION_RENDER_VERSION);
+}
 
 function sessionViewPathFromMetadata(metadataPath) {
   if (!metadataPath) return "";
@@ -1104,6 +2157,51 @@ function displayTranscriptMessages(messages, time) {
   return messages.map((message) => ({ ...message, timestamp: "" }));
 }
 
+function compactViewTranscriptMessages(messages) {
+  return (messages || []).map(compactViewTranscriptMessage);
+}
+
+function compactViewTranscriptMessage(message) {
+  if (!message || typeof message !== "object") return message;
+  const metadata = compactViewMetadata(message.metadata);
+  if (metadata === message.metadata) return message;
+  return { ...message, metadata };
+}
+
+function compactViewMetadata(metadata) {
+  if (!metadata || typeof metadata !== "object") return metadata;
+  let next = null;
+  if (metadata.toolResult && typeof metadata.toolResult === "object") {
+    next = { ...metadata, toolResult: compactViewToolResult(metadata.toolResult) };
+  }
+  return next || metadata;
+}
+
+function compactViewToolResult(result) {
+  if (!result || typeof result !== "object") return result;
+  const next = { ...result };
+  delete next.output;
+  delete next.text;
+  delete next.content;
+  return next;
+}
+
+function compactViewCanonicalEvents(events) {
+  return (Array.isArray(events) ? events : []).map(compactViewCanonicalEvent);
+}
+
+function compactViewCanonicalEvent(event) {
+  if (!event || typeof event !== "object") return event;
+  const body = event.body && typeof event.body === "object" ? event.body : null;
+  if (!body) return event;
+  const nextBody = { ...body };
+  if (typeof nextBody.text === "string") nextBody.text = "";
+  if (nextBody.toolResult && typeof nextBody.toolResult === "object") {
+    nextBody.toolResult = compactViewToolResult(nextBody.toolResult);
+  }
+  return { ...event, body: nextBody };
+}
+
 function cursorRawTimeMatchesSourceMtime(session, timestamp) {
   const rawFiles = Array.isArray(session?.rawFiles) ? session.rawFiles : [];
   return rawFiles.some((file) => {
@@ -1146,7 +2244,7 @@ function sessionHistoryTime(session) {
 
 function computeSessionView(session, transcriptMessages, canonicalEvents) {
   const time = sessionHistoryTime(session);
-  const display = displayTranscriptMessages(dedupeTranscriptMessages(transcriptMessages || []), time);
+  const display = compactViewTranscriptMessages(displayTranscriptMessages(dedupeTranscriptMessages(transcriptMessages || []), time));
   return {
     view_schema_version: VIEW_SCHEMA_VERSION,
     session_id: session?.sessionId || "",
@@ -1155,7 +2253,7 @@ function computeSessionView(session, transcriptMessages, canonicalEvents) {
     time_status: time.status || "",
     session_summary: session?.sessionSummary || undefined,
     transcript_messages: display,
-    canonical_events: Array.isArray(canonicalEvents) ? canonicalEvents : []
+    canonical_events: compactViewCanonicalEvents(canonicalEvents)
   };
 }
 
@@ -1195,6 +2293,44 @@ function renderConversationMarkdown(session, messages, events = []) {
   const title = session.title || `${session.provider || "agent"} session ${session.sessionId}`;
   const time = sessionHistoryTime(session);
   const displayMessages = displayTranscriptMessages(messages, time);
+  // Index events by messageIndex once so the per-message loop below is O(events)
+  // total instead of O(messages * events) — for huge sessions the naive filter
+  // per message is billions of comparisons.
+  const toolCallsByMessageIndex = new Map();
+  const toolResultsByMessageIndex = new Map();
+  const memoryEventsByMessageIndex = new Map();
+  const eventsById = new Map();
+  for (const event of events) {
+    if (!event || typeof event !== "object") continue;
+    if (event.eventId) eventsById.set(event.eventId, event);
+  }
+  const memoryToolCallEventIds = new Set();
+  const memoryToolResultEventIds = new Set();
+  for (const event of events) {
+    if (!event || typeof event !== "object") continue;
+    if (isMemoryEventKind(event.kind)) {
+      const list = memoryEventsByMessageIndex.get(event.messageIndex);
+      if (list) list.push(event);
+      else memoryEventsByMessageIndex.set(event.messageIndex, [event]);
+      if (event.parentEventId) {
+        memoryToolResultEventIds.add(event.parentEventId);
+        const resultEvent = eventsById.get(event.parentEventId);
+        if (resultEvent?.parentEventId) memoryToolCallEventIds.add(resultEvent.parentEventId);
+      }
+    }
+  }
+  for (const event of events) {
+    if (!event || typeof event !== "object") continue;
+    const bucket = event.kind === "tool.called"
+      ? memoryToolCallEventIds.has(event.eventId) ? null : toolCallsByMessageIndex
+      : event.kind === "tool.completed"
+        ? memoryToolResultEventIds.has(event.eventId) ? null : toolResultsByMessageIndex
+        : null;
+    if (!bucket) continue;
+    const list = bucket.get(event.messageIndex);
+    if (list) list.push(event);
+    else bucket.set(event.messageIndex, [event]);
+  }
   const hasRedactions =
     displayMessages.some((message) => /\[REDACTED(?::|\s+)[^\]\n]+\]/.test(JSON.stringify(message))) ||
     events.some((event) => /\[REDACTED(?::|\s+)[^\]\n]+\]/.test(JSON.stringify(event)));
@@ -1202,6 +2338,9 @@ function renderConversationMarkdown(session, messages, events = []) {
     "---",
     `session_id: ${yamlString(session.sessionId)}`,
     `provider: ${yamlString(session.provider)}`,
+    `device_name: ${yamlString(session.device?.name || "")}`,
+    `device_slug: ${yamlString(session.device?.slug || "")}`,
+    `device_id: ${yamlString(session.device?.id || "")}`,
     `repo: ${yamlString(session.repoCanonical || "")}`,
     `scope: ${yamlString(session.scopeCanonical || "")}`,
     `cwd: ${yamlString(session.cwd || "")}`,
@@ -1215,6 +2354,7 @@ function renderConversationMarkdown(session, messages, events = []) {
     `conversation_kind: ${yamlString(session.conversationKind || "")}`,
     `time_status: ${yamlString(time.status || session.timeStatus || "")}`,
     `archive_schema_version: ${yamlString(session.archiveSchemaVersion || 1)}`,
+    `conversation_render_version: ${yamlString(CONVERSATION_RENDER_VERSION)}`,
     `event_count: ${yamlString(events.length || session.eventCount || 0)}`,
     `parser_versions: ${yamlString(JSON.stringify(session.parserVersions || {}))}`,
     "---",
@@ -1234,24 +2374,168 @@ function renderConversationMarkdown(session, messages, events = []) {
   for (const message of displayMessages) {
     body.push(`## ${roleLabel(message.role)} - ${message.timestamp || "unknown time"}`);
     body.push("");
-    body.push(styleRedactionMarkersForMarkdown(String(message.content || "").trim()));
-    body.push("");
-    for (const event of events.filter((item) => item.messageIndex === message.index && item.kind === "tool.called")) {
+    const suppressMemoryToolContent = String(message.role || "").toLowerCase() === "tool" && memoryEventsByMessageIndex.has(message.index);
+    const content = suppressMemoryToolContent ? "" : styleRedactionMarkersForMarkdown(styleChatGptCitationMarkersForMarkdown(String(message.content || "").trim()));
+    if (content) {
+      body.push(content);
+      body.push("");
+    }
+    const attachmentMarkdown = renderMessageAttachmentsMarkdown(message);
+    if (attachmentMarkdown) {
+      body.push(attachmentMarkdown);
+      body.push("");
+    }
+    for (const event of toolCallsByMessageIndex.get(message.index) || []) {
       body.push(`### Tool Call - ${event.occurredAt || message.timestamp || "unknown time"}`);
       body.push("");
-      body.push(styleRedactionMarkersForMarkdown(String(event.body?.text || event.indexed?.summary || "").trim()));
+      body.push(styleRedactionMarkersForMarkdown(styleChatGptCitationMarkersForMarkdown(String(event.body?.text || event.indexed?.summary || "").trim())));
       body.push("");
     }
-    for (const event of events.filter((item) => item.messageIndex === message.index && item.kind === "tool.completed")) {
+    for (const event of toolResultsByMessageIndex.get(message.index) || []) {
       body.push(`### Tool Result - ${event.occurredAt || message.timestamp || "unknown time"}`);
       body.push("");
-      body.push(styleRedactionMarkersForMarkdown(String(event.indexed?.summary || event.body?.text || "").trim()));
+      body.push(styleRedactionMarkersForMarkdown(styleChatGptCitationMarkersForMarkdown(String(event.indexed?.summary || event.body?.text || "").trim())));
+      body.push("");
+    }
+    for (const event of memoryEventsByMessageIndex.get(message.index) || []) {
+      body.push(`### ${memoryMarkdownHeading(event)} - ${event.occurredAt || message.timestamp || "unknown time"}`);
+      body.push("");
+      body.push(styleRedactionMarkersForMarkdown(styleChatGptCitationMarkersForMarkdown(memoryMarkdownText(event, eventsById))));
       body.push("");
     }
   }
   return `${frontmatter.concat(body).join("\n").trimEnd()}\n`;
 }
 
+function isMemoryEventKind(kind) {
+  return kind === "memory.read" || kind === "memory.write" || kind === "memory.loaded";
+}
+
+function memoryMarkdownHeading(event) {
+  const action = String(event?.indexed?.memoryAction || event?.body?.memory?.action || "").toLowerCase();
+  if (action === "read") return "Memory Read";
+  if (action === "write") return "Memory Write";
+  return "Memory Loaded";
+}
+
+function memoryMarkdownText(event, eventsById = new Map()) {
+  const memory = event?.body?.memory || {};
+  const pathValue = String(event?.indexed?.memoryPath || memory.path || memory.name || "memory").trim();
+  const details = [];
+  if (pathValue) details.push(`Path: ${pathValue}`);
+  if (event?.indexed?.memorySource || memory.source) details.push(`Source: ${event.indexed?.memorySource || memory.source}`);
+  if (event?.indexed?.memoryScope || memory.scope) details.push(`Scope: ${event.indexed?.memoryScope || memory.scope}`);
+  const diff = memoryMarkdownDiff(event, eventsById);
+  const text = details.length ? details.join("\n") : String(event?.body?.text || event?.indexed?.summary || "").trim();
+  return [text, diff].filter(Boolean).join("\n\n");
+}
+
+function memoryMarkdownDiff(event, eventsById = new Map()) {
+  const completedEvent = event?.parentEventId ? eventsById.get(event.parentEventId) : null;
+  const callEvent = completedEvent?.parentEventId ? eventsById.get(completedEvent.parentEventId) : null;
+  const result = completedEvent?.body?.toolResult || {};
+  const call = callEvent?.body?.toolCall || {};
+  const hunks = firstStructuredPatch(result.structuredPatch, call.structuredPatch, call.arguments?.structuredPatch);
+  if (hunks.length) return fencedMarkdown("diff", structuredPatchToDiffText(hunks));
+  const editDiff = editArgumentsToDiffText(call.arguments);
+  if (editDiff) return fencedMarkdown("diff", editDiff);
+  return "";
+}
+
+function firstStructuredPatch(...values) {
+  for (const value of values) {
+    if (Array.isArray(value) && value.length) return value;
+  }
+  return [];
+}
+
+function structuredPatchToDiffText(hunks) {
+  const lines = [];
+  let previousFile = "";
+  for (const hunk of hunks) {
+    const file = String(hunk?.file || "").trim();
+    if (file && file !== previousFile) {
+      lines.push(`--- ${file}`, `+++ ${file}`);
+      previousFile = file;
+    }
+    const oldStart = Number(hunk?.oldStart) || 1;
+    const newStart = Number(hunk?.newStart) || 1;
+    lines.push(`@@ -${oldStart} +${newStart} @@`);
+    for (const raw of Array.isArray(hunk?.lines) ? hunk.lines : []) lines.push(String(raw ?? ""));
+  }
+  return lines.join("\n").trim();
+}
+
+function editArgumentsToDiffText(args) {
+  if (!args || typeof args !== "object" || Array.isArray(args)) return "";
+  const edits = Array.isArray(args.edits) && args.edits.length ? args.edits : [args];
+  const blocks = [];
+  for (const edit of edits) {
+    const oldString = typeof edit?.old_string === "string" ? edit.old_string : "";
+    const newString = typeof edit?.new_string === "string" ? edit.new_string : "";
+    if (!oldString && !newString) continue;
+    blocks.push(simpleDiffText(oldString, newString));
+  }
+  if (blocks.length) return blocks.join("\n");
+  const content = typeof args.content === "string" ? args.content : "";
+  if (!content) return "";
+  return content.split("\n").map((line) => `+${line}`).join("\n");
+}
+
+function simpleDiffText(oldString, newString) {
+  const lines = [];
+  for (const line of String(oldString || "").split("\n")) lines.push(`-${line}`);
+  for (const line of String(newString || "").split("\n")) lines.push(`+${line}`);
+  return lines.join("\n").trim();
+}
+
+function fencedMarkdown(language, value) {
+  const text = String(value || "").trim();
+  if (!text) return "";
+  return `\`\`\`${language}\n${text.replace(/```/g, "`\u200b``")}\n\`\`\``;
+}
+
+function styleChatGptCitationMarkersForMarkdown(value) {
+  return String(value || "").replace(/\uE200([A-Za-z_]*cite)\uE202([^\uE201]+)\uE201/g, (_, kind, ref) => {
+    const label = /file/i.test(String(kind || "")) ? "file citation" : "citation";
+    const text = chatGptCitationParts(ref).join(" ");
+    return text ? `[${label}: ${text}]` : `[${label}]`;
+  });
+}
+
+function chatGptCitationParts(ref) {
+  return String(ref || "").split("\uE202").map((part) => part.trim()).filter(Boolean);
+}
+
+function renderMessageAttachmentsMarkdown(message) {
+  const attachments = Array.isArray(message?.metadata?.attachments) ? message.metadata.attachments : [];
+  const assetPointers = Array.isArray(message?.metadata?.assetPointers) ? message.metadata.assetPointers : [];
+  if (!attachments.length && !assetPointers.length) return "";
+  const lines = ["### Attachments", ""];
+  for (const attachment of attachments) {
+    const name = markdownLine(attachment?.name || attachment?.id || "attachment");
+    const details = [
+      attachment?.mimeType,
+      attachment?.width && attachment?.height ? `${attachment.width}x${attachment.height}` : "",
+      attachment?.size ? `${attachment.size} bytes` : "",
+      attachment?.assetPointer ? `asset ${attachment.assetPointer}` : ""
+    ].filter(Boolean).join(", ");
+    lines.push(`- ${name}${details ? ` (${markdownLine(details)})` : ""}`);
+  }
+  const attachedPointers = new Set(attachments.map((attachment) => attachment?.assetPointer).filter(Boolean));
+  for (const pointer of assetPointers) {
+    if (!pointer?.assetPointer || attachedPointers.has(pointer.assetPointer)) continue;
+    const details = [
+      pointer.contentType,
+      pointer.mimeType,
+      pointer.width && pointer.height ? `${pointer.width}x${pointer.height}` : "",
+      pointer.size ? `${pointer.size} bytes` : ""
+    ].filter(Boolean).join(", ");
+    lines.push(`- ${markdownLine(pointer.assetPointer)}${details ? ` (${markdownLine(details)})` : ""}`);
+  }
+  return lines.join("\n");
+}
+
 function normalizePrecomputedEvents(events, session) {
   return events
     .filter((event) => event && typeof event === "object")
@@ -1315,7 +2599,8 @@ function touchManifest(session, pathsForSession, env = process.env) {
     transcriptPath: pathsForSession.transcriptPath,
     eventPath: pathsForSession.eventPath,
     viewPath: pathsForSession.viewPath || "",
-    rawPath: pathsForSession.rawPath || ""
+    rawPath: pathsForSession.rawPath || "",
+    artifactsPath: pathsForSession.artifactsPath || ""
   });
   writeJson(manifestPath, { sessions: next.sort((a, b) => String(b.startedAt).localeCompare(String(a.startedAt))) });
 }
@@ -1356,6 +2641,8 @@ function walk(dir, visit) {
 
 module.exports = {
   archiveRoot,
+  collectSessionToolUsage,
+  mcpServerFromToolUsage,
   collectSessionModels,
   computeSessionUsage,
   computeSessionView,
@@ -1370,12 +2657,17 @@ module.exports = {
   ensureConversationMarkdown,
   ensureSessionView,
   findSessionById,
+  invalidateSessionsSnapshotCache,
+  isWebChatProvider,
   listSessions,
+  listSessionsSnapshot,
+  cachedListSessionsSnapshot,
   normalizeMessages,
   objectPathForSession,
   readEvents,
   readTranscript,
   renderConversationMarkdown,
+  rebuildSessionListIndex,
   revealSession,
   sessionHistoryTime,
   sessionViewPathForSession,